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%'
}

In general, to fix incomplete string escaping or encoding when using String.prototype.replace, you should either (a) use a regular expression with the g flag so that all occurrences of the pattern are replaced, or (b) use an API that is explicitly global (like replaceAll). For simple literal patterns such as "*", converting to a global regular expression is straightforward.

In this specific case, the best way to fix the problem without changing existing functionality is to update alias[0].replace("*", "") so that every * in the alias key is removed, not just the first. The simplest change is to use a global regular expression: alias[0].replace(/\*/g, ""). This continues to turn a typical alias like "@app/*" into "@app/", but also handles any aliases that might have more than one asterisk. No additional imports or helper methods are required; this is a built-in JavaScript feature. The change is localized to the findImportAlias function in packages/openapi-code-generator/src/typescript/server/typescript-nextjs/typescript-nextjs.generator.ts, line 22 in the snippet.

General fix: ensure that the string obtained from JSON.stringify(model.default) is further sanitized before being interpolated into generated code, so that characters like <, >, /, \u2028, \u2029, etc., cannot break out of their intended context if the generated code is ever embedded in HTML or similar sinks.

Best concrete fix for this codebase:

1. Introduce a small, shared escaping helper in AbstractSchemaBuilder that takes the JSON string and replaces potentially dangerous characters with safe escape sequences, following CodeQL’s recommended mapping (e.g. < → \u003C, > → \u003E, / → \u002F, \u2028/\u2029 → \u2028/\u2029 escape forms).
2. Use this helper in the default methods of JoiBuilder, ZodV3Builder, and ZodV4Builder instead of using JSON.stringify(model.default) raw.
3. Keep the logic that wraps defaultValue in extra quotes for string‑typed models unchanged, but apply it to the sanitized string. Since JSON.stringify already returns a valid JavaScript literal, and the additional escaping only introduces further backslash escapes, the semantics of the default values remain the same.

Specifically:

• In abstract-schema-builder.ts, add a protected escapeUnsafeJsonString(value: string): string method that implements the CodeQL‑style escaping on top of the JSON string.
• In joi-schema-builder.ts, change the default implementation so that it computes const defaultValue = this.escapeUnsafeJsonString(JSON.stringify(model.default)).
• Do the same in zod-v3-schema-builder.ts and zod-v4-schema-builder.ts.

No changes are required in server-operation-builder.ts or typescript-nextjs-router-builder.ts themselves; once the schema builders sanitize the default value, the tainted flow into the router template will be safe.