soldermaskdocs

Parts and packages

The parts stage turns each part the design describes into a real part you can order from JLCPCB, with a footprint to draw it. A part it cannot find is taken off the board and named in the gaps list.

The stage is resolve.resolve(design). It returns a netlist of ordered parts, with a gap or a note for everything it could not do exactly as asked.

A part that did not resolve also fails the board's verdict. The pass rule needs every part real and drawable. A part that is out of stock today still passes.

Where parts come from

Parts come from the catalogue on disk. jlcsearch answers only when that catalogue cannot.

SourceAnswers whenWhat it is
The catalogue on disk, under .cache/jlcparts/Always, once it existsJLCPCB's own catalogue or the jlcparts mirror, whichever was written last
jlcsearch, over the networkThe catalogue on disk cannot answerA free, unauthenticated server, used as the last resort

The catalogue on disk is one of these two:

CatalogueWritten whenWhat it is
JLCPCB's ownsoldermask setup --parts runs with API credentials, and the app is granted the Parts APIEvery LCSC code with stock, written from the vendor's API
The jlcparts mirrorOtherwiseyaqwsx/jlcparts (MIT), rebuilt upstream daily

The catalogue on disk is the answer, including an empty one. A search it answers with nothing is not sent over the network to the same data again. A part costs two small cached reads: a lookup bucket and a shard.

JLCPCB's API

jlcapi.py signs its requests with three environment variables: JLCPCB_APP_ID, JLCPCB_ACCESSKEY and JLCPCB_SECRETKEY. The app must also be granted the Parts API in JLCPCB's console. soldermask setup --check says whether it is.

The API has no search, so it is the source the local catalogue is written from. With the grant, soldermask setup --parts does it in four steps:

  1. Download the whole LCSC listing: about 7.25 million records, of which about 723,000 have stock. This takes about an hour.
  2. Fetch a detail record for every code with stock, 1,000 codes a call. This takes about 15 minutes. The parameters are only in these records.
  3. Write the catalogue in the mirror's own format (jlcapi.ingest()), so every reader works unchanged.
  4. Build the parametric index over it (params.build()).

Without credentials or the grant, setup --parts downloads every mirror file a build can read instead. A catalogue already written from the API is kept.

Parts with no stock are left out of the catalogue (jlcapi.MIN_STOCK). The raw download under .cache/jlcapi/<day>/ keeps them all, so the choice can be revisited without the network.

The API catalogue does not refresh itself

The mirror's daily refresh never replaces a catalogue written from the API. Its stock and prices are from the day setup --parts last ran, until you run it again. soldermask setup prints that date:

parts   1645 files, complete -- 723,227 components, from JLCPCB's API 2026-09-16

Prefer the API catalogue where you can. Checked against the vendor's own download, the mirror's package field was wrong on 259,001 rows and blank on 155,262.

The mirror

Without setup --parts, a build fetches each mirror file the first time it needs it, and keeps it. The mirror's manifest is checked once a day. A kept file is fetched again when the manifest says it has changed.

A mirror that names fewer than half the components of a whole build is treated as unable to answer. A partial mirror would otherwise say no such part about parts it has simply not downloaded.

The mirror carries two things jlcsearch does not. One is joints, the pad count. The other is the full set of parametric attributes behind the value index. jlcsearch is built from the same data.

jlcsearch

jlcsearch answers only when the catalogue on disk cannot. That happens when there is no manifest and no way to fetch one, a shard will not read, or an index will not open.

BehaviourSetting
Responses cached for 24 hours.cache/parts
A failed request remembered for an hour, so it is not asked again mid-buildparts.FAIL_TTL
Wait for an answer10 s (parts.TIMEOUT_S)
Network downThe stale cache is used
Ask jlcsearch instead of the catalogue on disk, to compare the two. The parametric and part-number indexes still answer first.SOLDERMASK_PARTS=jlcsearch

It has no service agreement and a rate limit. In the first full orderability run, 40 of its 76 "unsourceable" parts were its rate limiter, not the catalogue.

The stock and price you are quoted

parts.authoritative() reads stock, price and the basic flag from one source, so a bill of materials and a re-check of it agree.

MachineSource
API credentials set, and the app granted the Parts APIJLCPCB's API, asked for each part as it resolves
Anything elseThe catalogue on disk, or jlcsearch when that catalogue cannot answer

