Project setup

Configure your Next.js project before installing Tailark items — shadcn initialization, components.json, path aliases, and monorepo layout.

For theme tokens, see Theme. Registry configuration is in Quick Setup.

Requirements

  • A Next.js app using the App Router
  • shadcn/ui initialized with a components.json file
  • For gated Quartz content: a Tailark API key from your Dashboard and an active plan

OSS kits (Mist, Dusk, Veil) do not require an account or API key.

Initialize shadcn

If you do not have shadcn/ui set up yet, run the init command in your project root. This creates components.json and adds the default path aliases.

bash

Pick the style preset that matches your UI base:

  • Base UI projects — use a base-* style (for example base-nova)
  • Radix UI projects — use a radix-* style (for example radix-vega)

Your style choice should align with the registry URL you configure in Quick Setup.

components.json

The components.json file is the entry point for the shadcn CLI. It tells the CLI where to install files, which Tailwind settings to use, and which registries you can install from.

Tailark page items declare install targets such as @app/(marketing)/layout.tsx, @types/post.ts, and @content/legal/terms-of-service.mdx. The CLI resolves those paths using the aliases map.

A minimal structure (add registries from Quick Setup):

json

Path aliases

Running npx shadcn@latest init adds components, utils, ui, lib, and hooks by default.

For Tailark Pages, also define app, types, and content so routes, shared types, and MDX content land in the correct directories.

json

Note

Match these paths to your project structure. Alias values must align with the paths in your tsconfig.json.

Monorepo

The shadcn CLI understands monorepo layouts and installs files to the correct workspace paths. See the shadcn monorepo docs for the full reference.

Getting started

Scaffold a new monorepo with:

bash

After adding registry entries and TAILARK_API_KEY to your app workspace, install Tailark items from the app path — not the repo root.

bash

File structure

bash

Monorepo requirements

  1. Every workspace needs a components.json.
  2. Define aliases per workspace. The app workspace needs app, types, and content for pages.
  3. Register @tailark in the app workspace (with API key headers). Mirror in packages/ui if you install blocks from there.
  4. Keep style, iconLibrary, and baseColor aligned across workspaces.
  5. For Tailwind CSS v4, leave tailwind.config empty in components.json.

Example app workspace components.json:

json

Use /r/radix/{name}.json for both namespaces when your project uses Radix UI.

Import shared UI from the workspace package:

tsx

Next steps

  • Theme — CSS variables and dark mode
  • MCP — AI agent support