I Packaged Our Tariff Engine for npm — Versioned Data, Zero Dependencies, and Trusted Publishing

Description and use

Packaging the tariff calculation engine into an npm package delivers reproducible, auditable results without external dependencies.

Problem

US tariff calculations change frequently, making it hard to reproduce past quotes and answer audit questions.

Outcome

The packaged engine delivers reproducible, auditable tariff calculations without external dependencies, simplifying CI pinning and audit trails.

Workflow

• 1. Bundle the ruleset JSON and TypeScript engine into a single ESM package using esbuild with platform neutral and minify options.
• 2. Ensure the published artifact is built only from public, cleaned data by removing internal metadata paths.
• 3. Publish the package to npm staging, obtain manual approval, then promote to live.
• 4. Consume the package in client code by importing rulesetSeed, searchHts, and calculateLandedCost, passing entryDate and other parameters.
• 5. Receive deterministic results that include legalBasis, source URLs, and status for each layer, enabling auditability.

Evidence

US tariff math has a reproducibility problem. The rules changed roughly five times a month through 2026 — new Section 301 tiers, sector measures, fee schedules — and every change retroactively makes your old quotes look wrong.

Source

The package ships one versioned seed — rulesetVersion and dataAsOf right in the JSON — and the engine is a set of pure functions over it.

Source

The build is a thin esbuild script: ... platform: 'neutral' keeps Node built-ins out of the bundle graph, minified ruleset JSON inlines into the output, and a hand-written CLI (bin: us-tariff) gets copied in as a separate file.

Source

npm's flow for a first-time publisher turned out to be sensibly paranoid: publish to staging, a human approves, then it goes live.

Source