Skip to content

Node.js / TypeScript quickstart

mic-node applies the same MIC boundaries to Node.js: executable contracts, framework-neutral routes, canonical domain errors, explicit injection, and tests of public behavior.

Requirements

  • Node.js 24 or later
  • pnpm

All fifteen @mic-struct packages are published on the public npm registry. Installing them requires no token or MIC-specific registry configuration.

Generate and verify a service

pnpm dlx @mic-struct/create-mic-service ./my-service
cd my-service
pnpm install
pnpm verify
pnpm start

The generated project immediately provides:

  • GET /health and GET /ready;
  • its OpenAPI 3.1 contract at GET /openapi.json;
  • POST /api/v1/widgets and GET /api/v1/widgets;
  • an operator CLI for readiness, OpenAPI export, event catalog validation, and replay;
  • 12 service tests, including a real HTTP smoke test;
  • a non-retryable widgets.already_exists error shared by runtime behavior and the OpenAPI contract.

The server listens on port 3000 by default. Export the contract without starting an HTTP listener:

pnpm run cli openapi --pretty > openapi.json

Declare a route

import { created, route, schema, wrapHttpSuccess } from "@mic-struct/mic-core"

const CreateWidget = schema.object({
  name: schema.string({ minLength: 1 }),
})

export const createWidget = route({
  method: "POST",
  path: "/api/v1/widgets",
  name: "widgets.create",
  category: "widgets",
  body: CreateWidget,
  successStatusCode: 201,
  handler: async ({ body }) => created(
    wrapHttpSuccess({ id: "widget-1", name: body.name }),
  ),
})

Node HTTP, Express, Fastify, Hono, and NestJS serve the same route without changing the handler.

Packages

Need Packages
Contracts, errors, HTTP, authentication, CLI @mic-struct/mic-core
Signed service-to-service client @mic-struct/mic-client
Persistence, cache, outbox, queues, realtime, scheduling @mic-struct/mic-datastore
HTTP adapters @mic-struct/mic-node-http, @mic-struct/mic-express, @mic-struct/mic-fastify, @mic-struct/mic-hono, @mic-struct/mic-nest
Kafka, NATS, and Redis @mic-struct/mic-kafka, @mic-struct/mic-nats, @mic-struct/mic-redis
Observability and resilience @mic-struct/mic-observability, @mic-struct/mic-resilience
Authorization, rate limiting, OIDC @mic-struct/mic-platform
Generator @mic-struct/create-mic-service

All 15 packages declare engines.node >=24.0.0. Every official release starts from a protected tag, verifies the npm archives, then installs the published packages in an empty project and runs the generated service.

See the mic-node repository for the complete API and architecture decisions.