# How to choose a template engine for generating source code

> Render one TypeScript class from one JSON model in Mustache, Handlebars, EJS, Nunjucks, Go text/template, and jostraca, and see where each one puts the logic.

Source: https://voxgig.com/howto/choose-a-template-engine-for-generated-code

- Audience: platform-team
- Level: beginner
- Languages: typescript, go
- Verified: 2026-11-22
- Published: 2026-11-22

## Short answer

Choose a template engine by rendering one real file from one JSON model in Mustache, Handlebars, EJS, Nunjucks, and Go text/template, then diffing each result against a hand-written, Prettier-formatted reference. Mustache moves the logic into a precomputed view, EJS moves it into the template, and the other three split it with named helpers. Turn off HTML escaping in the four JavaScript engines, or List<T> comes out as List&lt;T&gt;.

---
## You will need

Node 22 or later, Go 1.22 or later for the `text/template` row, and a small JSON model of what you
generate. The sample's `model.json` describes a `Book` client with four operations, seven
parameters split across path, query, and body, and one paged result. That is enough for nested
loops, a conditional import, and two levels of indentation. Prettier formats the reference at a
print width of 100, and its [`--check` flag](https://prettier.io/docs/cli) holds the output to it.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [EJS](https://github.com/mde/ejs) | The team writes JavaScript and the template needs real expressions | Logic leaks into `<% %>` tags, where only a full render can test it | People who should not edit code edit the templates |
| [jostraca](https://jostraca.org/docs/explanation/) | Most of the file is computed, or the template must stay valid TypeScript | No template syntax at all, so the file's shape lives in code until you run it | The output is mostly literal text a reviewer wants to read |
| [Mustache](https://mustache.github.io/mustache.5.html) | The template should read as a picture of its output | Every derived value moves into a view, three fields for this one class | Names have to be computed, joined, or checked |
| [Nunjucks](https://mozilla.github.io/nunjucks/templating.html) | Jinja-style syntax, shared with a Python team | Escaping on by default, and a custom filter for anything the built-ins lack | The generator runs on Go or the JVM |
| [oapi-codegen, Go text/template](https://github.com/oapi-codegen/oapi-codegen#custom-code-generation) | A Go SDK whose templates you override by filename | Its README calls template overrides unstable, and says their input contexts keep drifting | The SDK is in any language but Go |
| [Swagger Codegen, Handlebars templates](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generators/#modifying-the-client-library-format) | Stock client templates in many languages, with a few overrides | One of its own stock templates escapes a type, and an override replaces a whole file | You want one engine across generators you write yourself |

Voxgig maintains jostraca, one of the six rows here, and it is not the recommendation.

The engine decides where the logic goes, not whether it exists. Mustache keeps templates dumb and
testable by moving every derived value into a view, so even the comma between two parameters needs a
field. EJS keeps
the model raw and pays in templates that only a render can check. The two generators choose for
you. Swagger Codegen runs Handlebars and oapi-codegen runs Go `text/template`.

## Render one class from one model in every engine

`reference/BookClient.ts` was written by hand and formatted with Prettier. `render.mjs` sends
`model.json` through each engine's template, writes the results to `rendered/`, and compares bytes.

```bash
node render.mjs
```

```text output
engine               file                              same bytes as reference
Mustache             rendered/mustache.ts              yes
Handlebars           rendered/handlebars.ts            yes
EJS                  rendered/ejs.ts                   yes
Nunjucks             rendered/nunjucks.ts              yes
Go text/template     rendered/go-text-template.ts      yes
jostraca component   rendered/jostraca-component.ts    yes
jostraca fill-in     rendered/jostraca-fill-in.ts      yes
```

All seven reach the same bytes, so the choice rests on what each one asked for along the way. The
Mustache template is the output with holes in it:

```handlebars title="templates/book.mustache"
{{#ops}}

  /** {{method}} {{{path}}} */
  {{name}}({{#params}}{{name}}{{#optional}}?{{/optional}}: {{{type}}}{{^last}}, {{/last}}{{/params}}): Promise<{{{returns}}}> {
    return this.transport.call("{{method}}", "{{{path}}}", {
{{#groups}}
      {{key}}: { {{names}} },
{{/groups}}
    });
  }
{{/ops}}
```

It cannot join a list or compare two values, so `view.mjs` adds `last` to every parameter and
`groups` to every operation before the render. The EJS template reads the raw model instead:

```erb title="templates/book.ejs"
<% for (const op of ops) { -%>

  /** <%= op.method %> <%- op.path %> */
  <%= op.name %>(<%- op.params.map((p) => `${p.name}${p.optional ? '?' : ''}: ${p.type}`).join(', ') %>): Promise<<%- op.returns %>> {
    return this.transport.call("<%= op.method %>", "<%- op.path %>", {
<% for (const where of ['path', 'query', 'body']) { -%>
<%   const names = op.params.filter((p) => p.in === where).map((p) => p.name) -%>
<%   if (names.length > 0) { -%>
      <%= where %>: { <%= names.join(', ') %> },
<%   } -%>
<% } -%>
```

The signature is a `map` and a `join` inside an output tag. It needs no file beside the template,
which is the attraction, and it has no test of its own.

## Score where the logic ends up

`score.mjs` counts the control tags in each template, names the logic that lives outside it, and
asks Prettier whether the template itself parses as TypeScript.

```bash
node score.mjs
```

```text output
engine               template            lines  logic tags  parses as TS  logic outside the template
Mustache             book.mustache          22           6  no            view adds anyPaged, groups, last
Handlebars           book.hbs               22           6  no            helpers groups, some
EJS                  book.ejs               25           5  no            none
Nunjucks             book.njk               25           8  no            filter namesIn
Go text/template     book.tmpl              25           7  no            funcs anyPaged, list, namesIn
jostraca fill-in     BookClient.frag.ts     10           2  yes           the methods, written as code
jostraca component   (none)                  0           0  n/a           the whole file
```

Handlebars, Nunjucks, and Go land in the middle. Their helpers are ordinary functions you can unit
test, and the template calls them by name. Five of the six templates fail to parse, which means
the formatter, the type checker and the editor's outline cannot read them until they are rendered.

## Fill in a file that stays TypeScript

jostraca has no template language. It writes a file from component calls, or fills marked regions
of a file that is still valid source. The fill-in file here passes the Prettier check as it stands,
because `$$name$$Client` is a legal identifier and the markers sit in comments:

```ts title="templates/BookClient.frag.ts"
// Generated from model.json. Do not edit.
import type { $$name$$ } from "./types";
// <[SLOT:imports]>
import type { Transport } from "./transport";

/** $$title$$ */
export class $$name$$Client {
  constructor(private readonly transport: Transport) {}
  // <[SLOT]>
}
```

The code that fills it decides the conditional import and writes the methods:

```js title="engines.mjs"
      Fragment({ from }, () => {
        // A marker keeps its own newline, so the text put at it has none. The Slot is
        // passed even when it is empty: a named marker with no Slot stays in the file.
        Slot({ name: 'imports' }, () => {
          if (m.ops.some((op) => op.paged === true)) Content('import type { Page } from "./page";')
        })
        Content(m.ops.flatMap((op) => methodLines(op)).join('\n'))
      })
```

Both rules in that comment come from the [jostraca component reference](https://jostraca.org/docs/reference-components/#slot).
The second is the one that bites: leave out the `Slot` and `// <[SLOT:imports]>` reaches the
output as text, where it compiles as a comment, so no build step reports it.

## Check it worked

Run the formatter in check mode over the reference and every rendered file, then the tests.

```bash
npx prettier --check reference rendered
```

```text output
Checking formatting...
All matched files use Prettier code style!
```

```bash
node --test render.test.mjs
```

```text output
1..13
# tests 13
# suites 0
# pass 13
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 1113.47588
```

The first test renders all seven again and compares them with both the reference and the committed
`rendered/` files. Another feeds the comparison an empty file and a one-character change, and both
fail it. A third misspells `$$title$$` in the fill-in template, and the comparison refuses the
result at line 6.

## When it goes wrong

The generic type turns into entities. Mustache, Handlebars, and EJS escape for HTML on their
default output tag. Nunjucks escapes because its `autoescape` option is on unless you turn it off,
and `escape.mjs` leaves it at that default. Go's `html/template` escapes too. The script renders one
line each way:

```bash
node escape.mjs
```

```text output
default output tag
  Mustache          {{returns}}        Promise<Map&lt;string, Book[]&gt;>
  Handlebars        {{returns}}        Promise<Map&lt;string, Book[]&gt;>
  EJS               <%= returns %>     Promise<Map&lt;string, Book[]&gt;>
  Nunjucks          {{ returns }}      Promise<Map&lt;string, Book[]&gt;>
  Go html/template  {{.returns}}       Promise&lt;Map&lt;string, Book[]&gt;>
  Go text/template  {{.returns}}       Promise<Map<string, Book[]>>
  jostraca          $$returns$$        Promise<Map<string, Book[]>>

the fix
  Mustache          {{{returns}}}      Promise<Map<string, Book[]>>
  Handlebars        noEscape: true     Promise<Map<string, Book[]>>
  EJS               <%- returns %>     Promise<Map<string, Book[]>>
  Nunjucks          autoescape: false  Promise<Map<string, Book[]>>
  Go                text/template      Promise<Map<string, Book[]>>

book.mustache with double braces only:
  list(limit?: number, cursor?: string): Promise<Page&lt;Book&gt;> {
  prettier refused it: '>' expected. (11:57)
```

`html/template` also rewrote the `<` that the template text itself wrote. The
[`text/template` documentation](https://pkg.go.dev/text/template) sends HTML output to
`html/template`, so source code belongs in `text/template`. The options are
[`noEscape` for Handlebars](https://handlebarsjs.com/api-reference/compilation.html) and [`autoescape` for Nunjucks](https://mozilla.github.io/nunjucks/api.html), which defaults to
true.[^1] Keep the formatter in the pipeline, because it is the first thing to refuse the file.

A misspelled key renders as nothing. Mustache, Handlebars, and Nunjucks write an empty string,
Go writes `<no value>`, and jostraca leaves `$$retruns$$` in place, which its
[utilities reference](https://jostraca.org/docs/reference-utilities/#template) calls deliberate:

```bash
node missing.mjs
```

```text output
the template asks for retruns; the model holds returns
  Mustache          default           Promise<>
  Handlebars        default           Promise<>
  Handlebars        strict: true      throws: "retruns" not defined in [object Object] - 1:10
  EJS               default           throws: retruns is not defined
  EJS               locals.retruns    Promise<>
  Nunjucks          default           Promise<>
  Nunjucks          throwOnUndefined  throws: attempted to output null or undefined value
  Go text/template  default           Promise<<no value>>
  Go text/template  missingkey=error  throws: template: line:1:10: executing "line" at <.retruns>: map has no entry for key "retruns"
  jostraca          default           Promise<$$retruns$$>
```

Turn on the strict mode where the engine has one. The [Mustache manual](https://mustache.github.io/mustache.5.html)
says a missed variable returns an empty string, so only the comparison with the reference catches
it there.

## Fix the same escape in Swagger Codegen and oapi-codegen

A team that generates its SDK with either generator does not pick the engine. It overrides
templates written for the engine the generator runs. `generate.sh` ran both once on the page's
`openapi.json`, and `generators.mjs` reads what they wrote.

```bash
node generators.mjs
```

```text output
Swagger Codegen 3.0.85, typescript-fetch
  Template engine: io.swagger.codegen.v3.templates.HandlebarTemplateEngine
  stock templates, api.ts:166   const needsSerialization = (<any>"Array&lt;string&gt;" !== ...
  -t override,     api.ts:166   const needsSerialization = (<any>"Array<string>" !== ...
  stock run: 9 files, -t run with only api.mustache: 9 files
  --template-engine mustache: exit status: 0, files written: 0

oapi-codegen v2.9.0, Go text/template
  stock typedef.tmpl:  // Book A title in the "catalog", returned as Array<Book> by listBooks & tagBook.
  user typedef.tmpl:   // Book was written by a user template.
  user.gen.go and indented.gen.go: identical, after oapi-codegen formatted both
```

Swagger Codegen's stock `typescript-fetch` template writes `{{dataType}}` with two braces in one
place, and the generated client carries the escaped type.[^2] The comparison still evaluates to
true, so nothing breaks at run time. Fix it the documented way: copy the template into a folder,
change it to three braces, and pass the folder with `-t`. The run with only `api.mustache` in the
folder wrote the same nine files as the stock run, so the templates you do not copy fall back.
Swagger Codegen's `generate --help` also lists `--template-engine mustache`, which threw on this
target, wrote no files, and exited 0.

oapi-codegen runs Go `text/template`, so the description keeps its `<`, `&` and quotes as written.
Override a template by its exact filename under
[`output-options.user-templates`](https://github.com/oapi-codegen/oapi-codegen#custom-code-generation).
It formats every file it writes, so a user template indented by eight to twelve spaces gave the
same bytes as a tidy one.[^3]

## When not to do this

Do not run an engine bake-off when a generator already owns the templates. If Swagger Codegen or
oapi-codegen writes your SDK, the engine is chosen, and the work is keeping overrides small.
Swagger Codegen is the better fit when you need stock clients for many languages and can carry a
few overrides. oapi-codegen is the better fit for a Go-only SDK, because its output arrives
formatted without a separate step.

Do not use Go's `html/template` for source code, and do not leave any of the four JavaScript engines on
its default escaping.

Skip jostraca when the file is mostly literal text. A template is a picture a reviewer can read,
and the component version moves that picture into code. jostraca earns its place when most of the
file is computed, or when the template has to stay a file the formatter and the type checker can
read.

Do not choose EJS for templates that people outside the generator's code owners edit. The logic it
allows has no test except the rendered file.

## Related how-tos

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

- [Format generated code as the last step of generation](/howto/format-generated-code-as-the-last-step)

- [Make a Handlebars template produce byte-identical output](/howto/handlebars-byte-identical-output-every-run)

- [Find which template produced a generated file](/howto/find-which-template-produced-a-generated-file)

- [Compose one generated file from several components](/howto/compose-generated-files-with-slots-and-fragments)

## Last verified

Verified 2026-11-22 against Node 22.23.5, Go 1.24.7 and 1.25.0, mustache 4.2.0, handlebars 4.7.10, EJS 7.0.2,
Nunjucks 3.2.4, prettier 3.10.1, jostraca 0.42.0, and shape 12.2.5. Every output block is what the
command preceding it printed. Swagger Codegen 3.0.85 and oapi-codegen v2.9.0 each ran once, through
`generate.sh`, and the files they wrote are committed under `generated/`; the page's commands read
those files and run neither generator. oapi-codegen v2.9.0 declares `go 1.26.0`, so the go command
fetched a Go 1.26 toolchain to run it.

[^1]: The Nunjucks escape table in
[lib.js](https://github.com/mozilla/nunjucks/blob/v3.2.4/nunjucks/src/lib.js) has six entries:
the ampersand, both quotes, both angle brackets, and a backslash, which comes out as `&#92;`.
Mustache, Handlebars, and EJS leave the backslash alone, and a test in the sample holds all four to
that. Mustache and Handlebars escape the backtick, which closes a TypeScript template literal, and
EJS and Nunjucks leave it alone. A generated Windows path in a string literal is the case where the sixth entry shows.

[^2]: Swagger Codegen's documentation says it processes "handlebar templates with the
Handlebars.java engine" and that `-t` points it at your own. The template this page overrides
is [`api.mustache`](https://github.com/swagger-api/swagger-codegen-generators/blob/master/src/main/resources/handlebars/typescript-fetch/api.mustache),
which sits in a folder named `handlebars` in swagger-codegen-generators and is run by Handlebars
whatever its extension says. The double-brace `{{dataType}}` is on line 231 of the `master` copy
too.

[^3]: The formatting is `imports.Process`, called in
[codegen.go](https://github.com/oapi-codegen/oapi-codegen/blob/v2.9.0/pkg/codegen/codegen.go)
unless `output-options.skip-fmt` is set. The
[README](https://github.com/oapi-codegen/oapi-codegen#custom-code-generation) that documents user
templates also says template overrides are "always drifting and so are their input contexts" and
calls them unstable. The formatter sits in the Go code that runs the templates, outside any file a
user template replaces.