@accelbyte/codegen 0.0.0-dev-20250519035357 → 0.0.0-dev-20260320085237

package/README.md

@@ -2,6 +2,10 @@
 
 AccelByte Code Generator is a CLI tool that facilitates creating an AccelByte TypeScript SDK from AccelByte OpenAPI definitions.
 
+## Requirements
+
+- **Node.js >= 22.18.0** (LTS) — required for native TypeScript type stripping, used to load `abcodegen.config.ts` at runtime.
+
 ## CLI
 This codegen build a CLI called `accelbyte-codegen` that will be used to generate code from given config.
 
@@ -33,9 +37,11 @@ Provide swaggers url you wish to generate, store it in .json format file.
 
 ## How to Generate
 
-**Step 1: Set Up Your Node.js Environment** Make sure you have Node.js and npm (Node Package Manager) installed on your system. You can download and install them from the official website: https://nodejs.org/en/ 
+**Step 1: Set Up Your Node.js Environment** Make sure you have **Node.js >= 22.18.0** (LTS) and npm (Node Package Manager) installed on your system. You can download and install them from the official website: https://nodejs.org/en/
 
-__*It is recommended__ to use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install Node.js so you can switch between Node versions more easily 
+This minimum version is required because the codegen loads `abcodegen.config.ts` at runtime using Node.js native TypeScript type stripping, which was unflagged in Node.js 22.18.0.
+
+__*It is recommended__ to use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install Node.js so you can switch between Node versions more easily
 
 **Step 2: Create a New Node.js Project (if needed)** If you are starting a new project, create a new directory and initialize it as a Node.js project. You can do this using the following commands: 
 ```
@@ -110,4 +116,44 @@ after installing, execute prettier as below
 npm exec prettier --write swaggers/*.json && prettier --write sdk/**/*
 # Or, with yarn:
 yarn prettier --write swaggers/*.json && prettier --write sdk/**/*
+```
+
+## Configuration
+
+Place an `abcodegen.config.ts` file next to your `swaggers.json` to customize codegen behavior. All options are optional — if the file is absent, defaults apply.
+
+```typescript
+// abcodegen.config.ts
+export default {
+  // Override the base path prepended to all API routes.
+  // Default: uses basePath from the swagger spec.
+  basePath: '/custom',
+
+  // Skip generation of barrel index files (index.ts, all-query-imports.ts).
+  // Default: true
+  unstable_shouldProduceIndexFile: false,
+
+  // Force specific definitions to emit `z.any()` instead of a full schema.
+  // Keyed by definition file name. Value can be `true` or a function receiving the schema.
+  unstable_overrideAsAny: {
+    ProtobufAny: true,
+    SomeOther: (schema) => schema.properties?.['@type'] !== undefined
+  }
+}
+```
+
+## Design Decisions
+
+### Zod definitions use `interface`, not `type`
+
+Generated definitions use `interface Foo extends z.TypeOf<typeof Foo> {}` rather than a `type` alias. This makes editors display the object shape directly on hover instead of showing the `z.TypeOf<...>` indirection.
+
+This triggers `@typescript-eslint/no-empty-object-type`. That rule guards against the `{}` gotcha in hand-written code, which does not apply to generated output. Consumers can disable it for generated files:
+
+```js
+// eslint.config.js
+{
+  files: ['src/generated-definitions/**'],
+  rules: { '@typescript-eslint/no-empty-object-type': 'off' }
+}
 ```