Installation

Requirements

Requirement	Version
React	19
Tailwind CSS	4
TypeScript	5 or later
Node.js	18.17 or later

New project

init creates a ready-to-run app with the theme, the @/ path, the Inter font, and every UI component already in place.

Next.jsVite

npmpnpmyarn

npx nateui@latest init --nextjs my-app

The target folder must be new or empty. When init finishes, it prints the commands to install packages and start the app, for example:

cd my-app && npm install && npm run dev

To start with the Pro layers as well, add --pro. The CLI asks you to sign in if you haven't. See the CLI reference.

Manual

Add NateUI to a project you already have. Set up the theme and the @/ path once, before your first add. These are the same steps init does for a new app.

1. 1

   Install packages

   Next.jsViteOther React setups

   If your app doesn't have Tailwind CSS 4 yet, follow Tailwind's Next.js guide first. Then add the typography plugin the theme uses:

   npmpnpmyarn

   npm install -D @tailwindcss/typography

   Component-specific packages are added later by add.

2. 2

   Add the theme

   This stylesheet holds every color, radius, and shadow the components use, in light and dark.

   styles/base.css

   @import "tailwindcss";
   @plugin "@tailwindcss/typography";
   
   @custom-variant dark (&:where(.dark, .dark *));

   Expand code

   Next.jsViteOther React setups

   Save it as styles/base.css, next to your app folder. Then import it at the top of app/globals.css:

   app/globals.css

   @import "../styles/base.css";

   The stylesheet already imports Tailwind CSS, so remove your own @import "tailwindcss"; line. Otherwise Tailwind loads twice.

3. 3

   Set the @/ path

   Components import each other and their helpers through @/. NateUI installs its files into the folder @/ points to.

   Next.jsViteOther React setups

   Apps created with create-next-app already have @/, so there's nothing to add.

4. 4

   Add the font

   Optional. The theme uses Inter and falls back to the system font when Inter isn't loaded.

   Next.jsViteOther React setups

   app/layout.tsx

   import type { ReactNode } from "react";
   import { Inter } from "next/font/google";
   import "./globals.css";
    
   const inter = Inter({
     subsets: ["latin"],
     display: "swap",
     variable: "--font-inter",
   });
    
   export default function RootLayout({ children }: { children: ReactNode }) {
     return (
       <html lang="en" className={inter.variable}>
         <body className={inter.className}>{children}</body>
       </html>
     );
   }
5. 5

   Add a component

   Run this from the project root:

   npmpnpmyarn

   npx nateui@latest add button

   add copies the component and anything it depends on into the folder @/ points to, adds its npm packages to package.json, and writes a components.json. Run your package manager's install afterwards if it tells you to.

   To copy files by hand instead, use the Manual tab on any component page. It lists every file and package the component needs. Pro components show their files once you sign in.

   And use it:

   Next.jsVite

   app/page.tsx

   "use client";
    
   import { Button } from "@/components/ui/button";
    
   export default function Page() {
     return <Button>Get started</Button>;
   }

   Most components use React state or context. In the App Router, use them from a file that starts with "use client".

Where files go

NateUI installs into the folder @/ points to: src if your project has one, otherwise the project root.

Components land in the folder for their layer. Shared hooks and helpers go to hooks and utils, and are added automatically when a component needs them.

components.json sits at the project root. It records where NateUI installs files and which items you've added. Keep it in version control.

Next steps