Next.js Guide

Set up Vortex in a Next.js App Router project.

Install the packages

bun add @vortexlabs/vortex

bun add -d postcss @csstools/postcss-global-data postcss-custom-media cssnano

Generate your theme

Create vortex.config.ts at your project root. Replace acme with your theme name; an empty definition inherits Vortex's defaults.

vortex.config.ts

import type { VortexThemeConfig } from "@vortexlabs/vortex";

const config: VortexThemeConfig = {
themes: {
  acme: {},
},
};

export default config;

Add a script to your existing package.json. The CLI is included in @vortexlabs/vortex.

package.json

"scripts": {
"build:theme": "vortex theming --output ./src/themes"
}

bun run build:theme

This creates src/themes/acme/. Run the script again after changing vortex.config.ts, before starting or building your app. See Create a Theme to customize your tokens.

Configure PostCSS

Vortex ships its styles with @custom-media breakpoint queries that are resolved by your build. Add the PostCSS preset that comes with the package — responsive styles won't work without it. Next.js expects the config as a plain object, which is exactly what the preset exports.

postcss.config.cjs

const { config } = require("@vortexlabs/vortex/config/postcss");

module.exports = config;

If you already have a PostCSS config, merge the preset's plugins into it. Restart the dev server after configuration changes.

If you customize breakpoints, follow Custom breakpoints to use your generated definitions.

Configure package transpilation

Add Vortex to transpilePackages so Next.js processes the package and its CSS Modules. Keep any other options in your existing config.

next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
transpilePackages: ["@vortexlabs/vortex"],
};

export default nextConfig;

Add the provider and theme

Create a client boundary for the provider:

app/providers.tsx

"use client";

import { VortexProvider } from "@vortexlabs/vortex";
import type { ReactNode } from "react";

export default function Providers({ children }: { children: ReactNode }) {
return (
  <VortexProvider defaultTheme="acme" defaultColorMode="light">
    {children}
  </VortexProvider>
);
}

Import the generated theme once in your root layout and wrap your app with Providers. This example uses a root-level app/ directory; for src/app/, use ../themes/acme/globals.css. Setting data-vortex-theme and data-vortex-color-mode on <html> server-side prevents a flash of unstyled content — keep these values in sync with the provider's initial theme and color mode.

app/layout.tsx

import "../src/themes/acme/globals.css";
import type { ReactNode } from "react";
import Providers from "./providers";

const RootLayout = ({ children }: { children: ReactNode }) => (
<html
  lang="en"
  data-vortex-theme="acme"
  data-vortex-color-mode="light"
  suppressHydrationWarning
>
  <body>
    <Providers>{children}</Providers>
  </body>
</html>
);

export default RootLayout;

Render components

Import Vortex components inside a Client Component. The package includes components that use React context and refs; a provider above them does not turn a Server Component into a Client Component. Client Components can still be rendered on the server for the initial page load.

app/page.tsx

"use client";

import { Button, Stack, Text } from "@vortexlabs/vortex";

const Page = () => (
<Stack gap={4}>
  <Text as="h1" size={{ xs: "heading-xl-mobile", sm: "heading-xl-desktop" }}>Hello Vortex</Text>
  <Button variant="primary">Get started</Button>
</Stack>
);

export default Page;

See the Next.js client boundary guide for composing server and client components.

Fonts

Vortex doesn't include font files. Follow the Fonts guide to load your fonts and connect them to your theme.