Customize with enrichments

What you'll build

The petstore project from tutorial 02, now with a form generator added and customized through enrichments: operation-specific form titles, submit-button labels, and field labels.

Prerequisites

• The petstore project from tutorial 02.
• Familiarity with the enrichments concept (skim it; this tutorial gives concrete steps).

Step 1: Find the generator's enrichment shape

Install the form generator:

skmtc install @skmtc/gen-shadcn-form petstore

Each generator declares its enrichment shape in src/enrichments.ts. For gen-shadcn-form, the shape is roughly:

{
  "title": "string",
  "description": "string",
  "submitLabel": "string",
  "fields": [
    {
      "id": "string",         // matches a property name in the request body schema
      "label": "string",
      "placeholder": "string"
    }
  ]
}

The full schema is documented at gen-shadcn-form's reference.

Step 2: Add enrichments to client.json

gen-shadcn-form is an OAS operation generator, so its routing keys are the literal OpenAPI path and lowercase method — not operationId. For the petstore, addPet is POST /pet and updatePet is PUT /pet.

Edit .skmtc/petstore/.settings/client.json:

{
  "source": "https://petstore3.swagger.io/api/v3/openapi.json",
  "settings": {
    "basePath": "src/generated",
    "enrichments": {
      "@skmtc/gen-shadcn-form": {
        "/pet": {
          "post": {
            "main": {
              "title": "Add a new pet",
              "submitLabel": "Add to inventory",
              "fields": [
                { "moduleSelect": { "schemaPath": ["name"] }, "label": "Pet name", "placeholder": "Fluffy" },
                { "moduleSelect": { "schemaPath": ["category"] }, "label": "Category" }
              ]
            }
          },
          "put": {
            "main": {
              "title": "Edit pet details",
              "submitLabel": "Save changes"
            }
          }
        }
      }
    }
  }
}

The routing path is [generatorId][path][method][variant] for OAS operation generators — the override sits under the variant key (main by default). See enrichments shape reference for all three routing shapes.

Step 3: Regenerate

skmtc generate petstore

No need to rebundle — client.json is runtime config, not bundle code.

Step 4: Verify the customization landed

Look at the generated form:

cat src/generated/pet/addPet.generated.tsx

The form's <h2> text is now "Add a new pet", the submit button reads "Add to inventory", and the name field's label is "Pet name". Other operations use the form generator's defaults (derived from the OAS path and verb).

What just happened

client.json#settings.enrichments is read by the engine and routed to each generator instance. The toOasOperationProjectionBase factory looks up enrichments[generatorId][operation.path][operation.method][variant] for the current operation and validates the result against the generator's Valibot schema. The validated { subject, generator, stack } umbrella lands on the Projection as this.settings.enrichments — read your per-operation config off its subject scope:

const { title, submitLabel } = this.settings.enrichments.subject ?? {}
return `<Form><h2>${title ?? defaultTitle}</h2>...<Button>${submitLabel ?? 'Submit'}</Button></Form>`

When you provided a title for POST /pet, it landed there. When you didn't (for other operations), the ?? defaults kicked in.

Next steps

• How to configure enrichments — targeted reference for adding more enrichment entries
• Enrichments concept — the mental model
• Tutorial: Cloning a generator — when enrichments aren't enough and you need source-level customization