Skip to content
New

Installation

Rasengan UI needs React and Tailwind CSS v4. rasengan-ui init sets the rest up: the core, the token contract, a village, the CSS imports and the village on <html>.

Rasengan.js

  1. Start from a Tailwind v4 project

    Any Rasengan.js 2 project with Tailwind v4, such as the tailwind-v4-ts starter. Its @/* alias is already set. If you don't have one yet, create-rasengan makes it:

    Terminal
    npx create-rasengan@latest my-app --template tailwind -y
    cd my-app
    npm install

    With -y, it picks TypeScript, file-based routing and Tailwind v4. Leave -y out to choose them yourself.

  2. Run init

    Terminal
    npx rasengan-ui init

    It asks for a village and a nature, then imports them in src/styles/index.css and sets the village on <html> in src/template.tsx.

  3. Add components

    Terminal
    npx rasengan-ui add button dialog

Vite

  1. Add Tailwind CSS

    Install tailwindcss and @tailwindcss/vite, add the plugin to vite.config.ts, and import Tailwind at the top of src/index.css: see Tailwind's guide.

  2. Add the @ alias

    The components import @/components/… and @/lib/…. Add the alias to tsconfig.app.json and tsconfig.json:

    tsconfig.app.json
    {
      "compilerOptions": {
        "paths": { "@/*": ["./src/*"] }
      }
    }

    and to Vite:

    vite.config.ts
    import path from "node:path";
     
    export default defineConfig({
      plugins: [react(), tailwindcss()],
      resolve: { alias: { "@": path.resolve(import.meta.dirname, "./src") } },
    });
  3. Run init, then add components

    Terminal
    npx rasengan-ui init
    npx rasengan-ui add button dialog

    The village goes on <html> in index.html.

Next.js

  1. Create the app with Tailwind

    Terminal
    npx create-next-app@latest my-app --ts --tailwind --app
  2. Run init, then add components

    Terminal
    npx rasengan-ui init
    npx rasengan-ui add button dialog

    The village goes on <html> in app/layout.tsx. The components that need the browser start with "use client", so they work from Server Components.

A package of a workspace

In a monorepo, the components can live in a package that the apps import in source, such as @acme/ui. There, @/ would point into each app, not into the package: the components import the package's own name instead.

  1. Point the name at the package's source

    packages/ui/tsconfig.json
    {
      "compilerOptions": {
        "paths": { "@acme/ui/*": ["./src/*"] }
      }
    }

    and export the same folders to the apps. A pattern takes one extension (bundlers use only the first target of a list), so each .tsx file of lib/ gets its own line, before the pattern:

    packages/ui/package.json
    {
      "name": "@acme/ui",
      "exports": {
        "./lib/village-scope": "./src/lib/village-scope.tsx",
        "./lib/field-context": "./src/lib/field-context.tsx",
        "./lib/*": "./src/lib/*.ts",
        "./components/*": "./src/components/*.tsx"
      }
    }
  2. Run init with the package's name

    Terminal
    cd packages/ui
    npx rasengan-ui init --aliases @acme/ui
    npx rasengan-ui add button dialog

    The components then import @acme/ui/lib/utils and @acme/ui/components/ui/…, which the package resolves through its own exports. An app imports @acme/ui/components/ui/button, and its Tailwind setup scans the package with @source "../../packages/ui/src";. After an add, rasengan-ui doctor lists any file the exports don't reach, with the line to add.

Other setups

init writes the config and the stylesheet imports for any project with Tailwind v4 and an import alias (@/, or --aliases), then prints the attributes to put on your <html> element:

<html data-village="konoha" data-nature="katon" data-tint="village">

What init changes

  • rasengan-ui.json: the engine, village, nature, greys, the stylesheet and the aliases.
  • The core and the contract: lib/utils.ts, lib/village-scope.tsx, and rasengan/ next to your stylesheet (the engine variants, the token contract, the natures and the village).
  • Your stylesheet: one block of imports right after Tailwind's, in the order the contract needs.
  • Theme tokens already there: a starter or shadcn theme in the same stylesheet (--background, --primary, --radius-sm, a font-family on body…) would override the village. init comments out only those declarations, after asking; --keep-css leaves them.
  • <html>: data-village, data-nature and data-tint.

rasengan-ui doctor checks all of it later on.

Fonts

Each village has its own type: Figtree in Konoha, Manrope in Kiri, Space Grotesk and JetBrains Mono in Iwa, Plus Jakarta Sans with Bricolage Grotesque headings in Kusa. init says which ones the village uses; load them from Google Fonts or host them yourself. Until then the system fonts stand in.