NSmithy

July 1, 2026 · View on GitHub

CI Docs NuGet .NET 10 License Smithy CLI

Preview: NSmithy is in preview — expect some API changes before 1.0. Protocol implementations are not yet on par with the Smithy reference implementations.

NSmithy

Docs · Design Docs · smithy.io

NSmithy is a .NET toolkit that turns a Smithy model into idiomatic C# at build time. From a single contract you get typed clients, server scaffolding, and shared model types — fully integrated into your MSBuild workflow.

Features

  • Contract-first: The Smithy model is the source of truth: operations, shapes, errors, traits, and documentation live in one distributable contract. NSmithy generates C# model types, typed clients, and ASP.NET Core server handlers from it.
  • Protocol-agnostic: The same model can target multiple protocols, serialization formats, and wire shapes without rewriting the service contract.
  • Language-agnostic interop: Smithy has generators across many ecosystems. A service generated with NSmithy can share a contract with clients or servers generated for Java, TypeScript, Python, Go, Rust, Swift, and more.
  • Smithy-native architecture: NSmithy follows Smithy's official code generator guidance: reusable shape generation, protocol-specific runtime packages, and a clear boundary between generated code and runtime libraries.
  • Protocol support: Supports REST JSON, REST XML, AWS JSON, RPC v2 CBOR, and native gRPC.
  • Streaming support: Supports unary operations, event streaming, bidirectional streaming, and streaming blob payloads across protocols.
  • Conformance-tested: Protocol implementations are tested against official Smithy, AWS, and alloy conformance suites.

Development

The recommended way to work on this repo is with Nix and devenv.

  1. Install Nix (recommended: Determinate Nix) and devenv.

  2. Optionally install direnv to activate the dev environment automatically when entering the directory (direnv allow). Without it, run devenv shell manually.

  3. Use the just recipes to build, test, and package:

    just          # list all available recipes
just build    # build the codegen JAR and .NET solution
just test     # run the test suite
just fmt      # format all code
just docs     # start the documentation dev server
just ci       # run the full CI pipeline locally
  • Smithy — the IDL and protocol framework NSmithy is built on.
  • smithy4s — the main inspiration for NSmithy; generates Scala code from Smithy models with similar goals, though with a more sophisticated typeclass-based codec architecture that cleanly separates schema interpretation from serialization.
  • alloy — Smithy extensions used by NSmithy for simpleRestJson and gRPC protocols.
  • smithy-go / smithy-typescript — official Smithy codegen plugins for Go and TypeScript, which NSmithy draws inspiration from.
  • TypeSpec — Microsoft's alternative API description language with similar goals. Compiles to OpenAPI, JSON Schema, Protobuf, and more; has first-party .NET emitters.