step.parts: a searchable STEP catalog with an API, a SQLite index and a PR-only intake path

The problem is model provenance at the file level, not part discovery

Finding a STEP file for an M3 socket head cap screw is not hard. Finding one whose geometry you can trust, whose metadata you can query, and whose licence you can state in a hardware repo is harder. step.parts addresses the second problem. Each catalog entry, as the README describes it, pairs a canonical STEP file with human-authored metadata and generated preview assets. That pairing is the product. The directory is searchable and covers fasteners and hardware, stock and structural parts such as extrusion profiles and brackets, motion parts including bearings, gears, pulleys and linear-motion components, electronics and thermal parts such as development boards, connectors, heatsinks and fans, and actuators and robotics parts including servos, motors and gear reducers. The intended user is someone assembling a CAD assembly, a robot build, an electronics layout or a mechanical prototype who wants to pull a part in rather than model it. The repository is TypeScript, built on Next.js and React, MIT-licensed for original project material, and the README's own header line says 16,000+ parts while the repository description says 12,000+. That discrepancy is worth noting: the counts in this project move, and neither number is a quality signal.

Catalog data, SQLite index and Blob-hosted previews are three separate layers

The architecture visible in the README is a split between source data, a queryable index, and generated assets. Source records live in catalog/parts.json. Canonical STEP files live in catalog/step/. A regenerated SQLite catalog lives at catalog/parts.sqlite and the README describes it as refreshed as part of the add-part helper, which suggests it is a derived artifact rather than something edited by hand. Preview assets are generated as GLB and PNG, and the badge block points at Vercel Blob for preview hosting, with DEVELOPMENT.md sections named catalog-and-assets and preview-assets. The practical consequence is that the repository does not commit preview binaries: the contribution checklist states that local public/glb/ and public/png/ files should not be committed. The API is the read surface over this stack. It lives under https://api.step.parts/v1 and the README notes the app uses the same /v1 routes locally for server-side search, filtering, downloads and pagination, which means local development and production share one route implementation rather than diverging. Machine-readable descriptions are published at /v1/openapi.json, /v1/catalog/schema and /v1/catalog/parts.index.json, so a client can be generated or validated against the schema instead of scraping HTML.

The query surface is narrow and deliberately typed

The README lists four example lookups, and they reveal the intended query model. A plain page fetch: /v1/parts?pageSize=100. A free-text plus tag query: /v1/parts?q=M3&tag=screw&page=2. A structured query combining category, family and standard: /v1/parts?category=fastener&family=socket-head-cap-screw&standard=ISO%204762. And an attribute-style query on a numeric field: /v1/parts?q=lengthMm%2012. The third example is the one that matters. category, family and standard are distinct axes, so a socket head cap screw is not just a tag match, it is a position in a small taxonomy with a standard designation attached. That is what makes the catalog useful for BOM work: you can ask for a specific standard rather than hoping the free-text description mentions it. The fourth example, q=lengthMm 12, suggests attributes are queryable through the same free-text parameter, which is convenient but also a signal that attribute filtering may not have dedicated query parameters. The README does not document which attributes are indexed this way, so treat that as something to confirm against /v1/catalog/schema before designing around it.

Intake runs through one command that writes five things

Adding a part is a single interactive command, npm run catalog:add, and the README spells out its side effects: it prompts for a local STEP file path, part metadata, tags, aliases, optional standard details and attributes, then generates the part id, copies the STEP file into the catalog, updates the source catalog, refreshes SQLite catalog metadata, exports GLB and PNG previews, and validates everything. Five artifacts from one prompt. There is a dry-run mode that prints the generated record without writing files, and the README gives a full example with flags: npm run catalog:add -- --dry-run --step /path/to/part.step --name "Example part" --category fastener --family socket-head-cap-screw --tag screw --attr thread=M3. Note that the flags mirror the API's query axes, so the intake vocabulary and the query vocabulary are the same. Contributions are PR-only: create a branch, make catalog changes locally, run the checks, open a PR rather than pushing to main. The checks are npm run catalog:check, npm run lint and npx tsc --noEmit. Tag conventions live in TAGGING.md and the catalog schema, asset generation and deployment notes live in DEVELOPMENT.md.

