@accelbyte/codegen 0.0.0-dev-20250530101210 → 0.0.0-dev-20260326093546

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/
+
+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 
+__*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,52 @@ 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
+import { type CodegenConfigOptions } from '@accelbyte/codegen'
+
+export default {
+  // Override the base path prepended to all API routes.
+  // Default: uses basePath from the swagger spec.
+  basePath: '/custom',
+
+  // Generate barrel index files (index.ts, all-imports.ts, all-query-imports.ts).
+  // Default: true
+  unstable_shouldProduceIndexFiles: 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
+  }
+} satisfies CodegenConfigOptions
+```
+
+## 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' }
+}
+```
+
+## Troubleshooting
+
+### Type or lint errors in generated files
+
+The generated code aims to use neutral, unopinionated style defaults. However, some generated syntax may conflict with your tsconfig or linter settings. In that case, you can ignore specific lint rules in the codegen folder, or create a `tsconfig.json` inside it to override your top-level configuration.

package/dist/accelbyte-codegen.d.mts

@@ -0,0 +1,22 @@
+interface CodegenConfigOptions {
+    /**
+     * 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.
+     *
+     * @example
+     * { ProtobufAny: true, SomeOther: (schema) => schema.properties?.['@type'] !== undefined }
+     */
+    unstable_overrideAsAny?: Record<string, boolean | ((schema: Record<string, any>) => boolean)>;
+    /**
+     * Generate barrel index files (index.ts, all-imports.ts, all-query-imports.ts).
+     * @default true
+     */
+    unstable_shouldProduceIndexFiles?: boolean;
+    /**
+     * Override the base path prepended to all API routes.
+     * @default `basePath` from the swagger spec
+     */
+    basePath?: string;
+}
+
+export type { CodegenConfigOptions };

package/dist/accelbyte-codegen.d.ts

@@ -0,0 +1,22 @@
+interface CodegenConfigOptions {
+    /**
+     * 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.
+     *
+     * @example
+     * { ProtobufAny: true, SomeOther: (schema) => schema.properties?.['@type'] !== undefined }
+     */
+    unstable_overrideAsAny?: Record<string, boolean | ((schema: Record<string, any>) => boolean)>;
+    /**
+     * Generate barrel index files (index.ts, all-imports.ts, all-query-imports.ts).
+     * @default true
+     */
+    unstable_shouldProduceIndexFiles?: boolean;
+    /**
+     * Override the base path prepended to all API routes.
+     * @default `basePath` from the swagger spec
+     */
+    basePath?: string;
+}
+
+export type { CodegenConfigOptions };