diff --git a/cli/src/api/build.ts b/cli/src/api/build.ts
index 4446bb5c..821fb17f 100644
--- a/cli/src/api/build.ts
+++ b/cli/src/api/build.ts
@@ -798,7 +798,20 @@ class Builder {
       this.envs.TYPE_DEF_TMP_PATH,
       this.options.constEnum ?? true,
       !this.options.noDtsHeader
-        ? this.options.dtsHeader ?? DEFAULT_TYPE_DEF_HEADER
+        ? this.options.dtsHeader ??
+            (this.config.dtsHeaderFile
+              ? await readFileAsync(
+                  join(this.cwd, this.config.dtsHeaderFile),
+                  'utf-8',
+                ).catch(() => {
+                  debug.warn(
+                    `Failed to read dts header file ${this.config.dtsHeaderFile}`,
+                  )
+                  return null
+                })
+              : null) ??
+            this.config.dtsHeader ??
+            DEFAULT_TYPE_DEF_HEADER
         : '',
     )
 
@@ -876,8 +889,8 @@ class Builder {
           name,
           this.config.packageName,
           wasiRegisterFunctions,
-          this.config.wasm.initialMemory,
-          this.config.wasm.maximumMemory,
+          this.config.wasm?.initialMemory,
+          this.config.wasm?.maximumMemory,
         ) +
           exportsCode +
           '\n',
@@ -888,8 +901,8 @@ class Builder {
         createWasiBrowserBinding(
           name,
           wasiRegisterFunctions,
-          this.config.wasm.initialMemory,
-          this.config.wasm.maximumMemory,
+          this.config.wasm?.initialMemory,
+          this.config.wasm?.maximumMemory,
         ) +
           idents
             .map(
diff --git a/cli/src/utils/__tests__/__snapshots__/config.spec.ts.md b/cli/src/utils/__tests__/__snapshots__/config.spec.ts.md
index 4eca4920..e3c8cc5c 100644
--- a/cli/src/utils/__tests__/__snapshots__/config.spec.ts.md
+++ b/cli/src/utils/__tests__/__snapshots__/config.spec.ts.md
@@ -48,7 +48,6 @@ Generated by [AVA](https://avajs.dev).
           triple: 'x86_64-apple-darwin',
         },
       ],
-      wasm: {},
     }
 
 ## should be able to read config from napi.json
@@ -95,5 +94,4 @@ Generated by [AVA](https://avajs.dev).
           triple: 'aarch64-apple-darwin',
         },
       ],
-      wasm: {},
     }
