feat: experimental typescript-nextjs template

[mnahkies]

Creates a new typescript-nextjs template

• Server only so far, plan to add client
• Generates routes following the app router "Route handlers", with a mirrored directory structure of companion files under ./src/generated containing the types and validation boilerplate

Approach

Due to the NextJS file based routing paradigm I couldn't see anyway to avoid manipulating files that will contain manually written code.

• This is a major shift compared to the other templates which treat all emitted files as disposable.
• To achieve this we employ ts-morph to (hopefully) safely modify the app router files without destroying the manually written implementations.
• Plan to implement require clean git working directory by default #52 before releasing this, I remember early linting tools mangling/damaging my code, and there's a pretty high chance the morphing will have edge cases I've missed

Pending Refactoring

Currently there is a lot of duplicated code between this and the typescript-koa template which needs rationalizing, as well as it depending on the typescript-koa-runtime package. Part of the motivation behind this is to have more than one server template to allow it to become more generic like the client templates.

Because of the typescript-koa-runtime hack, to actually use this in a NextJS application you need to add the following to your next.config.mjs:

webpack: (
    config,
    {buildId, dev, isServer, defaultLoaders, nextRuntime, webpack}
  ) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      koa: false,
      '@koa/cors': false,
      'koa-body': false,
    }
    // Important: return the modified config
    return config
  },

I also don't love the explosion of files this creates when running the standard set of integration suites, and might limit the scope down to one spec to reduce the noise. Ideally I'd like to separate the integration tests to their own repo and also start testing more permutations of options (eg: joi, extract-inline-schemas).

Additionally to make multiple suites play nicely I've had to fudge the output paths in the tests, technically producing incorrect routes.

Performance

I've been told that ts-morph can be relatively slow, so it's probably useful to check the performance between this and typescript-koa

Overall it looks similar, aside from calculation of the dependency graph. I'm not sure if this is the bug in the timing code, or if the larger number of compilation units is somehow causing this. Warrants some investigation in case we're calculating it repeatedly or something.

typescript-nextjs - api.github.com.yaml

[info] elapsed {
  total: '3735 ms',
  '0 - program starting': '0 ms, 0%',
  '1 - load files': '292 ms, 8%',
  '2 - calculate schema dependency graph': '1528 ms, 41%',
  '3 - generate ./generated/api.github.com.yaml/models.ts': '268 ms, 7%',
  '4 - generate ./generated/api.github.com.yaml/schemas.ts': '314 ms, 8%',
  '5 - format output': '1128 ms, 30%',
  '6 - write output': '49 ms, 1%'
}

typescript-koa - api.github.com.yaml

[info] elapsed {
  total: '2398 ms',
  '0 - program starting': '0 ms, 0%',
  '1 - load files': '293 ms, 12%',
  '2 - calculate schema dependency graph': '506 ms, 21%',
  '3 - generate ./models.ts': '267 ms, 11%',
  '4 - generate ./schemas.ts': '322 ms, 13%',
  '5 - format output': '851 ms, 35%',
  '6 - write output': '4 ms, 0%'
}

The correct fix is to replace all occurrences of *, not just the first one.
Best minimal change: update line 22 in packages/openapi-code-generator/src/typescript/server/typescript-nextjs/typescript-nextjs.generator.ts to use replaceAll("*", "") (or regex /\*/g). Since this codebase already uses replaceAll (line 191), replaceAll is consistent and keeps behavior clear.

No additional imports, helper methods, or dependency changes are needed.

General fix: sanitize JSON-stringified values before inserting them into generated code strings, using a dedicated escaping routine that replaces JavaScript/HTML-dangerous characters with safe Unicode escape sequences.

Best single fix without changing functionality: in each affected schema builder default-method (joi-schema-builder.ts, zod-v3-schema-builder.ts, zod-v4-schema-builder.ts), add a local helper that post-processes the output of JSON.stringify and use it for defaultValue. Keep existing needsWrapping behavior unchanged so semantics remain identical except safer escaping.

Concretely:

• In each file, define:
  • unsafeCharacterMap mapping <, >, /, \b, \f, \n, \r, \t, \0, \u2028, \u2029.
  • escapeUnsafeJsonForCode(value: string): string using .replace(...).
• Replace const defaultValue = JSON.stringify(model.default) with:
  • const defaultValue = escapeUnsafeJsonForCode(JSON.stringify(model.default)).

No new external dependency is required.