Install with Next.js

Use Next.js App Router. Follow Next.js’s current system requirements for your Node.js runtime.

1. Create the application with LoamUI

shell

pnpm dlx loamui@latest create

shell

npx loamui@latest create

shell

yarn dlx loamui@latest create

shell

bunx loamui@latest create

This runs create-next-app — TypeScript, App Router, empty, without Tailwind or a src directory — installs @loamui/core, writes a layout that links the stylesheet for that version, a welcome page and its stylesheet, and then runs init: the layer order in app/globals.css, Stylelint, Oxlint and Oxfmt with the composition checker and a check script, a LoamUI section in AGENTS.md, and the agent skills. Give the directory after create, or answer the prompt.

Already have an application? Keep its routes and configuration and run init in it instead:

shell

pnpm dlx loamui@latest init

shell

npx loamui@latest init

shell

yarn dlx loamui@latest init

shell

bunx loamui@latest init

init only adds — nothing you have is replaced — and running it again changes nothing; --dry-run shows the plan. It links the stylesheet in app/layout.tsx, creates app/globals.css with the layer order and imports it, and adds the checks, scripts and skills. A project with a src directory is detected and wired under src/app/. Check the existing-project workflow before changing its styling foundation.

2. Check your first interface

create wrote the foundation page at app/page.tsx with welcome.css beside it; in an existing application, copy the foundation example there. It starts with "use client": the package is one client module, so compound parts such as Field.Root are undefined in a server component and the page fails at prerender. Keep components that render LoamUI parts on the client; the root layout stays a server component.

shell

pnpm run dev

shell

npm run dev

shell

yarn run dev

shell

bun run dev

Check the interface, then stop that server and run:

shell

pnpm run buildpnpm run start

shell

npm run buildnpm run start

shell

yarn run buildyarn run start

shell

bun run buildbun run start

Next: build with the skill.

What create and init did, by hand

The same setup by hand

Create an empty application without Tailwind:

shell

pnpm create next-app@latest my-app \  --ts --app --empty --no-tailwind --no-src-dir --use-pnpm --yescd my-app

shell

npx create-next-app@latest my-app \  --ts --app --empty --no-tailwind --no-src-dir --use-npm --yescd my-app

shell

yarn create next-app my-app \  --ts --app --empty --no-tailwind --no-src-dir --use-yarn --yescd my-app

shell

bun create next-app@latest my-app \  --ts --app --empty --no-tailwind --no-src-dir --use-bun --yescd my-app

Install the package:

shell

pnpm add @loamui/core

shell

npm install @loamui/core

shell

yarn add @loamui/core

shell

bun add @loamui/core

Load the stylesheet directly

Load the stylesheet with a <link> so it reaches the browser unchanged. This avoids a build-time parsing limitation in Lightning CSS, used by Next.js, which currently rejects some modern CSS syntax used by LoamUI.

Add the stylesheet link inside the <head> of app/layout.tsx. Keep the existing layout, metadata and application stylesheet import:

TSX

import "./globals.css";
export default function RootLayout({ children }: { children: React.ReactNode }) {  return (    <html lang="en">      <head>        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@loamui/core@0.2.0/dist/styles.css" />      </head>      <body>{children}</body>    </html>  );}

The browser loads tokens, element styles and component styles without sending core CSS through the bundler. Do not add an import of @loamui/core/styles.css. No provider is needed.

The URL is pinned to the installed version of @loamui/core; keep the two in step when you update. See stylesheet delivery for self-hosting.

Declare the layer order

The --empty scaffold does not create app/globals.css. Create it with this layer order as its first line, before any imports or rules that create LoamUI layers:

CSS

@layer loamui.tokens, loamui.elements, loamui.components;

Next.js can emit bundled recipe styles before the manual stylesheet link. This declaration keeps element defaults below component and recipe rules. A later layer declaration cannot repair an order already established.

For a fresh application, this declaration is the whole file, and the layout above imports it. Preserve existing application styles when integrating into a working project. Import recipe styles alongside their components. Check the emitted stylesheet order on a direct page load and after client navigation.

The checks, scripts and skills are described in Build with the skill.