Installation

Install the Aqqo UI package

Pre‑requisites

Next.js 16 (App Router)
Tailwind CSS v4

If you are setting up Tailwind v4 in a fresh Next.js app, follow the official guide first: https://tailwindcss.com/docs/installation/framework-guides/nextjs

Key points for v4 + Next.js:

Install PostCSS plugin: npm i -D tailwindcss @tailwindcss/postcss postcss
Create postcss.config.mjs with @tailwindcss/postcss
Import Tailwind via @import "tailwindcss"; in your global CSS

Create .npmrc file

Create a .npmrc file in the root of your project and add the following line:

@aqqo:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken={token}

Replace token with your personal access token. You can create a personal access token by following the instructions here.

Install the packages

Install the packages using npm or yarn:

npm install

Configure PostCSS (Tailwind v4)

Create postcss.config.mjs at the project root:

postcss.config.mjs

const config = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};
export default config;

Global CSS (Tailwind v4)

Replace your global stylesheet to use the Tailwind v4 approach and make sure Tailwind scans both your app and the Aqqo UI packages for utility classes. This ensures classes used inside the component library (like bg-green-50) are generated.

app/globals.css

@import "tailwindcss";
 
/* Scan your app and MDX content */
@source "./app/**/*.{ts,tsx,mdx}";
@source "./src/**/*.{ts,tsx,mdx}";
@source "./content/**/*.{md,mdx}";
 
/* Scan Aqqo UI package (distributed CSS-in-JS output) */
@source "../node_modules/@aqqo/aqqo-ui/dist/**/*.{js,mjs}";
 
/* Enable Tailwind plugins (recommended) */
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";
@plugin "tailwindcss-animate";
 
/* Theme tokens mapped to next/font variables */
@theme {
  --font-instrument: var(--font-instrument-sans);
  --font-poppins: var(--font-poppins);
  --font-roboto: var(--font-roboto);
 
  --color-primary-dark-green: #032622;
  --color-primary-light-green: #02D868;
  --color-primary-off-white: #F4F2EF;
}
 
@layer base {
  body {
    @apply font-roboto text-sm;
  }
}

Root layout (fonts + styles)

Adjust the root layout to import Aqqo UI styles and register font variables. This ensures fonts are loaded before content is rendered.

layout.jsx

import { Instrument_Sans, Poppins, Roboto } from 'next/font/google'
import './globals.css'
import '@aqqo/aqqo-ui/style'
 
const instrumentSans = Instrument_Sans({
    weight: ['400', '500', '600', '700'],
    subsets: ['latin'],
    variable: '--font-instrument-sans',
})
 
const poppins = Poppins({
    weight: ['100', '200', '300', '400', '500', '600', '700', '800', '900'],
    subsets: ['latin'],
    variable: '--font-poppins',
})
 
const roboto = Roboto({
    weight: ['100', '300', '400', '500', '700', '900'],
    subsets: ['latin'],
    variable: '--font-roboto',
})
 
export default function RootLayout({ children }) {
    return (
        <html lang="en">
            <body
                className={`${poppins.variable} ${instrumentSans.variable} ${roboto.variable}`}>
                {children}
            </body>
        </html>
    )
}

Notes:

Tailwind v4 stores most configuration in CSS; you typically don’t need tailwind.config.js. Use @theme, @source, and @plugin in CSS.
Restart your dev server after adding postcss.config.mjs or changing plugin configuration so the PostCSS pipeline reloads.