Smithy Core (@smithy/core)

@smithy/core is the internal-but-load-bearing runtime package inside the smithy-lang/smithy-typescript monorepo, the reference TypeScript code generator for Smithy-modeled services. Rather than shipping as dozens of micro-packages that every generated client would need to install separately, @smithy/core consolidates commonly used runtime building blocks — middleware stacks, serialization/deserialization, endpoint resolution, retry logic, CBOR/JSON codecs, and schema-driven type registries — behind a single package with exports-based submodules (@smithy/core/cbor, @smithy/core/protocols, @smithy/core/serde, and more). It is the common dependency that AWS SDK for JavaScript v3 clients (e.g. @aws-sdk/client-s3, @aws-sdk/client-dynamodb) and other Smithy-generated TypeScript clients pull in for cross-cutting request/response plumbing, letting Node.js initialization stay fast while keeping a single consistent version of core logic instead of package sprawl.

While most application developers never add @smithy/core directly to their own package.json — it’s installed transitively as part of code generation — understanding it is essential for anyone debugging AWS SDK v3 internals, building custom Smithy protocol generators, or writing their own Smithy-based TypeScript client/server. It packages middleware for HTTP auth schemes and signing, endpoint rule-set resolution, a schema/type registry for runtime (de)serialization, retry and error-classification logic, and CBOR/RPCv2 protocol codecs — the full request lifecycle a generated client needs, in one well-versioned dependency.

What You Get

• A unified exports-based package (@smithy/core/cbor, /protocols, /serde, /schema, /retry, /config, /client, /endpoints, /checksum, /event-streams, /transport) that replaces what used to be dozens of separately versioned @smithy/* micro-packages
• HTTP auth-scheme and signing middleware (httpAuthSchemeMiddleware, httpSigningMiddleware) plus identity-and-auth helpers used by every generated client’s request pipeline
• A runtime TypeRegistry and NormalizedSchema system that lets generated clients validate, serialize, and deserialize shapes from compact static schema definitions instead of bulky per-shape generated code
• Built-in CBOR codec and SmithyRpcV2Cbor protocol support, plus the middleware stack, retry/error-classification, and endpoint rule-set resolution shared across the AWS SDK for JavaScript v3
• Backwards-compatible root-level re-exports (normalizeProvider, createPaginator, setFeature) so packages migrating off the older micro-package layout keep working without churn

Common Use Cases

• Powering the request/response plumbing of every @aws-sdk/client-* package in the AWS SDK for JavaScript v3, transitively installed rather than depended on directly
• Serving as the runtime target for custom Smithy protocol generators that need middleware, serde, and schema primitives without reinventing them
• Providing the schema/type-registry layer for RPCv2 CBOR and JSON-based Smithy protocols so generated clients can (de)serialize shapes at runtime
• Giving teams building their own Smithy-modeled TypeScript client or server SDK a ready-made runtime core instead of assembling middleware, retry, and endpoint resolution from scratch

Under The Hood

Architecture: @smithy/core is organized as a “mono-package within the monorepo” (per its own README) — instead of the traditional one-package-per-concern layout used elsewhere in smithy-typescript (e.g. middleware-retry, protocol-http), its src/submodules/ directory groups over a dozen previously standalone concerns (retry, config, schema, serde, cbor, checksum, client, endpoints, event-streams, protocols, transport) behind package.json exports entries, each independently bundled to dist-cjs/dist-es via an internal Inliner.js build script and validated by a custom submodules linter (scripts/validation/submodules-linter.js) that runs on every build. src/index.ts re-exports a small backwards-compatible root API (auth-scheme middleware, normalizeProvider, createPaginator, setFeature) while the bulk of functionality lives behind scoped submodule imports like @smithy/core/protocols and @smithy/core/schema, which the schema-driven TypeRegistry and NormalizedSchema classes use to cache and resolve shape metadata for runtime (de)serialization — a deliberate move away from per-shape generated serde code toward compact static schemas. Tech Stack: Pure TypeScript targeting es2015/CommonJS with dual ESM/CJS output (dist-es, dist-cjs, dist-types) built via tsc plus a custom es_cjs.js compilation script, downlevel .d.ts generation for TypeScript <4.5 compatibility back to ts3.4, and Yarn workspaces/Turborepo for monorepo orchestration; runtime dependencies are minimal — just @smithy/types and tslib — keeping the package lightweight despite its broad scope. Code Quality: The package ships 232 .spec.ts test files run through Vitest (yarn g:vitest), colocated with source files (e.g. setFeature.spec.ts, TypeRegistry.spec.ts, NormalizedSchema.spec.ts, cbor.spec.ts), with dedicated integration tests (core.integ.spec.ts) and CBOR test-vector fixtures; nearly every exported symbol carries TSDoc @internal/@public annotations, and the custom submodule linter enforces structural consistency (correct package.json exports, tsconfig entries) across all eleven submodules automatically. API Design: As the README states plainly, @smithy/core is explicitly an internal package — “this is used as a dependency for other, public packages, but should not be taken directly as a dependency in your application’s package.json” — so its API surface is optimized for consumption by code-generated clients and other Smithy packages rather than hand-written application code; the tradeoff is a highly modular, exports-segmented surface (eleven distinct entry points) that keeps unused code out of any given client’s bundle, at the cost of being less approachable for a developer encountering it directly without the generator or AWS SDK docs as context.