diff --git a/cli/src/utils/__tests__/__snapshots__/config.spec.ts.snap b/cli/src/utils/__tests__/__snapshots__/config.spec.ts.snap
index 975c7e1d..38093d05 100644
Binary files a/cli/src/utils/__tests__/__snapshots__/config.spec.ts.snap and b/cli/src/utils/__tests__/__snapshots__/config.spec.ts.snap differ
diff --git a/cli/src/utils/config.ts b/cli/src/utils/config.ts
index acc96875..70b1ba36 100644
--- a/cli/src/utils/config.ts
+++ b/cli/src/utils/config.ts
@@ -42,6 +42,17 @@ export interface UserNapiConfig {
    */
   constEnum?: boolean
 
+  /**
+   * dts header prepend to the generated dts file
+   */
+  dtsHeader?: string
+
+  /**
+   * dts header file path to be prepended to the generated dts file
+   * if both dtsHeader and dtsHeaderFile are provided, dtsHeaderFile will be used
+   */
+  dtsHeaderFile?: string
+
   /**
    * wasm compilation options
    */
@@ -116,11 +127,12 @@ export interface CommonPackageJsonFields {
 }
 
 export type NapiConfig = Required<
-  Pick<UserNapiConfig, 'binaryName' | 'packageName' | 'npmClient' | 'wasm'>
-> & {
-  targets: Target[]
-  packageJson: CommonPackageJsonFields
-}
+  Pick<UserNapiConfig, 'binaryName' | 'packageName' | 'npmClient'>
+> &
+  Pick<UserNapiConfig, 'wasm' | 'dtsHeader' | 'dtsHeaderFile'> & {
+    targets: Target[]
+    packageJson: CommonPackageJsonFields
+  }
 
 export async function readNapiConfig(
   path: string,
@@ -173,7 +185,6 @@ export async function readNapiConfig(
       targets: [],
       packageJson: pkgJson,
       npmClient: 'npm',
-      wasm: {},
     },
     omit(userNapiConfig, 'targets'),
   )
diff --git a/cli/src/utils/typegen.ts b/cli/src/utils/typegen.ts
index 610c1705..5b254b37 100644
--- a/cli/src/utils/typegen.ts
+++ b/cli/src/utils/typegen.ts
@@ -64,7 +64,7 @@ export async function processTypeDef(
   const defs = await readIntermediateTypeFile(intermediateTypeFile)
   const groupedDefs = preprocessTypeDef(defs)
 
-  header = header ? header + '\n' : ''
+  header = header ?? ''
   let dts = ''
 
   sortBy(Array.from(groupedDefs), ([namespace]) => namespace).forEach(
diff --git a/examples/napi/__tests__/__snapshots__/typegen.spec.ts.md b/examples/napi/__tests__/__snapshots__/typegen.spec.ts.md
index 09d3d5e1..1d0ffc52 100644
--- a/examples/napi/__tests__/__snapshots__/typegen.spec.ts.md
+++ b/examples/napi/__tests__/__snapshots__/typegen.spec.ts.md
@@ -11,6 +11,7 @@ Generated by [AVA](https://avajs.dev).
     `/* auto-generated by NAPI-RS */␊
     /* eslint-disable */␊
     ␊
+    type MaybePromise<T> = T | Promise<T>␊
     ␊
     export class ExternalObject<T> {␊
       readonly '': {␊
diff --git a/examples/napi/__tests__/__snapshots__/typegen.spec.ts.snap b/examples/napi/__tests__/__snapshots__/typegen.spec.ts.snap
index fed22a6f..54ed56dc 100644
Binary files a/examples/napi/__tests__/__snapshots__/typegen.spec.ts.snap and b/examples/napi/__tests__/__snapshots__/typegen.spec.ts.snap differ
diff --git a/examples/napi/__tests__/__snapshots__/values.spec.ts.snap b/examples/napi/__tests__/__snapshots__/values.spec.ts.snap
index 164d8175..2b1be196 100644
Binary files a/examples/napi/__tests__/__snapshots__/values.spec.ts.snap and b/examples/napi/__tests__/__snapshots__/values.spec.ts.snap differ
diff --git a/examples/napi/dts-header.d.ts b/examples/napi/dts-header.d.ts
new file mode 100644
index 00000000..3986614f
--- /dev/null
+++ b/examples/napi/dts-header.d.ts
@@ -0,0 +1,4 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+
+type MaybePromise<T> = T | Promise<T>
diff --git a/examples/napi/index.d.cts b/examples/napi/index.d.cts
index 993d69dd..93e5500c 100644
--- a/examples/napi/index.d.cts
+++ b/examples/napi/index.d.cts
@@ -1,6 +1,7 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
 
+type MaybePromise<T> = T | Promise<T>
 
 export class ExternalObject<T> {
   readonly '': {
diff --git a/examples/napi/package.json b/examples/napi/package.json
index 7c84ac45..0e36107e 100644
--- a/examples/napi/package.json
+++ b/examples/napi/package.json
@@ -14,7 +14,9 @@
     "binaryName": "example",
     "wasm": {
       "initialMemory": 16384
-    }
+    },
+    "dtsHeader": "type MaybePromise<T> = T | Promise<T>",
+    "dtsHeaderFile": "./dts-header.d.ts"
   },
   "devDependencies": {
     "@napi-rs/cli": "workspace:*",