Add custom dts headers doc (#419)

* Add custom dts headers doc

* fix: address PR review comments

- Fix dtsHeader documentation to correctly state it replaces (not appends to) the default header
- Remove auto-generated routes.d.ts reference from next-env.d.ts that breaks fresh checkouts

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: Brooooooklyn

pages/docs/concepts/types-overwrite.en.md

@@ -106,3 +106,112 @@ export interface TsTypeChanged {
   typeOverrideOptional?: object
 }
 ```
+
+## Custom Type Definitions in Header
+
+When NAPI-RS generates `index.d.ts`, it includes a default header. You can customize this header to add your own TypeScript types, imports, or comments that your native module needs.
+
+### Use Cases
+
+- **Custom type aliases**: Define types like `MaybePromise<T>` used by your API
+- **Import external types**: Import `ReadableStream`, `Buffer`, or other Node.js types
+- **ESLint/TypeScript directives**: Add `// @ts-nocheck` or custom rules
+- **Documentation**: Copyright notices, version info, or deprecation warnings
+- **Declare symbols**: Export constants or symbols used by your bindings
+
+### Configuration Options
+
+| Method            | Location    | Best For                     |
+| ----------------- | ----------- | ---------------------------- |
+| `dtsHeaderFile`   | napi config | Complex headers with imports |
+| `dtsHeader`       | napi config | Simple single-line additions |
+| `--dts-header`    | CLI flag    | CI/CD overrides              |
+| `--no-dts-header` | CLI flag    | Disable header entirely      |
+
+### Priority Resolution
+
+When multiple options are set, NAPI-RS resolves them in this order:
+
+| Priority | Source                   | Description                                         |
+| :------: | ------------------------ | --------------------------------------------------- |
+|    1     | `dtsHeaderFile` (config) | File path in `napi` config - **always wins if set** |
+|    2     | `--dts-header` (CLI)     | CLI flag overrides inline config                    |
+|    3     | `dtsHeader` (config)     | Inline string in `napi` config                      |
+|    4     | Default header           | Used when nothing else is specified                 |
+
+> **Key point**: `dtsHeaderFile` in config takes precedence over ALL other options, including the `--dts-header` CLI flag. If you need CLI override capability, use `dtsHeader` instead of `dtsHeaderFile`.
+
+### Example Scenarios
+
+| Config `dtsHeaderFile` | Config `dtsHeader` | CLI `--dts-header` | Result               |
+| :--------------------: | :----------------: | :----------------: | -------------------- |
+|    `./header.d.ts`     |   `"type X = Y"`   |  `"// override"`   | Uses `./header.d.ts` |
+|           -            |   `"type X = Y"`   |  `"// override"`   | Uses `"// override"` |
+|           -            |   `"type X = Y"`   |         -          | Uses `"type X = Y"`  |
+|           -            |         -          |         -          | Uses default header  |
+
+### Using `dtsHeaderFile` (Recommended)
+
+Create a separate `.d.ts` file for complex headers:
+
+**Step 1: Create the header file**
+
+```typescript filename="dts-header.d.ts"
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+
+import type { ReadableStream } from 'node:stream/web'
+
+type MaybePromise<T> = T | Promise<T>
+
+export declare const MY_SYMBOL: symbol
+```
+
+**Step 2: Reference it in package.json**
+
+```json filename="package.json"
+{
+  "napi": {
+    "dtsHeaderFile": "./dts-header.d.ts"
+  }
+}
+```
+
+> ⚠️ The file content **completely replaces** the default header. Include the auto-generated comment and eslint directive if you want to keep them.
+
+### Using `dtsHeader` (Inline)
+
+For simple additions, use an inline string in your config:
+
+```json filename="package.json"
+{
+  "napi": {
+    "dtsHeader": "type MaybePromise<T> = T | Promise<T>"
+  }
+}
+```
+
+This completely replaces the default header. Include the auto-generated comment and eslint directive in the string if you want to keep them.
+
+### CLI Options
+
+**`--dts-header`**: Override the header via CLI (useful for CI/CD):
+
+```sh
+napi build --dts-header "// Custom header"
+```
+
+**`--no-dts-header`**: Generate `.d.ts` without any header:
+
+```sh
+napi build --no-dts-header
+```
+
+### Default Header
+
+Without customization, NAPI-RS uses:
+
+```typescript
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+```