From c8a4e56be1ca4d680ab304c0544b79ebe13d60b3 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Wed, 2 Sep 2026 16:13:55 +0000
Subject: [PATCH] docs(typescript): document packageJsonMergeStrategy

Co-Authored-By: bot_apk <apk@cognition.ai>
---
 .../generators/typescript/configuration.mdx   | 25 +++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/fern/products/sdks/generators/typescript/configuration.mdx b/fern/products/sdks/generators/typescript/configuration.mdx
index 71084cadd2..40dd21b381 100644
--- a/fern/products/sdks/generators/typescript/configuration.mdx
+++ b/fern/products/sdks/generators/typescript/configuration.mdx
@@ -450,6 +450,31 @@ config:
 ```
 
 You can also use `packageJson.exports` to register custom subpath exports (e.g. `import { myHelper } from "@acme/sdk/helper"`). The generator only auto-generates export entries for your API definition, so custom files need to be added manually—otherwise Node.js won't resolve subpath imports for them. See [Adding custom code](/learn/sdks/generators/typescript/custom-code) for details.
+
+How nested objects are combined with the generated values is controlled by `packageJsonMergeStrategy`.
+</ParamField>
+
+<ParamField path="packageJsonMergeStrategy" type="'shallow' | 'deep'" default="shallow" toc={true}>
+Controls how nested objects in `packageJson` are merged into the generated `package.json`. Top-level values you specify always win over generated ones, and arrays (such as `files`) are unioned with your entries first.
+
+- `shallow` (default): nested objects one level below a top-level key are replaced wholesale. For example, overriding `exports["."]` replaces the generated `import`/`require`/`default` conditions with exactly what you wrote.
+- `deep`: nested objects are merged recursively. Your keys win at every level, keys you don't mention are inherited from the generated output, and your keys are emitted first in the order you wrote them, so a custom `exports` condition precedes the generated ones and Node.js matches it first.
+
+Use `deep` to add a custom export condition without redefining the whole subpath:
+
+```yaml
+# generators.yml
+config:
+  packageJsonMergeStrategy: deep
+  packageJson:
+    exports:
+      ".":
+        "my-dev-condition":
+          types: "./dist/cjs/index.d.ts"
+          default: "./src/index.ts"
+```
+
+Removing a generated key (for example dropping the `require` condition) is not expressible under either strategy.
 </ParamField>
 
 <ParamField path="package-name" type="string" default="null" required={false} toc={true}>