Configuration Files

The Nocta CLI maintains two JSON documents: nocta.config.json inside each workspace and nocta.workspace.json at the repository root. This guide explains their structure and how they are used.

`nocta.config.json`

Created by nocta-ui init, this file describes how the CLI should scaffold components and where shared helpers live.

Core structure

tailwind.css tells the CLI where to inject design tokens.
aliases control where component files and utilities land and optionally provide a custom import alias.
aliasPrefixes only matter when an alias is a short string; they decide which import prefix (@, ~, etc.) is used.
exports.components (optional) keeps a barrel file up to date when you install components.
workspace stores metadata that lets the CLI coordinate monorepos and link additional workspaces.

Example: Application linking a shared UI package

The application workspace keeps its own Tailwind entry point but delegates component installs to a shared UI package. The CLI will sync helpers, exports, and dependencies with the linked workspace.

{
  "$schema": "https://nocta-ui.com/registry/config-schema.json",
  "style": "default",
  "tailwind": {
    "css": "app/globals.css"
  },
  "aliases": {
    "components": "components/ui",
    "utils": "lib/utils"
  },
  "aliasPrefixes": {
    "components": "@",
    "utils": "@"
  },
  "workspace": {
    "kind": "app",
    "packageName": "web",
    "root": "apps/web",
    "linkedWorkspaces": [
      {
        "kind": "ui",
        "packageName": "ui",
        "root": "packages/ui",
        "config": "../../packages/ui/nocta.config.json"
      }
    ]
  }
}

linkedWorkspaces let the CLI know which packages should receive component files and dependency updates.
Paths inside linkedWorkspaces[].config are relative to the current workspace, which makes cross-package updates resilient when you move folders.
Leave aliasPrefixes set to @ unless your project needs a different import character (React Router defaults to ~).

Example: Shared UI workspace with export barrel

Shared UI packages usually own component source files, run Tailwind in build pipelines, and expose a barrel file for consumers. The CLI uses this information to decide where to write helpers and when to touch the package manifest.

{
  "$schema": "https://nocta-ui.com/registry/config-schema.json",
  "style": "default",
  "tailwind": {
    "css": "src/styles.css"
  },
  "aliases": {
    "components": "src/components/ui",
    "utils": "src/lib/utils"
  },
  "aliasPrefixes": {
    "components": "@",
    "utils": "@"
  },
  "exports": {
    "components": {
      "barrel": "src/index.ts",
      "strategy": "named"
    }
  },
  "workspace": {
    "kind": "ui",
    "packageName": "ui",
    "root": "packages/ui"
  }
}

exports.components ensures nocta-ui add appends new components to the barrel without touching your custom code outside the managed block.
Shared UI workspaces usually omit linkedWorkspaces because other projects link to them; add entries only when you need to push files into sibling libraries.

Framework Defaults

init fills the fields above based on the detected framework:

Framework	Tailwind CSS file	Component path	Utils path	Alias prefix
Next.js (App Router)	`app/globals.css`	`components/ui`	`lib/utils`	`@`
Next.js (Pages Router)	`styles/globals.css`	`components/ui`	`lib/utils`	`@`
Vite + React	`src/App.css`	`src/components/ui`	`src/lib/utils`	`@`
React Router 7 (Framework Mode)	`app/app.css`	`app/components/ui`	`app/lib/utils`	`~`
TanStack Start	`src/styles.css` (auto-detected)	`src/components/ui`	`src/lib/utils`	`@`
Shared UI / Library	CLI searches common CSS filenames and defaults to `src/styles.css`; component and utility paths live under `src/`.

You can edit the config after running init; future runs merge new information while preserving customisations where possible.

`nocta.workspace.json`

Stored at the repository root, this manifest tracks every workspace that has run init. It enables cross-package coordination when you run commands from different directories.

Structure

{
  "packageManager": "pnpm",
  "repoRoot": ".",
  "workspaces": [
    {
      "name": "@workspace/ui",
      "kind": "ui",
      "packageName": "@workspace/ui",
      "root": "packages/ui",
      "config": "packages/ui/nocta.config.json"
    },
    {
      "name": "@workspace/admin",
      "kind": "app",
      "packageName": "@workspace/admin",
      "root": "apps/admin",
      "config": "apps/admin/nocta.config.json"
    }
  ]
}

Field	Type	Description
`packageManager`	enum (`"npm"`, `"pnpm"`, `"yarn"`, `"bun"`)	Detected from repo lockfiles. Used for all install commands.
`repoRoot`	string (optional)	Normalised path to the repo root (usually `.`).
`workspaces`	array	Each entry mirrors information from the corresponding `nocta.config.json`.

Each workspace entry contains:

Field	Type	Description
`name`	string	Display name (defaults to `root` when no package name is provided).
`kind`	enum (`"app"`, `"ui"`, `"library"`)	Workspace role.
`packageName`	string (optional)	npm workspace or package name. Helps route package-manager commands.
`root`	string	Path from repo root to the workspace.
`config`	string	Relative path from repo root to `nocta.config.json`.

Lifecycle

nocta-ui init creates or updates the manifest whenever a workspace is registered.
The file keeps entries sorted by root for readability.
Commands like add rely on the manifest to resolve linked workspaces even when you run the CLI from a different directory.

Keep the manifest committed to version control so collaborators share the same workspace topology.