# How to add a custom target to a generation run in your own repo

> Add an output the generator does not ship as a target kept in your project, compared with a meta-scaffolded generator and a templating step after generation.

Source: https://voxgig.com/howto/add-a-custom-target-without-contributing-upstream

- Audience: library-maintainer
- Level: advanced
- Languages: typescript
- Verified: 2026-11-20
- Published: 2026-11-20

## Short answer

In an sdkgen project, add `.sdk/model/target/<name>.aontu` and a `Main_<name>` component under `.sdk/src/cmp/<name>/`, run `voxgig-sdkgen target add <name>`, and generate. The target reads the same model as every other target, writes into its own folder, and generate fails on a file name that climbs out of it. With Swagger Codegen or OpenAPI Generator, scaffold a generator class with `meta`, build it, and put it on the class path.

---
## You will need

Node 22 or later, an sdkgen project you can regenerate, and Java with Maven for the two Java
generators. Read the prerequisite on components first: a target's code is a component. The
sample in `code/` commits every generator's output, so its checks run offline on Node alone.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [OpenAPI Generator meta command custom generator](https://openapi-generator.tech/docs/customization/) | You already run OpenAPI Generator and can build a Java jar | A Java class and Mustache templates to maintain, plus a class path on every run | The output needs entity names rather than operationIds |
| [sdkgen custom targets](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/author-a-new-language.md) | An sdkgen project, and the output should follow its model | Yours to maintain, and doctor reports your own target file as forked | You do not generate with sdkgen |
| [Separate templating step](https://nodejs.org/api/fs.html) | Any generator, or none, and a small output | Rebuilds from the document whatever it needs, and nothing stops it writing anywhere | The output needs the generator's classification |
| [Swagger Codegen meta command custom generator](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generators/) | You run Swagger Codegen 3 and its OpenAPI 3.0 reading suits you | The same Java class and template work as OpenAPI Generator, on a smaller generator list | You want the wider generator list of OpenAPI Generator |

Voxgig maintains sdkgen. It is one of four options in the table, not the recommendation.

The in-repo sdkgen target reuses the model and the pipeline it already runs, and is yours to maintain. A
separate step owes nothing to any generator and must rebuild what it needs from the document.
The two `meta` generators sit between: a Java project that reuses the generator's parser and
names operations by operationId.

## Declare the target and write its component

A target is a model file and a component directory under `.sdk`. This one, `http`, is a tool
rather than an SDK, so it switches off every standard phase and emits its whole output from
`Main`, as the [model reference](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md)
describes for consumer targets.

```aontu title=".sdk/model/target/http.aontu"
main: kit: target: http: {
  title: 'HTTP request file'
  ext: http
  comment: line: "#"
  module: name: '$$name$$'

  phase: {
    entity:     { active: false }
    feature:    { active: false }
    readme:     { active: false }
    agentguide: { active: false }
    test:       { active: false }
  }

  deps: {}
}
```

`Main_http` walks the entities in the model and writes one request block per operation point,
using the HTTP client format JetBrains documents, with in-place variables written
[`@base` and `{{bookId}}`](https://www.jetbrains.com/help/idea/http-client-variables.html).

```ts title=".sdk/src/cmp/http/Main_http.ts"
  File({ name: model.name + '.' + target.ext }, () => {
    Content(`# ${model.Name} API requests. Generated by the http target, do not edit.\n`)
    Content(`@base = ${base}\n`)
    each(entities, (entity: any) => {
      if (false === entity.active) return
      each(entity.op || {}, (op: any) => {
        each(op.points || [], (point: any) => {
          const path = String(point.o).replace(/\{(\w+)\}/g, '{{$1}}')
          Content(`\n### ${entity.name}.${op.name}\n${point.m} {{base}}${path}\n`)
          if (point.bf && point.bf.length) {
            const body: any = {}
            for (const field of point.bf) body[field] = ''
            Content(`content-type: application/json\n\n${JSON.stringify(body, null, 2)}\n`)
          }
        })
      })
    })
  })