Without the API, the figures are as old as the catalogue on disk. That is the mirror's last daily build, or the last setup --parts.

The stock check looks each part up again by exact LCSC code, in the same catalogue. See Stock and pricing.

The query ladder

A component that carries an lcsc code skips the search. It is looked up by that code and ordered as chosen, without checking it against the line. Codes come from these places:

WhereWhich code
The claude-code design backendOnly a code that search_parts or pins returned in the same turn. Any other is removed and named in unsupported. See Design.
An MCP clientThe code it chose, usually from search_parts
Library → Parts in the workbenchThe row a person chose
A rebuild of a stored version, such as Route againThe code each part was ordered as

A pinned code JLCPCB does not list is a gap: R3: C99999999 is not a part JLCPCB lists. A pinned part whose package does not fit the declared footprint is kept, with a note to check the fit.

Every other component climbs a ladder of searches:

  1. Value. A resistor, capacitor, inductor or crystal with a value asks the parametric index. Each row is checked against the value its own listing states.
  2. Part number. A normalised prefix match on the number (params.find_mpn). It keeps only the number asked for, give or take a packaging suffix or a grade letter.
  3. Text. It searches four forms in turn:
    • the search phrase as written;
    • its first word, if that looks like a part number;
    • the value;
    • that first word with a trailing letter suffix trimmed (LMV358IDR → LMV358).
  4. Generic terms for the kind, such as pin header, USB-C or crystal. These run only when nothing clean was found above.

Each rung adds what it finds to one pool. A rung ends the search only when its best part is clean. Clean means the package and mounting asked for, and the number asked for when the part was named by number. Otherwise the ladder carries on, and the best part in the whole pool wins.

A trailing digit is never trimmed

AMS1117-3.3 is never shortened to AMS1117. That search could return the 5 V part, which places, routes, passes ERC and destroys whatever the board powers. The text search also skips the value for a part named by number: the value describes that part, and searching it finds a different one.

Why the index and the number go first

The parametric index matches values in the catalogue's own attribute table (attributes-lut.json.gz), in SI units. On 105 jellybean queries it picked the right part 99% of the time, against 61% for text search, in 3.6 ms against 537 ms.

setup --parts builds the index after it writes an API catalogue. Otherwise build it with tools/parametric_index.py build. The ladder starts at the next rung when there is no index. It also does when the attribute table has changed since the index was built, and soldermask setup says so.

A part number written from memory often differs from the listing by a suffix or a hyphen. The normalised prefix match still finds it.

Which part wins

A candidate is dropped when any of these holds:

  • It does not fit the footprint, such as a 2-pin header for a 4-pad footprint.
  • JLCPCB files it under a different kind, and its number is not the one asked for.
  • It has more pads than its kind can have.
  • It states a pin count other than the one asked for.
  • A resistor, capacitor or inductor states a rating, tolerance, dielectric or power below the ask. A 25 V capacitor on a 50 V ask is one.

The survivors are sorted by, in order:

  1. In stock.
  2. The exact number asked for, then the number with a suffix.
  3. Category confirmed, and a description that does not name another kind.
  4. Pin count confirmed.
  5. Package confirmed by the listing, then mounting as asked.
  6. A description that names the kind.
  7. For a resistor, capacitor or inductor, a listing that states the rating asked for.
  8. Closest text match (not used for resistors, capacitors and inductors).
  9. Basic before extended.
  10. More stock, then lower price.

Stock is a preference, not a gate. A real part that shows 0 today still resolves, with a note, because stock changes hourly.

When the part is not what was asked

Every way the ordered part differs from the line is said once, in the notes. Examples:

  • The number is not listed, and a part a letter or two off is ordered.
  • The number is listed only with a suffix.
  • The package or the mounting differs from the one asked.
  • A rating was asked for and the listing states none.
  • The part has no CAD data, so the next match that has some is ordered.

A part with no match at all is dropped from the netlist. The gap reads R3: no JLCPCB part exists for '10k' in 0603.

A connector, IC or module named by a number JLCPCB does not list is dropped too when only its kind found anything. A pin header found for a battery holder is a different thing, not a substitute. The gap says to describe the part or pin a code from search_parts.

