From ce40fda532e91e04c3bd028a70dd3e36d5c7e408 Mon Sep 17 00:00:00 2001 From: techmannih Date: Mon, 1 Jun 2026 23:49:38 +0530 Subject: [PATCH 1/4] docs: add TI parts engine platform config guide --- .../platform-configuration.md | 14 +++ .../using-ti-parts-engine.mdx | 85 +++++++++++++++++++ .../tscircuit-essentials/tscircuit-config.mdx | 9 ++ 3 files changed, 108 insertions(+) create mode 100644 docs/guides/running-tscircuit/using-ti-parts-engine.mdx diff --git a/docs/guides/running-tscircuit/platform-configuration.md b/docs/guides/running-tscircuit/platform-configuration.md index 9ead91ca..190743d8 100644 --- a/docs/guides/running-tscircuit/platform-configuration.md +++ b/docs/guides/running-tscircuit/platform-configuration.md @@ -15,6 +15,8 @@ Some use cases: - Organizations may want to customize the cloud autorouter to avoid sending sensitive designs outside your company - Organizations may want to introduce custom footprint strings using a prefix like `footprint="my-company:*"` +- Organizations may want to provide vendor-specific behavior, such as a custom + TI parts engine or `ti:` footprint library - Organizations may want to use their own internal registry for importing circuits instead of [tscircuit.com](https://tscircuit.com) - For [autorouting.com](https://autorouting.com), we configure the platform to not perform any autorouting @@ -89,6 +91,18 @@ await circuitRunner.renderUntilSettled() const circuitJson = await circuitRunner.getCircuitJson() ``` +## External Vendor Integrations + +Vendor-specific integrations do not need to be built into `@tscircuit/eval`. +You can provide them through a custom platform configuration instead. + +For a concrete example, see +[Using ti-parts-engine](./using-ti-parts-engine). That guide shows: + +- how to provide a custom TI-backed `partsEngine` +- how to enable explicit `footprint="ti:..."` strings when needed +- how to keep partner-token usage in local tooling instead of browser clients + :::info Interested in running the entire tscircuit platform privately inside your company? We're happy to help! Reach out to **enterprise@tscircuit.com** diff --git a/docs/guides/running-tscircuit/using-ti-parts-engine.mdx b/docs/guides/running-tscircuit/using-ti-parts-engine.mdx new file mode 100644 index 00000000..799508fb --- /dev/null +++ b/docs/guides/running-tscircuit/using-ti-parts-engine.mdx @@ -0,0 +1,85 @@ +--- +title: Using ti-parts-engine +description: Configure TI-backed part lookup and explicit `ti:` footprints through a custom platform config +sidebar_position: 5 +--- + +`@tscircuit/ti-parts-engine` is an external helper package for local TI-backed +development workflows. It is not built into `@tscircuit/eval` by default. +Instead, provide it through a custom platform configuration. + +## Install from GitHub + +`ti-parts-engine` is currently installed directly from GitHub: + +```bash +bun add -D github:tscircuit/ti-parts-engine +``` + +## Use TI as a Custom Parts Engine + +If your local tooling loads a JS/TS platform config module, you can keep the TI +parts engine in a `tscircuit.config.ts`-style file: + +```ts +import { createTiPartsEngine } from "@tscircuit/ti-parts-engine" + +export default { + platformConfig: { + partsEngine: createTiPartsEngine({ + // local CLI/dev usage only + partnerToken: process.env.PARTNER_TOKEN!, + }), + }, +} +``` + +This wires TI-backed automatic part lookup through `platform.partsEngine`. + +:::info +Keep `PARTNER_TOKEN` in local development tooling only. Do not expose it to +browser clients or commit it to your repository. +::: + +## Use Explicit `ti:` Footprint Strings + +If you want to use explicit footprint strings such as +`footprint="ti:MSP430"`, you also need a TI footprint library mapping. The +easiest way to wire both pieces together is `createTiPlatformConfig(...)`: + +```ts +import { createTiPlatformConfig } from "@tscircuit/ti-parts-engine" + +export default { + platformConfig: createTiPlatformConfig({ + partnerToken: process.env.PARTNER_TOKEN!, + }), +} +``` + +This configures: + +- `partsEngine` for TI-backed part lookup +- `footprintLibraryMap.ti` for explicit `ti:` footprint strings + +If you only provide `createTiPartsEngine(...)`, automatic TI part lookup works, +but the `ti:` footprint prefix is not added by itself. + +## Programmatic Usage + +You can also pass the same platform config directly when creating a runner or +root circuit: + +```ts +import { createTiPlatformConfig } from "@tscircuit/ti-parts-engine" +import { RootCircuit } from "@tscircuit/core" + +const circuit = new RootCircuit({ + platform: createTiPlatformConfig({ + partnerToken: process.env.PARTNER_TOKEN!, + }), +}) +``` + +For more background on platform customization, see +[Platform Configuration](./platform-configuration). diff --git a/docs/guides/tscircuit-essentials/tscircuit-config.mdx b/docs/guides/tscircuit-essentials/tscircuit-config.mdx index 18ec9ad4..20872703 100644 --- a/docs/guides/tscircuit-essentials/tscircuit-config.mdx +++ b/docs/guides/tscircuit-essentials/tscircuit-config.mdx @@ -5,6 +5,15 @@ description: Configure your tscircuit project settings 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`. +`tscircuit.config.json` is designed for serializable project settings. It is a +good place for entrypoints, build options, snapshot preferences, and other JSON +configuration. + +If you need function-valued platform settings such as a custom `partsEngine` or +`footprintLibraryMap`, keep those in a separate JS/TS module and pass that +platform config from your runtime or local tooling instead of trying to embed +them directly in `tscircuit.config.json`. + ## Example ```json From d57115df0abe283b8d64981d42cf288b22c0fb21 Mon Sep 17 00:00:00 2001 From: techmannih Date: Mon, 1 Jun 2026 23:53:02 +0530 Subject: [PATCH 2/4] update --- docs/guides/running-tscircuit/platform-configuration.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/guides/running-tscircuit/platform-configuration.md b/docs/guides/running-tscircuit/platform-configuration.md index 190743d8..c9793a23 100644 --- a/docs/guides/running-tscircuit/platform-configuration.md +++ b/docs/guides/running-tscircuit/platform-configuration.md @@ -15,8 +15,6 @@ Some use cases: - Organizations may want to customize the cloud autorouter to avoid sending sensitive designs outside your company - Organizations may want to introduce custom footprint strings using a prefix like `footprint="my-company:*"` -- Organizations may want to provide vendor-specific behavior, such as a custom - TI parts engine or `ti:` footprint library - Organizations may want to use their own internal registry for importing circuits instead of [tscircuit.com](https://tscircuit.com) - For [autorouting.com](https://autorouting.com), we configure the platform to not perform any autorouting @@ -93,7 +91,6 @@ const circuitJson = await circuitRunner.getCircuitJson() ## External Vendor Integrations -Vendor-specific integrations do not need to be built into `@tscircuit/eval`. You can provide them through a custom platform configuration instead. For a concrete example, see From f6a85542c428c20dfb2058949cd605c5b225e0e9 Mon Sep 17 00:00:00 2001 From: techmannih Date: Mon, 1 Jun 2026 23:59:33 +0530 Subject: [PATCH 3/4] update --- .../tscircuit-essentials/tscircuit-config.mdx | 60 +++++++------------ 1 file changed, 20 insertions(+), 40 deletions(-) diff --git a/docs/guides/tscircuit-essentials/tscircuit-config.mdx b/docs/guides/tscircuit-essentials/tscircuit-config.mdx index 20872703..fa0785b5 100644 --- a/docs/guides/tscircuit-essentials/tscircuit-config.mdx +++ b/docs/guides/tscircuit-essentials/tscircuit-config.mdx @@ -5,50 +5,34 @@ description: Configure your tscircuit project settings 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`. -`tscircuit.config.json` is designed for serializable project settings. It is a -good place for entrypoints, build options, snapshot preferences, and other JSON -configuration. - -If you need function-valued platform settings such as a custom `partsEngine` or -`footprintLibraryMap`, keep those in a separate JS/TS module and pass that -platform config from your runtime or local tooling instead of trying to embed -them directly in `tscircuit.config.json`. - ## Example ```json { "mainEntrypoint": "lib/circuits/main-board.tsx", - "ignoredFiles": [ - "dist", - "build", - "coverage", - "*.log", - ".DS_Store", - "temp" - ] + "ignoredFiles": ["dist", "build", "coverage", "*.log", ".DS_Store", "temp"] } ``` ## Configuration Options -| Property | Description | -| --- | --- | -| `$schema` | [Optional JSON schema reference for editor tooling.](#schema) | -| `mainEntrypoint` | [Primary entry file for builds and dev workflows.](#mainentrypoint) | -| `previewComponentPath` | [Overrides which component is used for preview images/GLTF.](#previewcomponentpath) | -| `siteDefaultComponentPath` | [Default component shown in generated static sites.](#sitedefaultcomponentpath) | -| `ignoredFiles` | [Extra file and directory ignore patterns for CLI workflows.](#ignoredfiles) | -| `includeBoardFiles` | [Glob list for which board files are built or snapshotted.](#includeboardfiles) | -| `snapshotsDir` | [Centralized directory for snapshot outputs.](#snapshotsdir) | -| `prebuildCommand` | [Command to run before builds.](#prebuildcommand) | -| `buildCommand` | [Override command used for cloud builds.](#buildcommand) | -| `kicadProjectEntrypointPath` | [Entry file for KiCad project generation.](#kicadprojectentrypointpath) | -| `kicadLibraryEntrypointPath` | [Entry file for KiCad footprint library generation.](#kicadlibraryentrypointpath) | -| `kicadLibraryName` | [Name for the generated KiCad library.](#kicadlibraryname) | +| Property | Description | +| --------------------------------- | ----------------------------------------------------------------------------------- | +| `$schema` | [Optional JSON schema reference for editor tooling.](#schema) | +| `mainEntrypoint` | [Primary entry file for builds and dev workflows.](#mainentrypoint) | +| `previewComponentPath` | [Overrides which component is used for preview images/GLTF.](#previewcomponentpath) | +| `siteDefaultComponentPath` | [Default component shown in generated static sites.](#sitedefaultcomponentpath) | +| `ignoredFiles` | [Extra file and directory ignore patterns for CLI workflows.](#ignoredfiles) | +| `includeBoardFiles` | [Glob list for which board files are built or snapshotted.](#includeboardfiles) | +| `snapshotsDir` | [Centralized directory for snapshot outputs.](#snapshotsdir) | +| `prebuildCommand` | [Command to run before builds.](#prebuildcommand) | +| `buildCommand` | [Override command used for cloud builds.](#buildcommand) | +| `kicadProjectEntrypointPath` | [Entry file for KiCad project generation.](#kicadprojectentrypointpath) | +| `kicadLibraryEntrypointPath` | [Entry file for KiCad footprint library generation.](#kicadlibraryentrypointpath) | +| `kicadLibraryName` | [Name for the generated KiCad library.](#kicadlibraryname) | | `alwaysUseLatestTscircuitOnCloud` | [Force latest tscircuit version in cloud builds.](#alwaysuselatesttscircuitoncloud) | -| `build` | [Build output toggles for CLI builds.](#build) | -| `pcbSnapshotSettings` | [Rendering options for PCB snapshots and preview images.](#pcbsnapshotsettings) | +| `build` | [Build output toggles for CLI builds.](#build) | +| `pcbSnapshotSettings` | [Rendering options for PCB snapshots and preview images.](#pcbsnapshotsettings) | ### $schema @@ -145,13 +129,7 @@ Specifies paths or directory names that should be ignored when the dev server sy ```json { - "ignoredFiles": [ - "dist", - "build", - ".git", - "*.log", - "temp" - ] + "ignoredFiles": ["dist", "build", ".git", "*.log", "temp"] } ``` @@ -362,6 +340,7 @@ Toggle build outputs for `tsci build`. ``` **Options:** + - `circuitJson` (`boolean`): Enable circuit JSON output in build. - `kicadProject` (`boolean`): Enable KiCad project output (`.kicad_pro`, `.kicad_sch`, `.kicad_pcb`) in build. - `kicadLibrary` (`boolean`): Enable KiCad library output in build. @@ -390,6 +369,7 @@ Controls rendering options for PCB images generated by `tsci snapshot` and `tsci ``` **Options:** + - `showCourtyards` (`boolean`): Render courtyard outlines around components. Courtyards define the keepout boundary for a footprint. Defaults to `false`. - `showPcbNotes` (`boolean`): Render PCB notes layer in the output image. Defaults to `false`. - `showFabricationNotes` (`boolean`): Render fabrication notes layer in the output image. Defaults to `false`. From 451c6207ab2776bd436e7f8031e080d0083af99c Mon Sep 17 00:00:00 2001 From: techmannih Date: Tue, 2 Jun 2026 00:04:16 +0530 Subject: [PATCH 4/4] update --- .../using-ti-parts-engine.mdx | 50 ++++++++++++++----- 1 file changed, 37 insertions(+), 13 deletions(-) diff --git a/docs/guides/running-tscircuit/using-ti-parts-engine.mdx b/docs/guides/running-tscircuit/using-ti-parts-engine.mdx index 799508fb..36b2340e 100644 --- a/docs/guides/running-tscircuit/using-ti-parts-engine.mdx +++ b/docs/guides/running-tscircuit/using-ti-parts-engine.mdx @@ -4,17 +4,11 @@ description: Configure TI-backed part lookup and explicit `ti:` footprints throu sidebar_position: 5 --- -`@tscircuit/ti-parts-engine` is an external helper package for local TI-backed -development workflows. It is not built into `@tscircuit/eval` by default. -Instead, provide it through a custom platform configuration. +`@tscircuit/ti-parts-engine` helps you provide TI-backed behavior through a +custom platform configuration in local development workflows. -## Install from GitHub - -`ti-parts-engine` is currently installed directly from GitHub: - -```bash -bun add -D github:tscircuit/ti-parts-engine -``` +This guide assumes `@tscircuit/ti-parts-engine` is available in your local +development environment. ## Use TI as a Custom Parts Engine @@ -65,13 +59,43 @@ This configures: If you only provide `createTiPartsEngine(...)`, automatic TI part lookup works, but the `ti:` footprint prefix is not added by itself. -## Programmatic Usage +## Example User Project Files + +If your local tooling supports a JS/TS platform config module, a minimal TI +footprint project can look like this: -You can also pass the same platform config directly when creating a runner or -root circuit: +`index.circuit.tsx` + +```tsx +export default () => ( + + + +) +``` + +`tscircuit.config.ts` ```ts import { createTiPlatformConfig } from "@tscircuit/ti-parts-engine" + +export default { + platformConfig: createTiPlatformConfig({ + // local CLI/dev usage only + partnerToken: process.env.PARTNER_TOKEN!, + }), +} +``` + +This is a local CLI/dev style workflow. Do not expose a real `PARTNER_TOKEN` +to browser clients. + +## Programmatic Usage + +You can also pass the same `createTiPlatformConfig(...)` result directly when +creating a runner or root circuit: + +```ts import { RootCircuit } from "@tscircuit/core" const circuit = new RootCircuit({