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.

2. Run init

   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

   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:

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

   and to Vite:

   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

   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

   npx create-next-app@latest my-app --ts --tailwind --app

2. Run init, then add components

   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.

Other setups

init writes the config and the stylesheet imports for any project with Tailwind v4 and an @/ alias, 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. init says which ones the village uses; load them from Google Fonts or host them yourself. Until then the system fonts stand in.