Typeweaver

Custom Generators

Custom generators are the advanced path for teams that need local or internal generated output Typeweaver does not ship out of the box.

In practice, a custom generator is usually still implemented as a plugin. The difference is scope: a custom generator is often local to one codebase, while a reusable plugin is something you expect other projects to install.

When a custom generator is the right tool

Reach for a custom generator when you need to generate:

  • framework-specific glue for an internal platform
  • SDK wrappers around the generated clients
  • deployment metadata or internal registries
  • opinionated code that should always stay in sync with the spec

Do not start here if handwritten code is simpler to maintain than generated code.

Start with the smallest possible extension

Before building your own generator, ask:

  1. can a built-in plugin already produce most of the output?
  2. can a thin handwritten wrapper around generated files solve the problem?
  3. do we really need regeneration every time the spec changes?

If the answer to those questions is still "yes, we need generation," a custom plugin is a good fit.

How custom generators plug into the CLI

The normal flow is still the same:

npx typeweaver generate --input ./api/spec/index.ts --output ./api/generated --plugins clients,my-plugin

The CLI always includes the core types generation internally, then loads any extra plugins you ask for and runs them in dependency order.

Configuration basics

Use a JavaScript config file when the command line gets noisy:

// typeweaver.config.mjs
export default {
  input: "./api/spec/index.ts",
  output: "./api/generated",
  plugins: ["clients", "my-plugin"],
  format: true,
  clean: true,
};

Run it with:

npx typeweaver generate --config ./typeweaver.config.mjs

Important config guardrail

Use JavaScript config files only:

  • .js
  • .mjs
  • .cjs

TypeScript config files are not supported by the published CLI.

How plugin loading works

For most users, plugin loading is simple:

  • built-in plugin names such as clients, server, hono, and aws-cdk resolve to the matching Typeweaver packages
  • the CLI can also import compatible module specifiers in advanced setups
  • plugin order in the final run is controlled by declared dependencies, not just by the order you typed them

That means your custom generator should declare dependencies explicitly when it needs another plugin's output shape or runtime helpers.

What to build against

Custom generators should work from the same stable concepts the built-in plugins use:

  • defineSpec(...) as the authoring entrypoint
  • the normalized resource/operation/response model
  • stable names such as resource names, operationId, and response names

If your generator depends on ad-hoc folder names or contributor-only file structure, it will be fragile.

A good mental model

Treat your generator like a compiler step:

  • input: a Typeweaver spec
  • output: deterministic generated files
  • contract: names and schemas from the spec

If a schema or response changes, regeneration should update your custom output automatically.

Keep the first version narrow

Good custom generators usually start with one concrete job, such as:

  • one file per resource
  • one manifest per operation
  • one adapter layer for a specific runtime

Avoid building a giant "project scaffolder" plugin on the first pass.

Was this page helpful?