Installation

Summary

Add UIX to a Next.js app in six steps. You need pnpm, and an app with the App Router and Tailwind CSS v4: pnpm create next-app@latest with its recommended options makes one. At the end, your app shows a UIX Button in light and dark.

Get access

UIX packages are in a private package registry. Ask for access through Support, with your app's name. The UIX team gives your app a read-only token, which can install UIX but not change it, and sends you:

• Two commands for your computer. The first tells pnpm where UIX packages are, and the second gives it your token. Run them once in a terminal: pnpm saves both in your user settings, outside your code, so they work for every app on that computer
• One value for your deploy platform and CI. It holds the same two settings in one environment variable, since those only take environment variables. Add it there as pnpm_config__auth

Both hold your token, so treat them like a password: never commit them or share them in chat. To check that access works, run:

pnpm view @anantya/uix version

It prints the latest version of UIX.

Install

pnpm add @anantya/uix @anantya/icons

@anantya/tokens and @anantya/core come with @anantya/uix, so you don't add them yourself.

Add the styles

Replace everything in app/globals.css with:

@import "tailwindcss";
@import "@anantya/uix/theme.css";

This loads the UIX theme, with Tailwind's blue-600 as the primary color. Its colors work as classes in your own code too, such as bg-primary. Replace the whole file, not only the top: a new Next.js app's CSS sets its own colors and font, which would override the UIX ones.

Set up the root layout

Replace app/layout.tsx with:

import { ThemeProvider } from "@anantya/uix";
import { Mona_Sans } from "next/font/google";
import type { ReactNode } from "react";
import "./globals.css";

const monaSans = Mona_Sans({ subsets: ["latin"], variable: "--font-sans" });

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" className={monaSans.variable} suppressHydrationWarning>
      <body className="bg-background text-foreground antialiased">
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

• Mona_Sans loads Mona Sans, the UIX font
• ThemeProvider switches the app between light and dark and remembers the reader's choice
• suppressHydrationWarning is needed because Theme Provider sets the dark class on <html> before the page shows
• bg-background text-foreground color the page in light and dark

Configure Next.js

Add optimizePackageImports to next.config.ts, so each page loads only the components and icons it uses:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: {
    optimizePackageImports: ["@anantya/uix", "@anantya/icons"],
  },
};

export default nextConfig;

Add a component

Replace app/page.tsx with:

import { Button, ThemeToggle } from "@anantya/uix";
import Link from "next/link";

export default function Home() {
  return (
    <main className="flex gap-3 p-10">
      <Button asChild>
        <Link href="/book">Book now</Link>
      </Button>
      <ThemeToggle />
    </main>
  );
}

Run pnpm dev. You see a blue Book now button, and Theme Toggle switches between light and dark. asChild makes the Next.js link look like a button and keeps it a link: see Slot for how it works.

Troubleshooting

Related

• Upgrading: move to a newer UIX version
• Theme Provider: light, dark and the reader's choice
• Button and Theme Toggle: the components used above
• Slot: how asChild works
• Support: ask the UIX team for access or help