Skip to main content

Quickstart

A fast path from zero to a generated, running smithy-hono service. For the full detail behind each step, follow the links into the Consuming & building section.

1. Get a registry token​

The @smithy-hono/* npm packages and the com.smithyhono:smithy-hono codegen jar live in a private GitLab registry, so every consumer authenticates. A Personal Access Token (read_api) is easiest for local dev; a Deploy Token is best for CI. Full details: Consuming → Get an access token.

export GITLAB_TOKEN=<your token>

2. Install the runtime packages​

Add the registry to your project's .npmrc, then install the core(s) plus the adapter for your platform:

@smithy-hono:registry=https://gitlab.example.com/api/v4/packages/npm/
//gitlab.example.com/api/v4/packages/npm/:_authToken=${GITLAB_TOKEN}
npm install @smithy-hono/security-core @smithy-hono/data-core @smithy-hono/adapter-node

See Consuming → npm packages for the per-platform install matrix and the project-level fallback URL.

3. Wire the codegen plugin​

Put the Maven jar on the Smithy build classpath and name the hono-codegen plugin in smithy-build.json. Copy model/traits.smithy into your model sources — the jar does not bundle loadable trait definitions. Full setup (Gradle / Smithy CLI / Maven), including the output-sync caveat: Consuming → The Hono codegen plugin.

4. Author your model, generate, and implement​

Annotate your model with @http traits, run codegen, then satisfy the generated operation interfaces in src/routes/*.ts. The end-to-end walkthrough — emitted output, @persisted zero-handler CRUD vs hand-written handlers, DataStore selection, errors, pagination, SSE, and MCP — is in Building a server.

5. Secure and deploy​

  • Secure it: Securing the server — the createSecurityPipeline assembly, OIDC sessions, S2S HMAC, and the production checklist.
  • Deploy it: Deploying — the platform matrix for Node/k8s, Cloudflare Workers, and AWS Lambda.

Learn from the reference apps​

The gold implementations live in the repo's examples/ directory — see the examples reference for what each one demonstrates.