Your first generation

What you'll build

A SKMTC project with @skmtc/gen-zod installed and a few .ts files generated from an OpenAPI spec — runtime validation schemas matching every component schema in the input.

Prerequisites

• Deno installed (deno --version)
• A sample OpenAPI v3 spec (URL or local .json / .yaml file)

If you don't have one handy, use the canonical Petstore spec: https://petstore3.swagger.io/api/v3/openapi.json.

Step 1: Install the CLI

curl -fsSL https://skm.tc/install | sh

The installer bootstraps Deno if it isn't already on your machine and bakes in the required --unstable-worker-options flag.

Confirm it's ready:

skmtc --help

You should see the list of skmtc commands.

Step 2: Create a project

In an empty directory, pass a project name and a basePath — the directory generated files are written to, relative to here:

skmtc init petstore src/generated

This scaffolds .skmtc/petstore/: a deno.json for generator imports and a .settings/client.json pre-filled with your basePath.

Step 3: Install a generator

skmtc install @skmtc/gen-zod petstore

The generator is added to .skmtc/petstore/deno.json#imports. See install reference for what the command does in detail.

Step 4: Configure the schema source

init already wrote basePath into .skmtc/petstore/.settings/client.json. Add a top-level source so the file reads:

{
  "source": "https://petstore3.swagger.io/api/v3/openapi.json",
  "settings": {
    "basePath": "src/generated"
  }
}

For a local file, use a relative path: "source": "./openapi.json" (resolved against the workspace root).

Step 5: Run generate

skmtc generate petstore

The engine fetches the spec, runs gen-zod against each schema component, and writes the artifacts to src/generated/.

Step 6: Read the output

ls src/generated/types/
cat src/generated/types/pet.generated.ts

Each schema component (Pet, Order, User, etc.) is now a zod schema under types/ (gen-zod's export path), one file per schema, named after the decapitalized schema name. Import it:

import { pet } from './src/generated/types/pet.generated.ts'

const validated = pet.parse(someApiResponse)

What just happened

The CLI ran the engine, which executed the three phases:

1. Parse: the OpenAPI document was normalized to OAS 3.0 and converted to typed OasDocument/OasSchema instances.
2. Generate: gen-zod's entry function iterated every schema component and called insertModel(ZodProjection, refName) for each, populating the file map.
3. Render: the file map was serialized to { path: content } artifacts and written to disk.

No Prettier ran — consumers format their own output. See design-philosophy for why.

Next steps

• Tutorial 02: Multiple generators — add types and hooks alongside the validators
• Tutorial 03: Customize with enrichments — add per-operation overrides via client.json
• How to debug a failing generation — if anything went wrong above
• Stock generators reference — the catalog of other generators you could add