tour-10-minutes.md

title	10‑minute tour
sidebar_label	10‑minute tour
sidebar_position	3

10‑minute tour

End‑to‑end in one sitting: init → add → register → openapi → package → curl.

1) Initialize a new app

npx smoz init --yes

This scaffolds:

• app/config/app.config.ts — schemas/config (params, env, http tokens)
• app/functions/** — endpoints (rest/http and non‑HTTP)
• app/generated/** — registers + OpenAPI placeholder
• serverless.ts — builds functions from the app registry

2) Add your first endpoint

npx smoz add rest/foo/get

This creates:

• app/functions/rest/foo/get/lambda.ts — registration (schemas)
• app/functions/rest/foo/get/handler.ts — business handler
• app/functions/rest/foo/get/openapi.ts — OpenAPI operation

Open lambda.ts:

export const eventSchema = z.unknown();
export const responseSchema = z.unknown();

export const fn = app.defineFunction({
  eventSchema,
  responseSchema,
  callerModuleUrl: import.meta.url,
});

Everything else derives from the folder and the app's defaults: event type rest, method get, base path foo, the function name, the public context and application/json. Set a field explicitly only to override it; see "What defineFunction derives from the path" in the Overview.

3) Register endpoints (side‑effects)

npx smoz register

This writes side‑effect files under app/generated/:

• register.functions.ts — imports all lambda.ts
• register.openapi.ts — imports all openapi.ts
• register.serverless.ts — imports any per‑function serverless.ts

Tip: Commit the generated register.*.ts so typecheck is stable.

4) Build OpenAPI

npm run openapi

This imports register.openapi.ts, collects paths via app.buildAllOpenApiPaths(), and writes app/generated/openapi.json.

Alternative: run a live loop that keeps registers/OpenAPI fresh and serves HTTP:

npx smoz dev --local inline

Use --local offline to drive serverless-offline instead.

5) Package with Serverless

npm run package

Serverless picks up:

• functions from app.buildAllServerlessFunctions()
• provider env from app.environment
• stages/params from app.stages

6) Curl it (locally or after deploy)

After you wire a dev endpoint or deploy, curl the route:

curl https://your-api/hello

Expected:

{ "ok": true }

Path parameters (bonus)

SMOZ supports native {id} path segments while keeping Windows‑safe folders:

• Spec input you can use: rest/users/:id/get, rest/users/{id}/get, or rest/users/[id]/get
• On disk: app/functions/rest/users/[id]/get/*
• In code: basePath: 'users/{id}'
• OpenAPI: includes a path parameter entry for id

Non‑HTTP flows (bonus)

For SQS/Step/etc., author the same way but skip HTTP options:

// lambda.ts (non‑HTTP)
export const fn = app.defineFunction({
  eventType: 'sqs',
  eventSchema: z.any(),
  responseSchema: z.any().optional(),
  callerModuleUrl: import.meta.url,
});

Attach platform events in a sibling serverless.ts:

// serverless.ts (non‑HTTP extras)
import { fn } from './lambda';
fn.serverless([
  { sqs: { arn: 'arn:aws:sqs:us-east-1:123456789012:my-queue' } },
]);

Next

• Read the Middleware page to customize the HTTP stack.
• Explore the Recipes for SQS, Cognito auth contexts, custom middleware, per‑function env, and observability helpers.