Getting Started

Earthling UI supports React 18 and 19. Use Node.js 20 or newer for the documented toolchain and CLI.

Install

bash

npm install earthling-ui

Configure Tailwind CSS 4 for your framework, then add these explicit paths to its global stylesheet:

css

@import "tailwindcss";
@import "earthling-ui/index.css";
@import "earthling-ui/themes/dark.css";

The dark stylesheet defines theme-dark. Apply it directly or through a selector:

css

@layer base {
  :root[data-theme="dark"] {
    @apply theme-dark;
  }
}

Import individual component entry points to keep dependency graphs focused:

tsx

import { Button } from "earthling-ui/button";
import { Input } from "earthling-ui/input";

export function SignupForm() {
  return (
    <form className="grid gap-4">
      <Input aria-label="Email" autoComplete="email" type="email" />
      <Button type="submit">Create account</Button>
    </form>
  );
}

Next.js App Router

If create-next-app configured Tailwind, keep its PostCSS setup and add the Earthling imports to app/globals.css or src/app/globals.css.

For a manual Tailwind 4 setup:

bash

npm install -D tailwindcss @tailwindcss/postcss postcss

tsx

// postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

Import the global stylesheet once from the root layout:

tsx

// app/layout.tsx
import "./globals.css";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Earthling entry points include "use client". Server Components may render them normally; add your own client boundary only when your code uses state, effects, handlers, or browser APIs.

See the official Next.js CSS guide for the current Tailwind integration.

Vite

Tailwind recommends its Vite plugin for new projects:

bash

npm install earthling-ui
npm install -D tailwindcss @tailwindcss/vite

tsx

// vite.config.ts
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [react(), tailwindcss()],
});

Put the three CSS imports shown above in src/styles.css, then import that file from src/main.tsx.

If the Vite plugin is unsuitable for your build, use PostCSS instead:

bash

npm install -D tailwindcss @tailwindcss/postcss postcss

tsx

// postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

Use one Tailwind integration, not both. The Earthling stylesheet carries its own source directives, so imported component classes are included. Vite may report harmless notices about ignored module-level "use client" directives in a client-only build.

See the official Tailwind Vite guide for the current plugin setup.

Import or own the source

Package imports receive library updates. To copy a component into your project, initialize destination paths and preview the operation:

bash

npx earthling-ui init
npx earthling-ui eject dialog --dry-run --json
npx earthling-ui eject dialog

Keep earthling-ui/index.css after ejection because source ownership and theme delivery are separate. Add an @source directive if your ejected directory is outside Tailwind automatic detection.

Continue with the theming guide, CLI reference, or component catalog.