Installation

Prerequisites

Before installing Nim UI, make sure you have:

• Node.js 22.0 or later
• React 19.2.0 or later
• TypeScript 5.9.0 or later (recommended)

Install the Package

Install Nim UI and its peer dependencies using your preferred package manager:

pnpm add @nim-ui/components
pnpm add -D tailwindcss @tailwindcss/postcss

npm install @nim-ui/components
npm install -D tailwindcss @tailwindcss/postcss

yarn add @nim-ui/components
yarn add -D tailwindcss @tailwindcss/postcss

bun add @nim-ui/components
bun add -D tailwindcss @tailwindcss/postcss

Configure Tailwind CSS

Nim UI uses Tailwind CSS v4 for styling. Set up Tailwind in your project:

1. Add Tailwind to PostCSS

Create a postcss.config.js file:

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

2. Import Styles

Tailwind v4 is configured in CSS, not in a JavaScript config file. Your entry stylesheet is the whole setup:

@import 'tailwindcss';
@import '@nim-ui/components/styles';

@import 'tailwindcss' brings in the default theme and scans your source for class names. @import '@nim-ui/components/styles' adds Nim's tokens, keyframes and the dark: variant on top.

This is all you need for reduced motion too -- the kit switches its own animations and moving transitions off per component. It does not install an application-wide motion reset on your behalf; if you want one, add @import '@nim-ui/components/reduced-motion.css'; as well. See Reduced Motion for what that changes, including why loading spinners keep turning either way.

Then import this CSS file in your app entry point:

import React from 'react';
import './index.css';
import ReactDOM from 'react-dom/client';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

TypeScript Configuration

For optimal TypeScript support, add these settings to your tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",
    "strict": true,
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "allowSyntheticDefaultImports": true
  },
  "include": ["src"]
}

Vite Configuration

If you're using Vite, ensure your vite.config.ts includes React plugin:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

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

Verify Installation

Create a simple component to verify everything is working:

import { Button } from '@nim-ui/components';

export default function App() {
  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold mb-4">Nim UI Test</h1>
      <Button variant="primary" onClick={() => alert('It works!')}>
        Click me
      </Button>
    </div>
  );
}

If you see a styled button, congratulations! Nim UI is successfully installed.

What's Next?

• Quick Start Guide - Build your first component
• Configuration - Customize the theme
• Browse Components - Explore all components

Framework-Specific Guides

Next.js

For Next.js projects, additional configuration is needed:

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@nim-ui/components'],
};

export default nextConfig;

Remix

For Remix, add to your remix.config.js:

/** @type {import('@remix-run/dev').AppConfig} */
export default {
  serverDependenciesToBundle: ['@nim-ui/components'],
};

Troubleshooting

Styles Not Loading

If styles aren't appearing:

1. Confirm your CSS entry file is actually imported into your app, not just written to disk — import './index.css'; in src/main.tsx, as shown above. A stylesheet nothing imports compiles nothing.

2. Confirm that stylesheet uses the v4 import, not a v3 content glob:

   @import 'tailwindcss';

   Tailwind v4 has no content option — a content: [...] array from a v3 setup does nothing here, whether it lives in a tailwind.config.js (ignored unless loaded with @config) or anywhere else, so it can't be the fix. If this file still has the v3 @tailwind base / @tailwind components / @tailwind utilities directives instead of @import 'tailwindcss', see the callout above — that's a silent partial build, not a missing one.

3. Ensure you imported the component styles:

   @import '@nim-ui/components/styles';

4. Check that PostCSS is configured correctly

TypeScript Errors

If you get TypeScript errors:

1. Ensure TypeScript version is 5.9.0 or later
2. Enable skipLibCheck: true in tsconfig.json
3. Restart your TypeScript server

Build Errors

If you encounter build errors:

1. Clear your build cache and node_modules
2. Reinstall dependencies
3. Ensure all peer dependencies are installed

For more help, check our GitHub Issues.