Skip to main content
Importing Modules and Chips

Installing KiCad Libraries

Overview​

You can install KiCad footprint libraries directly from GitHub using the tsci add or tsci install command. This is the easiest way to use existing KiCad footprints in your tscircuit projects, with automatic TypeScript type generation for full IDE support.

Installation​

To install a KiCad library from GitHub, use the tsci add command with the repository URL:

tsci add https://github.com/espressif/kicad-libraries
Adding https://github.com/espressif/kicad-libraries...
> bun add https://github.com/espressif/kicad-libraries
bun add v1.3.3 (274e01c7)

installed kicad-libraries@github:espressif/kicad-libraries#93d7c10

1 package installed [14.56s]
√ Added https://github.com/espressif/kicad-libraries successfully
Detected 47 KiCad footprint file(s), generating types...
√ Generated types at types/kicad-libraries.d.ts
√ Updated tsconfig.json with types directory
Initializing project in ./...
Installing dependencies...
bun add v1.3.3 (274e01c7)

installed @types/react@19.2.7
installed tscircuit@0.0.1010 with binaries:
 - tsci
 - tscircuit

[1065.00ms] done
Dependencies installed successfully.
√ Generated types for KiCad library: kicad-libraries
tip

tsci install is an alias for tsci add - both commands work identically.

What Happens During Installation​

When you install a repository containing .kicad_mod files, tsci will automatically:

  1. Add the package to package.json - The library is added as a dependency
  2. Install in node_modules - The package is downloaded and installed
  3. Detect KiCad footprints - Scans for .kicad_mod files in the repository
  4. Generate TypeScript types - Creates type definitions in types/<package-name>.d.ts
  5. Configure tsconfig.json - Adds the types directory to typeRoots

Using KiCad Footprints in Your Circuit​

After installation, you can import .kicad_mod files directly in your circuit code:

import kicadMod from "kicad-libraries/footprints/Espressif.pretty/ESP32-S2-MINI-1.kicad_mod"

export default () => {
  return (
    <board width="20mm" height="20mm">
      <chip footprint={kicadMod} name="U1" />
    </board>
  )
}

The imported kicadMod can be used directly as the footprint prop on components like <chip>.

ESP32-S2-MINI-1 PCB footprint

Generated Type Definitions​

When you install a KiCad library, tsci creates a type definition file in the types/ directory. For example, installing kicad-libraries creates types/kicad-libraries.d.ts:

declare module "kicad-libraries/footprints/Espressif.pretty/ESP32-S2-MINI-1.kicad_mod" {
  const value: string
  export default value
}

declare module "kicad-libraries/footprints/Espressif.pretty/ESP32-C3-MINI-1.kicad_mod" {
  const value: string
  export default value
}
// ... declarations for all .kicad_mod files in the library

This provides:

  • Full TypeScript support - No type errors when importing .kicad_mod files
  • IDE autocomplete - Your editor can suggest available footprint paths
  • Import validation - Catch typos in import paths at compile time

tsconfig.json Configuration​

The command automatically updates your tsconfig.json to include the types directory:

{
  "compilerOptions": {
    "typeRoots": ["./types", "./node_modules/@types"]
  }
}

If your project doesn't have a tsconfig.json, one will be created with the necessary configuration.

See Also​