https://github.com/karmaniverous/smoz
SMOZ: a TypeScript toolkit for AWS Lambda combining Serverless, Middy, OpenAPI 3.1 and Zod for schema‑first apps with robust HTTP middleware and typed validation.
https://github.com/karmaniverous/smoz
api-docs api-gateway aws-lambda content-negotiation cors error-handling http-middleware lambda-handlers middy openapi openapi-3-1 openapi-generator schema-first serverless serverless-framework smoz toolkit typescript validation zod
Last synced: about 1 month ago
JSON representation
SMOZ: a TypeScript toolkit for AWS Lambda combining Serverless, Middy, OpenAPI 3.1 and Zod for schema‑first apps with robust HTTP middleware and typed validation.
- Host: GitHub
- URL: https://github.com/karmaniverous/smoz
- Owner: karmaniverous
- License: bsd-3-clause
- Created: 2025-08-07T12:32:57.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-01-04T23:45:27.000Z (5 months ago)
- Last Synced: 2026-04-06T14:50:34.496Z (2 months ago)
- Topics: api-docs, api-gateway, aws-lambda, content-negotiation, cors, error-handling, http-middleware, lambda-handlers, middy, openapi, openapi-3-1, openapi-generator, schema-first, serverless, serverless-framework, smoz, toolkit, typescript, validation, zod
- Language: TypeScript
- Homepage: https://docs.karmanivero.us/smoz/
- Size: 7.56 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# SMOZ
[Serverless](https://www.serverless.com/) · [Middy](https://middy.js.org/) · [OpenAPI 3.1](https://spec.openapis.org/oas/latest.html) · [Zod](https://zod.dev/)
[](https://www.npmjs.com/package/@karmaniverous/smoz)
[](https://docs.karmanivero.us/smoz)
[](https://github.com/karmaniverous/smoz/tree/main/CHANGELOG.md)
[](https://github.com/karmaniverous/smoz/tree/main/LICENSE.md)
SMOZ is a small, pragmatic toolkit for authoring AWS Lambda handlers with [Middy] and [Zod], then aggregating Serverless functions and hand‑crafted OpenAPI 3.1 paths from a single, schema‑first application definition.
- Keep prod code testable and framework‑agnostic
- HTTP middleware with validation, shaping, errors, CORS, negotiation, and HEAD
- Non‑HTTP flows stay lean (no middleware overhead)
## Quick start (from zero)
From an empty directory:
```bash
npx @karmaniverous/smoz init -i
npx smoz dev -p 3000
```
- The first command scaffolds a new app and installs dependencies (including a local `smoz` bin).
- The second command starts the inline local backend and keeps registers + OpenAPI fresh.
- Open http://localhost:3000/openapi in your browser.
Prefer `serverless‑offline`?
```bash
npx smoz dev -l offline -p 3000
```
Add your first endpoint (avoid clashing with the template’s hello):
```bash
npx smoz add rest/foo/get
```
## Quick links
- [Overview](./docs-src/overview.md)
- [Why smoz?](./docs-src/why-smoz.md)
- [Getting started](./docs-src/getting-started.md)
- [10-minute tour](./docs-src/tour-10-minutes.md)
- [HTTP Middleware](https://docs.karmanivero.us/smoz/documents/HTTP_middleware.html)
- [Recipes](./docs-src/recipes/index.md)
- [SQS function](./docs-src/recipes/sqs.md)
- [Step Functions function](./docs-src/recipes/step.md)
- [Contexts + Cognito authorizer](./docs-src/recipes/contexts-auth.md) - [Custom middleware insertion](./docs-src/recipes/custom-middleware.md)
- [Per‑function env](./docs-src/recipes/per-function-env.md)
- [Observability](./docs-src/recipes/observability.md)
- [Troubleshooting](./docs-src/recipes/troubleshooting.md)
- [Templates](./docs-src/templates.md)
- [CLI](./docs-src/cli.md)
- [Contributing](./CONTRIBUTING.md)
## Install
```bash
npm i @karmaniverous/smoz zod zod-openapi
```
## Dev tooling (recommended):
```bash
npm i -D typescript typescript-eslint eslint prettier typedoc
```
## Docs and reference
- [Docs site](https://docs.karmanivero.us/smoz)
- [Changelog](./CHANGELOG.md)
- [License](LICENSE)
- [Middy](https://middy.js.org/)
- [Zod](https://zod.dev/)