The licence boundary is the sharpest edge in the project

This is the limitation that will bite a commercial team first. The repository is MIT-licensed for original project material, and the README is explicit that the MIT License does not relicense third-party-derived STEP or model files. The README states that some STEP files are copied from, modified from, adapted from, or generated using clearly licensed third-party model sources, and points to THIRD_PARTY_NOTICES.md for source, attribution, modification and licence details. The consequence is that the repository's licence badge tells you almost nothing about the individual file you are about to drop into a product assembly. A per-part licence check is not optional if the geometry ends up in something you ship. This is not legal advice and the notices file is the place to read the actual terms. The second limitation is structural: the intake path is a PR against a single repository, which means the catalog grows at the speed of review, and a part you need may simply not be there yet. There is no documented mechanism in the README for a private or local overlay catalog, so a team with proprietary parts is maintaining a fork or a separate index alongside this one. The third is that the README shows no versioned releases, and the repository's recent releases list is empty, so there is no tagged snapshot to pin against. You are tracking main.

Compared with a vendor portal or a CAD library bundle

The obvious alternative is a manufacturer's own CAD download portal, or a component library bundled with a CAD tool. Those differ from step.parts in a specific way: they are authoritative for the parts they cover. A vendor portal serves geometry the manufacturer stands behind, tied to a part number you can order, usually with a defined licence for use in designs. step.parts is the opposite trade. It is broad and queryable across many vendors and part families through one API, and the metadata is human-authored rather than vendor-issued. That breadth is why the licence situation is per-file rather than uniform, and why you should not expect a vendor part number to map cleanly onto a catalog entry. The second alternative is generating geometry parametrically, for example scripting fasteners from a standard table inside your CAD tool. That gives you exact control over the thread, length and head geometry, and no third-party licence question at all, at the cost of building and maintaining the generator. For a handful of standard fasteners, a generator is often the smaller commitment. For a wide spread of bearings, connectors, heatsinks and actuators, a catalog with a query API is the smaller commitment. The two approaches are not exclusive.

Running it locally and keeping it current

Local setup is short. Node.js 22.5 or newer is required, the repo includes .nvmrc so nvm use selects the same major version used in CI, then npm install and npm run dev, with the app on http://localhost:3000. Maintenance cost concentrates in three places. First, the catalog is a derived-artifact chain: catalog/parts.json feeds catalog/parts.sqlite, and previews are generated into GLB and PNG and hosted on Vercel Blob rather than committed. Any fork that regenerates the catalog needs that whole chain working, not just the JSON. Second, the validation gate is three commands (catalog:check, lint, tsc --noEmit) and the SQLite refresh happens inside catalog:add, so a contributor who edits parts.json by hand and skips the helper is likely to produce a source entry that disagrees with the index. Third, because there are no releases to pin, an upgrade means pulling main and re-running the checks; there is no changelog surface in the supplied material to tell you what moved. On the licence side, the maintenance cost is a review step, not a build step: every STEP file you take needs its entry in THIRD_PARTY_NOTICES.md read before the file goes into a shipped design, and that obligation does not go away when the repository's own MIT licence is permissive.

Editorial conclusion

Adopt step.parts if you need STEP geometry for fasteners, extrusion, bearings, boards or actuators and you want a query API rather than a zip of files: start from https://api.step.parts/v1/parts?pageSize=100 and check the licence fields on the specific parts you pull. Do not adopt it as a single source of truth for production BOM geometry, and do not treat the repository's MIT licence as covering every STEP file, because THIRD_PARTY_NOTICES.md exists precisely because it does not. Before you build on it, fetch https://api.step.parts/v1/openapi.json and https://api.step.parts/v1/catalog/schema and confirm the metadata fields your pipeline depends on are present in the records you actually need.

Official sources

1. earthtojake/step.parts on GitHub
2. Issues
3. License: MIT
4. Project website
5. README