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.
| Source | Answers when | What it is |
|---|---|---|
The catalogue on disk, under .cache/jlcparts/ | Always, once it exists | JLCPCB's own catalogue or the jlcparts mirror, whichever was written last |
| jlcsearch, over the network | The catalogue on disk cannot answer | A free, unauthenticated server, used as the last resort |
The catalogue on disk is one of these two:
| Catalogue | Written when | What it is |
|---|---|---|
| JLCPCB's own | soldermask setup --parts runs with API credentials, and the app is granted the Parts API | Every LCSC code with stock, written from the vendor's API |
| The jlcparts mirror | Otherwise | yaqwsx/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:
- Download the whole LCSC listing: about 7.25 million records, of which about 723,000 have stock. This takes about an hour.
- 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.
- Write the catalogue in the mirror's own format (
jlcapi.ingest()), so every reader works unchanged. - 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-16Prefer 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.
| Behaviour | Setting |
|---|---|
| Responses cached for 24 hours | .cache/parts |
| A failed request remembered for an hour, so it is not asked again mid-build | parts.FAIL_TTL |
| Wait for an answer | 10 s (parts.TIMEOUT_S) |
| Network down | The 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.
| Machine | Source |
|---|---|
| API credentials set, and the app granted the Parts API | JLCPCB's API, asked for each part as it resolves |
| Anything else | The 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:
| Where | Which code |
|---|---|
The claude-code design backend | Only a code that search_parts or pins returned in the same turn. Any other is removed and named in unsupported. See Design. |
| An MCP client | The code it chose, usually from search_parts |
| Library → Parts in the workbench | The row a person chose |
| A rebuild of a stored version, such as Route again | The 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:
- 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.
- 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. - Text. It searches four forms in turn:
- the
searchphrase 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).
- the
- Generic terms for the kind, such as
pin header,USB-Corcrystal. 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:
- In stock.
- The exact number asked for, then the number with a suffix.
- Category confirmed, and a description that does not name another kind.
- Pin count confirmed.
- Package confirmed by the listing, then mounting as asked.
- A description that names the kind.
- For a resistor, capacitor or inductor, a listing that states the rating asked for.
- Closest text match (not used for resistors, capacitors and inductors).
- Basic before extended.
- 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 partBasic 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:
| Family | Packages |
|---|---|
| Chip | 0402 0603 0805 1206 |
| Transistor and diode | SOT-23 SOT-23-3 SOT-223 SOD-123 |
| IC | SOIC-8 SOP-8 SOIC-16 TSSOP-20 |
| Single-row header | HDR-1x2 HDR-1x3 HDR-1x4 HDR-1x6 HDR-1x8 |
| Dual-row header | HDR-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,shellandbutton.
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 finds | What happens |
|---|---|
| The vendor draws the part turned 90, 180 or 270 degrees from ours | The 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 names | The 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 brief | Confidence | Means |
|---|---|---|
swap-safe | value-matched | The rating reads the same from both part numbers. Safe to swap. |
CHECK RATING | pinout-only | Another 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.
Design (the model)
The design stage turns a prompt into a structured design: the parts, the nets and a board size. Everything after it builds from that design, and none of it knows which model wrote it.
Symbols and pins
The design names every pin by what it does, such as VIN or SDA, and never by its number. This stage finds each part's symbol and turns every name into the pad it lands on.