```

`point.m`, `point.o` and `point.bf` are the method, path and body fields the model step already
extracted, so the component parses nothing.

## Add it to the run

From `.sdk/`, register the target and generate:

```bash
npx voxgig-sdkgen target add http
npm run generate
```

`target add` logs `http: defined in this project, so its files stay as they are`, then a warning
that no `test` source exists for the target. Every generate warns that one file in `.sdk` differs
from what its source installs, and `npx voxgig-sdkgen doctor` names it: the target's own model
file, reported `FORKED` because no copy record exists for it. Generate still exits 0; doctor
exits 1, as the last section shows.

The elementdemo SDK is the worked reference at full size. Its
[`.sdk`](https://github.com/voxgig-sdk/voxgig-elementdemo-sdk) holds a `bash` target with
`Main`, `Entity` and `Test` components, and its generated test runner seeds from the fixtures
in `.sdk/test/entity/` that the other targets' basic tests use.

## Scaffold the same output with meta

Swagger Codegen and OpenAPI Generator both scaffold a generator project with
`meta -o <dir> -n http-requests -p com.example.codegen`. The scaffold is a Maven project with a
class, a test, three Mustache templates, and a service registration. Writing `.http` files took three
edits to the class, shown in `class.diff`, and one `api.mustache`:

```text title="api.mustache"
# {{appName}} API requests. Generated by the http-requests generator, do not edit.
@base = {{{basePath}}}
{{#operations}}
{{#operation}}

### {{operationId}}
{{httpMethod}} {{=<% %>=}}{{base}}<%={{ }}=%>{{{path}}}
{{#hasBodyParam}}
content-type: application/json

{}
{{/hasBodyParam}}
{{/operation}}
{{/operations}}
```

Build with `mvn package`, then run the CLI with the jar on its class path:
`org.openapitools.codegen.OpenAPIGenerator generate -g http-requests` for OpenAPI Generator,
and `io.swagger.codegen.v3.cli.SwaggerCodegen generate -l http-requests` for Swagger Codegen.
Both wrote `DefaultApi.http` under a Java-package path, `src/org/openapitools/api/` and
`src/io/swagger/client/api/`.[^1]

For this particular file, OpenAPI Generator needs no class at all. It bundles a
[`jetbrains-http-client` generator](https://openapi-generator.tech/docs/generators/jetbrains-http-client/),
marked experimental, and `generate -g jetbrains-http-client` wrote `Apis/DefaultApi.http` with
every path variable already written `{{bookId}}`. It names each request from the operation's
`summary`, which the Bookshelf document leaves out, so all five headings came out blank. Swagger
Codegen 3.0.85 lists no such generator, so its route is `meta`.

`bolt-on.mjs` is the separate step: it reads `api.json`, walks `paths`, and prints the same
blocks. `compare.mjs` reads all four outputs.

```bash
node compare.mjs
```

```text output
operation               sdkgen            openapi-generator swagger-codegen   bolt-on
GET /books              book.list         listBooks         listBooks         listBooks
POST /books             book.create       createBook        createBook        createBook
GET /books/{bookId}     book.load         getBook           getBook           getBook
PATCH /books/{bookId}   book.update       updateBook        updateBook        updateBook
DELETE /books/{bookId}  book.remove       deleteBook        deleteBook        deleteBook
sdkgen             writes the path as /books/{{bookId}}
openapi-generator  writes the path as /books/{bookId}
swagger-codegen    writes the path as /books/{bookId}
bolt-on            writes the path as /books/{{bookId}}
```

The two `meta` generators name requests by operationId, and the template prints the path as the
document writes it. A REST client reads only `{{bookId}}` as a variable, so the fix is Java in
the generator class. OpenAPI Generator's scaffold already overrides
`postProcessOperationsWithModels` for such changes; Swagger Codegen's leaves the method to add.

## Check it worked

`generate.sh` ran `npm run generate` twice and fingerprinted every output file each time. The
tests compare the fingerprints and check that each output carries all five operations.

```bash
node --test target.test.mjs
```

```text output
# tests 9
# suites 0
# pass 9
# fail 0
```

The fourth test asserts the only `.http` file in the tree is `./http/bookshelf.http`, so a
target that strays into another folder fails it.

## When it goes wrong

A target that writes into another target's folder is the failure to guard against. Generate
failed on both ways of aiming `http` at `ts/` that the sample tried. The file writer refuses any
name with a `..` segment. `output.path`, which exists to send a target to another repository,
refuses any path inside the SDK project, the target's own folder included. A separate step has
no such check.

```bash
node pitfall.mjs
```

```text output
Main_http writes File({ name: '../ts/bookshelf.http' })
  generate exit 1: File name must not contain a ".." path segment, name=../ts/bookshelf.http
project.aontu sets main: kit: target: http: output: path: 'ts'
  generate exit 1: External output path is inside the SDK project.
a separate step writes ts/src/bookshelf.http, then generate runs
  ts/src/bookshelf.http after generate: present
  in the npm pack file list: true
npx voxgig-sdkgen doctor, with the http target added
  FORKED (no copy record, so an add stops on it; --force takes the source copy): model/target/http.aontu
  .sdk has drifted: 1 forked, 0 edited, 0 stale, 0 missing, 0 outdated, 0 unresolved
  doctor exit 1
```

The stray file survives regeneration, and the `files` list in the TypeScript `package.json`
includes `src`, so `npm pack` ships it. Give the separate step a folder no generator owns.

The second failure is a CI job that runs doctor as a gate. It goes red as soon as the project
has a target of its own, because doctor counts the target's model file as forked and exits 1.
Allow that one finding by path rather than dropping the gate.

## When not to do this

Do not build an sdkgen target for an output that reads the document alone. `bolt-on.mjs`
writes the requests by operationId in under thirty lines and owes nothing to any generator.

Skip sdkgen when your SDKs come from Swagger Codegen or OpenAPI Generator. For this
request file, OpenAPI Generator's bundled `jetbrains-http-client` generator is the better choice,
because it needs no code of yours. A `meta` generator reuses the parser you already trust, and
Swagger Codegen is the better choice when you already run it on OpenAPI 3.0 documents. OpenAPI Generator suits a team that wants its
wider generator list, or 3.1 documents, which its README marks as beta support.

Do not expect the in-repo target to be free: sdkgen upgrades can change the model shape your
component reads.

## Related how-tos

- [Generate a code section with code instead of a template](/howto/generate-a-code-section-with-a-component)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Package a customization several SDK projects can install](/howto/package-a-shared-generator-customisation)

- [Evaluate a third-tier SDK target before you ship it](/howto/evaluate-a-third-tier-sdk-target)

- [Fail a build when a generator customization becomes a fork](/howto/audit-generator-customisations-for-drift)

## Last verified

Verified 2026-11-20 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, `@voxgig/sdkgen`
4.44.3, OpenAPI Generator 7.27.0, and Swagger Codegen 3.0.85 on OpenJDK 21.0.13 and Maven
3.9.11. Every output block is what the command preceding it printed. The generators ran once,
recorded in `generate.sh`, OpenAPI Generator's bundled `jetbrains-http-client` included; the
lines `pitfall.mjs` prints are what that run logged.

[^1]: OpenAPI Generator's [README](https://github.com/OpenAPITools/openapi-generator) says it is
a fork of Swagger Codegen. More than 40 top contributors and template creators made it, citing
the issues with the Swagger Codegen 3.0.0 beta release and a disagreement over the project's
direction. The two `meta` scaffolds took
the same three edits to their classes, and the one `api.mustache` on this page rendered
byte-identical files in both.