NofiniteOpensource
AI
NUICSS logov3.1.0

Installation & Setup

Get started with NUICSS using your preferred framework, bundler, package manager, or zero-build CDN setup.

1. Package Installation

Install @nofinite/nuicss in your project:

bash
# pnpm
pnpm add @nofinite/nuicss

# npm
npm install @nofinite/nuicss

# yarn
yarn add @nofinite/nuicss

# bun
bun add @nofinite/nuicss

2. Framework Integration

A. Next.js (Turbopack & App Router)

NUICSS includes a first-class withNuicss Next.js plugin that automatically configures Turbopack aliases, package transpilation, and Webpack PostCSS pipelines:

javascript
// next.config.mjs
import { withNuicss } from '@nofinite/nuicss/next';

/** @type {import('next').NextConfig} */
const nextConfig = {
  // your existing Next.js options
};

export default withNuicss(nextConfig);

Then import the precompiled stylesheet in your root layout:

tsx
// app/layout.tsx
import '@nofinite/nuicss/styles.css';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className="bg-page text-default antialiased">
        {children}
      </body>
    </html>
  );
}
Tip

withNuicss automatically resolves virtual CSS aliases for both Turbopack (next dev --turbo / Next.js 15 Turbopack) and Webpack without needing custom alias boilerplate in your configuration.

B. Vite (React, Vue, Svelte)

For Vite-powered single-page applications, use nuicssVitePlugin. It provides on-demand utility compilation, live HMR, and zero PostCSS configuration:

typescript
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { nuicssVitePlugin } from '@nofinite/nuicss';

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

Import the virtual stylesheet in your application entry point:

typescript
// src/main.tsx or src/index.ts
import '@nofinite/nuicss/virtual.css';

C. PostCSS Pipeline (Astro, Webpack, Nuxt)

If you are using a standard PostCSS build pipeline, register the NUICSS PostCSS plugin:

javascript
// postcss.config.mjs
export default {
  plugins: {
    '@nofinite/nuicss/postcss': {},
  },
};

Include the @nuicss; directive at the top of your global CSS:

css
/* src/styles/global.css */
@nuicss;

D. Standalone Precompiled CSS (Zero Compiler Setup)

If you prefer to consume NUICSS as standard precompiled CSS without running any build plugins or JIT compilers, import the pre-built stylesheet directly:

typescript
import '@nofinite/nuicss/styles.css';

This includes:

  • Modern CSS reset and typography base
  • OKLCH color palettes and semantic tokens (--bg-page, --bg-surface, --color-primary)
  • All component superclasses (btn, card, input, badge, table-container, etc.)
  • Dark mode theme switching rules

E. Standalone CLI & Compiler (nuicss)

For non-Node stacks (Go, Python, PHP, Ruby) or standalone compilation workflows without a bundler plugin, use the official nuicss CLI:

bash
# On-demand via npx
npx nuicss -i input.css -o dist/output.css --watch --minify

# Or install standalone binary (Zero Node.js required)
# Windows (PowerShell):
irm https://opensource.nofinite.com/nuicss/install.ps1 | iex

# macOS & Linux (Bash):
curl -fsSL https://opensource.nofinite.com/nuicss/install.sh | bash

See the complete NUICSS CLI Guide for full command options, codebase linting (nuicss check), and automated migrations (nuicss migrate).

3. Zero-Build CDN Usage

For quick prototypes, HTML mockups, HTMX apps, or static server templates:

Option A: JIT Runtime Script (Automatic On-the-Fly Compilation)

html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>NUICSS App</title>
  <script src="https://cdn.jsdelivr.net/npm/@nofinite/nuicss/dist/index.global.js"></script>
</head>
<body class="bg-page text-default p-8">
  <div class="card max-w-md mx-auto p-6 space-y-4">
    <h1 class="text-xl font-bold">Hello NUICSS</h1>
    <button class="btn btn-primary">Get Started</button>
  </div>
</body>
</html>

Option B: Precompiled CSS

html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nofinite/nuicss/dist/index.css" />

4. Configuration (nuicss.config.ts)

Create a nuicss.config.ts in your project root to extend themes, customize breakpoints, or register custom shortcuts:

typescript
// nuicss.config.ts
import { defineConfig, nuicssPreset } from '@nofinite/nuicss';

export default defineConfig({
  presets: [
    nuicssPreset() as any,
  ],
  content: {
    pipeline: {
      include: [
        /\.(vue|svelte|[jt]sx|mdx?|html)($|\?)/,
        'src/**/*.{js,ts,jsx,tsx,mdx}',
      ],
    },
  },
});

Next Steps

View sourceEdit page
PreviousIntroductionNextCLI & Compiler