A network outage is reported as an outage, never as a missing part:

R3: could not reach JLCPCB to check stock (…) -- this is an outage here, not a statement about the part

Basic and extended

JLCPCB charges a setup fee for each distinct extended (non-basic) part. The pipeline counts it at $3 each in the bill of materials and the stock report. The design stage is told to prefer basic parts.

Supported packages

The footprints drawn by hand, IPC style:

FamilyPackages
Chip0402 0603 0805 1206
Transistor and diodeSOT-23 SOT-23-3 SOT-223 SOD-123
ICSOIC-8 SOP-8 SOIC-16 TSSOP-20
Single-row headerHDR-1x2 HDR-1x3 HDR-1x4 HDR-1x6 HDR-1x8
Dual-row headerHDR-2x2 HDR-2x3 HDR-2x4 HDR-2x5 HDR-2x8 HDR-2x10 HDR-2x20

The model is also offered every footprint in the imported KiCad set (soldermask/assets/footprints.json) that has a standard name and at most 48 pins. Standard names include chip sizes, SOIC, TSSOP, QFN, QFP, SOT, TO-, LED, USB, PinHeader, Crystal and SW_. The 48-pin limit holds on four layers too. A larger part comes in as FROM_PART. A hand-drawn footprint wins a name clash.

JLCPCB's spellings are read as the standard name: 0603 (1608 Metric) is 0603, SOT23-3 is SOT-23-3, and SOIC-8_150mil is SOIC-8.

Every package carries:

  • pads, with position, size, shape, and drill for a through-hole pad;
  • a body outline and a 0.25 mm courtyard margin;
  • a 3D profile (height, lead style and standoff), used to draw the part when the vendor has no 3D model. Lead styles are chip, gullwing, tab, noleads, dome, header, block, shell and button.

FROM_PART

One more name is offered, and it is not a footprint: FROM_PART. It means no package is named. A module, a radio or a radar has no IPC name and one correct footprint: the vendor's, for the part ordered. FROM_PART takes the footprint and the pin names from that part, so the search must name it.

Footprints from the vendor

When the package is FROM_PART or a name JLCPCB does not use, the part's own footprint comes from EasyEDA (easyeda.py). Of the 99 package names offered to the model, 61 can never match a JLCPCB package string.

  • The footprint is cached under .cache/easyeda, so a build fetches it once.
  • The board carries a note: … so the footprint is C12345's own (8 pads, 4.9x3.9mm) as published by the vendor, not IPC-verified, check it before ordering.
  • When EasyEDA refuses after its retries, the same drawing is asked of tscircuit's copy (jlcsearch.tscircuit.com/api/easyeda_components). It is never asked first.
  • When neither answers and there is no footprint to draw instead, the gap says it is an outage, not a statement about the part.

Checking the vendor against our footprint

When the pipeline draws its own footprint, it still compares the vendor's drawing of the ordered part with it:

What it findsWhat happens
The vendor draws the part turned 90, 180 or 270 degrees from oursThe assembly angle is turned back, so the part lands on our pads. A note says so.
A pad more than 0.35 mm off even at the best turn (easyeda.TOLERANCE_MM)A note says to check the datasheet. Nothing is adjusted: only the datasheet can tell a variant from a bad footprint.
No CAD data, or no shared pad namesThe angle goes to the fab uncorrected, and a note says to check polarised parts by hand

Alternates

alternates.py proposes in-stock replacements for a part with a no JLCPCB part exists gap. They appear only in the brief that --repair N hands back to the model. Every candidate shares the exact same KiCad symbol pinout, so it is pin-compatible by construction.

Pin-compatible is not the same part. 84% of such pinout classes are one family that differs only by a number: AMS1117-1.5 and AMS1117-3.3 share every pin and nothing else. So a candidate whose rating differs from the original's is never offered, and neither is one of the same family whose rating cannot be read. The rest are marked in one of two ways:

Mark in the briefConfidenceMeans
swap-safevalue-matchedThe rating reads the same from both part numbers. Safe to swap.
CHECK RATINGpinout-onlyAnother family with the same pins, and at least one part number states no rating. A person must confirm it.

Datasheet records

A part's datasheet record holds the external parts and limits the design check applies to it. soldermask parts show <LCSC> prints one. See Command line.

On this page