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
mainEntrypoint	Primary entry file for builds and dev workflows.
previewComponentPath	Overrides which component is used for preview images/GLTF.
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.

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.