tscircuit.config.json

The tscircuit.config.json file is a project-level configuration file that allows you to customize settings for your tscircuit project. This file should be placed in the root of your project directory and is automatically created when you run tsci init.

Example

{
  "mainEntrypoint": "lib/circuits/main-board.tsx",
  "ignoredFiles": [
    "dist",
    "build",
    "coverage",
    "*.log",
    ".DS_Store",
    "temp"
  ]
}

Configuration Options

Property	Description
$schema	Optional JSON schema reference for editor tooling.
mainEntrypoint	Primary entry file for builds and dev workflows.
previewComponentPath	Overrides which component is used for preview images/GLTF.
siteDefaultComponentPath	Default component shown in generated static sites.
ignoredFiles	Extra file and directory ignore patterns for CLI workflows.
includeBoardFiles	Glob list for which board files are built or snapshotted.
snapshotsDir	Centralized directory for snapshot outputs.
prebuildCommand	Command to run before builds.
buildCommand	Override command used for cloud builds.
kicadLibraryEntrypointPath	Entry file for KiCad footprint library generation.
kicadLibraryName	Name for the generated KiCad library.
alwaysUseLatestTscircuitOnCloud	Force latest tscircuit version in cloud builds.
build	Build output toggles for CLI builds.

$schema

Type: string (optional)

Optional JSON schema reference for editor tooling and validation.

Example:

{
  "$schema": "https://cdn.jsdelivr.net/npm/@tscircuit/cli/types/tscircuit.config.schema.json"
}

mainEntrypoint

Type: string (optional)

Specifies the main entry point file for your tscircuit project.

Use Cases:

• Explicit Entry Point Definition: When you have multiple .tsx files in your project and want to explicitly define which one should be used as the main component file
• Non-Standard Project Structure: If your main circuit file is not in a standard location (like index.tsx, main.tsx, etc.)

Example:

{
  "mainEntrypoint": "index.tsx"
}

How It Works:

• Used by the dev server when running tsci dev
• Used by the eval system to determine which file to execute
• Takes precedence over auto-detection
• When not specified, the system will attempt to auto-detect common entry point files like:
  • index.tsx, index.ts, index.circuit.tsx
  • main.tsx, main.circuit.tsx
  • Files in lib/ or src/ directories with these names

Setting via CLI:

tsci config set mainEntrypoint "path/to/your/file.tsx"

previewComponentPath

Type: string (optional)

Points to the component that should be rendered when generating preview images or GLTF previews.

Use Cases:

• Dedicated preview component: Use a showcase or demo component instead of the main entrypoint.
• Different build targets: Keep preview imagery focused on a specific circuit even if mainEntrypoint is used for builds.

Example:

{
  "previewComponentPath": "examples/showcase.circuit.tsx"
}

How It Works:

• When running preview commands (e.g. tsci build --preview-images or tsci build --preview-gltf), this value takes precedence over mainEntrypoint.
• If it is not set, the preview build falls back to the main entrypoint selection logic.

Setting via CLI:

tsci config set previewComponentPath "path/to/preview.circuit.tsx"

ignoredFiles

Type: array of strings (optional)

Specifies paths or directory names that should be ignored when the dev server syncs files to the file server.

Use Cases:

• Exclude Build Artifacts: Ignore generated files, build outputs, or temporary files from being watched and synced
• Performance Optimization: Reduce file watching overhead by excluding large directories that don't need to be synced
• Prevent Unnecessary Syncs: Avoid syncing files that are not part of your circuit design (e.g., documentation, test fixtures, local configuration)

Example:

{
  "ignoredFiles": [
    "dist",
    "build",
    ".git",
    "*.log",
    "temp"
  ]
}

How It Works:

• Used by the dev server and eval system to filter files when watching for changes
• Applied during filesystem watching operations
• Prevents ignored files from being uploaded to the file server
• Patterns can be file names, directory names, or glob patterns

Note: By default, the CLI ignores common directories and dotfiles such as node_modules, .git, .vscode, and project-level dotfiles like .env.

includeBoardFiles

Type: array of file paths or glob strings (optional)

Defines which board source files tsci build and tsci snapshot evaluate automatically. Each entry can be a specific path or a glob. When omitted, tscircuit builds every board that matches the default patterns: **/*.board.tsx, **/*.circuit.tsx, and **/*.circuit.json.

Use Cases:

• Build a subset of boards: Focus CI or preview builds on a curated list of boards without reorganizing your project tree.

Example:

{
  "includeBoardFiles": [
    "boards/main-board.circuit.tsx",
    "modules/**/*.board.tsx"
  ]
}

Note: Paths and globs are resolved relative to the project root, just like mainEntrypoint.

snapshotsDir

Type: string (optional)

Sets a central directory for storing snapshot outputs generated by tsci snapshot.

Use Cases:

• Centralized snapshots: Keep snapshot artifacts in one folder instead of next to each board file.
• Cleaner source trees: Avoid scattering __snapshots__ folders throughout the project.

Example:

{
  "snapshotsDir": "snapshots"
}

How It Works:

• When snapshotsDir is set, snapshots are written under that directory, preserving the relative subdirectory of each board file.
• When omitted, snapshots are stored in a __snapshots__ folder adjacent to each board file, similar to Jest.

siteDefaultComponentPath

Type: string (optional)

Specifies the default component path shown in generated static sites.

Use Cases:

• Static catalog defaults: Choose which circuit appears by default when a site loads.

Example:

{
  "siteDefaultComponentPath": "examples/intro-board.circuit.tsx"
}

How It Works:

• Used by static site generation to select the initial circuit.
• If omitted, static sites fall back to the entrypoint detection logic (or mainEntrypoint).

prebuildCommand

Type: string (optional)

Command to run before builds.

Use Cases:

• Asset generation: Build prerequisites before invoking tsci build.

Example:

{
  "prebuildCommand": "bun run build:assets"
}

buildCommand

Type: string (optional)

Override command used for cloud builds.

Use Cases:

• Custom build pipelines: Point the cloud build system at an alternate build command.

Example:

{
  "buildCommand": "bun run build:cloud"
}

kicadLibraryEntrypointPath

Type: string (optional)

Entry file for KiCad footprint library generation.

Use Cases:

• KiCad library exports: Define which file is used to generate footprint libraries.

Example:

{
  "kicadLibraryEntrypointPath": "lib/kicad/index.tsx"
}

kicadLibraryName

Type: string (optional)

Name for the generated KiCad library. Falls back to package.json name, then the directory name.

Example:

{
  "kicadLibraryName": "custom-footprints"
}

alwaysUseLatestTscircuitOnCloud

Type: boolean (optional)

Force cloud builds to use the latest tscircuit version instead of the project-pinned version.

Example:

{
  "alwaysUseLatestTscircuitOnCloud": true
}

build

Type: object (optional)

Toggle build outputs for tsci build.

Example:

{
  "build": {
    "circuitJson": true,
    "kicadLibrary": false,
    "kicadPcm": true,
    "previewImages": true,
    "typescriptLibrary": false
  }
}

Options:

• circuitJson (boolean): Enable circuit JSON output in build.
• kicadLibrary (boolean): Enable KiCad library output in build.
• kicadPcm (boolean): Enable KiCad Plugin/Content Manager assets output in build.
• previewImages (boolean): Enable preview image outputs in build.
• typescriptLibrary (boolean): Enable TypeScript library output in build.