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
Start from a Tailwind v4 project
Any Rasengan.js 2 project with Tailwind v4, such as the
tailwind-v4-tsstarter. Its@/*alias is already set. If you don't have one yet,create-rasenganmakes it:Terminal With
-y, it picks TypeScript, file-based routing and Tailwind v4. Leave-yout to choose them yourself.Run init
Terminal It asks for a village and a nature, then imports them in
src/styles/index.cssand sets the village on<html>insrc/template.tsx.Add components
Terminal
Vite
Add Tailwind CSS
Install
tailwindcssand@tailwindcss/vite, add the plugin tovite.config.ts, and import Tailwind at the top ofsrc/index.css: see Tailwind's guide.Add the @ alias
The components import
@/components/…and@/lib/…. Add the alias totsconfig.app.jsonandtsconfig.json:tsconfig.app.json and to Vite:
vite.config.ts Run init, then add components
Terminal The village goes on
<html>inindex.html.
Next.js
Create the app with Tailwind
Terminal Run init, then add components
Terminal The village goes on
<html>inapp/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.
Point the name at the package's source
packages/ui/tsconfig.json and export the same folders to the apps. A pattern takes one extension (bundlers use only the first target of a list), so each
.tsxfile oflib/gets its own line, before the pattern:packages/ui/package.json Run init with the package's name
Terminal The components then import
@acme/ui/lib/utilsand@acme/ui/components/ui/…, which the package resolves through its ownexports. An app imports@acme/ui/components/ui/button, and its Tailwind setup scans the package with@source "../../packages/ui/src";. After anadd,rasengan-ui doctorlists any file theexportsdon'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:
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, andrasengan/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, afont-familyonbody…) would override the village.initcomments out only those declarations, after asking;--keep-cssleaves them. <html>:data-village,data-natureanddata-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.