Package Library
Gerbtrace includes a built-in library of component packages used to render footprints on the board canvas. The library supports both SMD (surface mount) and THT (through-hole) packages, with the ability to add custom team packages.
How packages are used
When PnP data is imported, Gerbtrace matches the CAD package name from each component against the library. Matched components render with accurate body outlines, pad geometry, and pin-1 markers. Unmatched components display a generic placeholder.
Built-in packages
Built-in packages are organized into libraries under public/packages/libraries/. Each library has:
- A
library.jsonwith attribution, license, and provenance metadata - Individual package JSON files defining the geometry
Current built-in libraries include:
- Gerbtrace (Newmatik) — core package definitions
- KiCad — packages derived from the KiCad footprint libraries
- DigiKey KiCad — packages from DigiKey's KiCad library
The runtime loads the library tree on demand, so only the packages you use are fetched.
Package types
All packages use TPSys (Mycronic) package type classifications:
| Type | Description | Typical packages |
|---|---|---|
PT_TWO_POLE | Two-terminal passives | Chip resistors, capacitors, diodes |
PT_THREE_POLE | Three-terminal devices | SOT-23 family |
PT_TWO_SYM | Dual-inline symmetric | SOIC, SSOP, TSSOP, DFN |
PT_FOUR_SYM | Quad-flat symmetric | QFP, QFN, LQFP |
PT_TWO_PLUS_TWO | Asymmetric quad | Different lead counts per side pair |
PT_FOUR_ON_TWO | Four leads on two sides | DO-214AA and similar |
PT_BGA | Ball Grid Array | BGA packages |
PT_OUTLINE | Outline only | No lead geometry |
PT_GENERIC | Generic with lead groups | Non-standard layouts |
See Package Definitions for the complete technical reference.
Searching and matching
The package library supports search by name and alias. When you type a package name in the PnP panel, the search matches against:
- Canonical package names (e.g.,
SOIC-8) - Aliases (e.g.,
SO-8,SO8,SOP-8all resolve toSOIC-8)
The lookup normalizes input by stripping separators and converting to uppercase, so common variations are handled automatically.
Team packages (SMD)
Teams can create custom SMD packages that are shared across all team members:
- Create a new package from the package manager
- Edit package geometry and properties
- Duplicate a built-in package as a starting point
- Delete team packages that are no longer needed
- Export packages as JSON or
.pck(TPSys format)
Team packages are stored in Supabase and available to all team members. Package names must be unique and cannot shadow built-in package names.
THT packages
THT (through-hole) packages use a separate visual system based on primitive shapes:
- Rectangles — for IC bodies, connectors
- Circles — for pins, mounting holes
- Rounded rectangles — for rounded pads
- Lines — for outlines and details
THT packages include:
- Pin positions and shapes
- Body graphics (from fabrication and silkscreen layers)
- Drill hole indicators
- Polarity markers near pin 1
Team THT packages
Like SMD packages, teams can create and share custom THT packages. The THT package editor provides a visual canvas where you can:
- Add and position shape primitives
- Customize colors for body, pins, and strokes
- Preview the package in real time
Package preview
The package manager includes a preview pane that renders each package with its full geometry, showing body outline, pads/balls, and pin-1 highlighting. This helps verify that a package definition is correct before assigning it to components.
CAD package mapping
When PnP data uses non-standard package names, you can create a mapping from the CAD package name to a library package. These mappings persist with the project, so subsequent imports of the same file use the established mapping automatically.