Configuration

The backcap.json file is created by backcap init at the root of your project. It tells the CLI where to write files and which framework you use.

Example

{
  "framework": "express",
  "packageManager": "pnpm",
  "alias": "@domains",
  "paths": {
    "domains": "domains",
    "skills": ".claude/skills",
    "shared": "src/shared"
  }
}

Fields

`framework`

The backend framework for your project. Recorded for reference during backcap add.

Value	Detected from
`express`	`express` in `package.json`
`fastify`	`fastify` in `package.json`
`hono`	`hono` in `package.json`
`nestjs`	`@nestjs/core` in `package.json`
`nextjs`	`next` in `package.json`

Auto-detected during backcap init. If detection fails, you are prompted to choose.

`packageManager`

The package manager used for installing dependencies.

Value	Detected from
`npm`	`package-lock.json`
`pnpm`	`pnpm-lock.yaml`
`yarn`	`yarn.lock`
`bun`	`bun.lockb`

Auto-detected during backcap init. If detection fails, you are prompted to choose.

`alias`

Default: "@domains"

The TypeScript path alias for cross-domain imports. During backcap init, the CLI adds a corresponding entry to your tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@domains/*": ["domains/*"]
    }
  }
}

This lets domains import from each other using clean paths:

import type { ITokenService } from "@domains/auth/application/ports/token-service.port.js";

instead of fragile relative paths.

`paths`

Controls where the CLI writes files when you run backcap add. All paths are relative to your project root.

Field	Default	Description
`paths.domains`	`"domains"`	Domain source files — entities, use cases, contracts, value objects
`paths.skills`	`".claude/skills"`	AI agent skill files (SKILL.md and references)
`paths.shared`	`"src/shared"`	Shared utilities — `Result` type and event bus port

Customizing paths

You can edit backcap.json directly after init:

{
  "paths": {
    "domains": "src/domains",
    "skills": ".claude/skills",
    "shared": "src/shared"
  }
}

The CLI will use these paths for all subsequent backcap add commands. Existing files are not moved — only new installations use the updated paths.

Design notes

No state tracking. Unlike tools that maintain a lock file, backcap.json contains only configuration. The filesystem is the source of truth for what is installed — run backcap list to see installed domains.
Strict paths. Unknown keys inside paths are rejected during validation to catch typos early.
Extensible top level. Unknown keys at the top level are allowed for forward compatibility.