A vibe-coding setup has two halves: the ordinary Node toolchain your app runs on, and the harness that keeps your AI agent honest about the Once UI API. This page covers both, in the order you should do them.
What you'll need
Node 20 or newer — Once UI targets >=20.x. Check with node -v.
A package manager — npm ships with Node; pnpm and bun work too.
Git, for cloning starters and tracking what your agent changes.
An editor with an agent — Cursor, Windsurf, VS Code with Copilot, or Claude Code in the terminal.
Add Once UI to a project
In an existing Next.js App Router project, install the package:
npm install @once-ui-system/core
Then import the stylesheets once, in your root layout, before your own styles:
Everything else — components, hooks, contexts, icons — comes from the package root or its subpaths. You do not add a CSS framework alongside it; spacing, color, and typography are token props on the components themselves.
Wire the AI harness
This is the step most people skip, and it is the one that decides whether your agent writes real Once UI or plausible-looking guesses. Run the scaffolder once, from your project root:
npx once-ui-init-agent
It writes two files: an AGENTS.md section describing the harness and how to consult it, and a Cursor rule at .cursor/rules/once-ui-codegen.mdc. Both point your agent at the machine-readable spec that ships inside the package — the component catalog, per-component prop slices, task bundles, and the list of known gotchas.Commit both files. They are project configuration, not scratch output, and an agent that cannot find them falls back to memory.
Give your agent live docs
For "how does X work?" questions that go beyond the shipped spec, agents can pull documentation over MCP. Add Context7 to your client's MCP configuration:
The Once UI library is indexed there as /once-ui-system/core. Point questions at that library id rather than letting the agent search the open web, where it will find posts about older versions.
Verify the setup
Two checks tell you the environment is real rather than merely installed.
First, generate or write a small component, then run the validator that ships with the package:
It reports mechanical mistakes — unknown icon names, redundant default props, raw HTML where a component exists, hardcoded colors. A clean run means the file is at least idiomatic.
Second, start the dev server and confirm the tokens actually loaded:
If text and surfaces render unstyled, the stylesheet imports in your root layout are missing or in the wrong order.
A note on keeping it current
Pin the Once UI version in package.json rather than floating on latest, and re-run npx once-ui-init-agent after upgrading a minor version — the harness files describe the version you have installed, and a stale copy teaches your agent an API that no longer exists.
