feat: bundle types (#14020)

This PR updates the build process to generate a single
`dist/index.bundled.d.ts` file that bundles all `payload` package types.

Having one bundled declaration file makes it easy to load types into the
Monaco editor (e.g. for the new Code block), enabling full type
completion for the `payload` package.

## Example

```ts
 BlocksFeature({
        blocks: [
          CodeBlock({
            slug: 'PayloadCode',
            languages: {
              ts: 'TypeScript',
            },
            typescript: {
              fetchTypes: [
                {
                  filePath: 'file:///node_modules/payload/index.d.ts',
                  url: 'https://unpkg.com/payload@3.59.0-internal.e247081/dist/index.bundled.d.ts', // <= download bundled .d.ts
                },
              ],
              paths: {
                payload: ['file:///node_modules/payload/index.d.ts'],
              },
              typeRoots: ['node_modules/@types', 'node_modules/payload'],
            },
          }),
        ],
      }),
```

<img width="1506" height="866" alt="Screenshot 2025-10-01 at 12 38
54@2x"
src="https://github.com/user-attachments/assets/135b9b69-058a-42b9-afa0-daa328f64f38"
/>




---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1211524241290884

Author: AlessioGr

eslint.config.js

@@ -24,6 +24,7 @@ export const defaultESLintIgnores = [
   '**/app',
   'src/**/*.spec.ts',
   '**/jest.setup.js',
+  'packages/payload/rollup.dts.config.mjs',
 ]
 
 /** @typedef {import('eslint').Linter.Config} Config */

packages/payload/eslint.config.js

@@ -5,10 +5,10 @@ import { rootEslintConfig, rootParserOptions } from '../../eslint.config.js'
 
 /**
  * We've removed all eslint.config.js from the packages, but we have to leave this one as an exception.
- * The payload package is so large that without its own eslint.config, an M3 Pro (18GB) runs out of 
+ * The payload package is so large that without its own eslint.config, an M3 Pro (18GB) runs out of
  * memory when linting. Interestingly, two days ago when I started this PR, this didn't happen, but it
  * started happening when I did a merge from main to update the PR.
- * tsc also takes a long time to run. It's likely that at some point we'll need to split the package 
+ * tsc also takes a long time to run. It's likely that at some point we'll need to split the package
  * (into payload1, payload2, etc.) and re-export them in payload.
  */
 /** @type {Config[]} */
@@ -21,11 +21,11 @@ export const index = [
         tsconfigRootDir: import.meta.dirname,
         projectService: {
             // See comment in packages/eslint-config/index.mjs
-            allowDefaultProject: ['bin.js', 'bundle.js'],
+            allowDefaultProject: ['bin.js', 'bundle.js', 'rollup.dts.config.mjs'],
           },
       },
     },
   },
 ]
 
-export default index
+export default index

packages/payload/package.json

@@ -71,10 +71,11 @@
     "bin.js"
   ],
   "scripts": {
-    "build": "rimraf .dist && rimraf tsconfig.tsbuildinfo && pnpm copyfiles && pnpm build:types && pnpm build:swc && echo skipping esbuild",
+    "build": "rimraf .dist && rimraf tsconfig.tsbuildinfo && pnpm copyfiles && pnpm build:types && pnpm build:swc && pnpm bundle:types && echo skipping esbuild",
     "build:bundle-for-analysis": "node ./bundle.js esbuild",
     "build:swc": "swc ./src -d ./dist --config-file .swcrc --strip-leading-paths",
     "build:types": "tsc --emitDeclarationOnly --outDir dist",
+    "bundle:types": "rollup -c rollup.dts.config.mjs",
     "clean": "rimraf -g {dist,*.tsbuildinfo}",
     "clean:cache": "rimraf node_modules/.cache",
     "copyfiles": "copyfiles -u 1 \"src/**/*.{html,ttf,woff,woff2,eot,svg,jpg,png,json}\" dist/",
@@ -132,6 +133,8 @@
     "graphql-http": "^1.22.0",
     "react-datepicker": "7.6.0",
     "rimraf": "6.0.1",
+    "rollup": "4.52.3",
+    "rollup-plugin-dts": "6.2.3",
     "sharp": "0.32.6"
   },
   "peerDependencies": {

packages/payload/rollup.dts.config.mjs

@@ -0,0 +1,46 @@
+import dts from 'rollup-plugin-dts'
+import path from 'node:path'
+
+import { builtinModules } from 'node:module'
+
+const WHITELIST = ['ts-essentials', 'croner', '@payloadcms/translations'] // <-- only these get bundled
+
+/**
+ * One-step DTS bundle:
+ * - Input from your TS source entry
+ * - Output to a single dist/index.bundled.d.ts
+ * - respectExternal: true -> aggressively inline third-party .d.ts (helps with ts-essentials)
+ */
+export default [
+  {
+    input: 'src/index.ts',
+    output: { file: 'dist/index.bundled.d.ts', format: 'es' },
+    plugins: [
+      dts({
+        tsconfig: './tsconfig.bundletypes.json',
+        respectExternal: true,
+        compilerOptions: {},
+      }),
+    ],
+
+    /**
+     * Externalize all non-whitelisted packages and Node builtins.
+     * If we bundle all packages, this script runs out of memory.
+     */
+    external: (id) => {
+      // 1) Always keep Node builtins external
+      if (builtinModules.includes(id) || builtinModules.includes(id.replace(/^node:/, '')))
+        return true
+
+      // 2) Keep virtual/internal rollup ids external just in case
+      if (id.startsWith('\0')) return true
+
+      // 3) Never externalize *local* files (we want our own .d.ts bundled)
+      if (id.startsWith('.') || path.isAbsolute(id)) return false
+
+      // 4) Bundle only whitelisted packages (opt-in)
+      const isWhitelisted = WHITELIST.some((p) => id === p || id.startsWith(`${p}/`))
+      return !isWhitelisted // everything else is external
+    },
+  },
+]

packages/payload/tsconfig.bundletypes.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "references": [{ "path": "../translations" }],
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as payload is a server-only package.
+    // This ensures node types do not conflict with node types (e.g. fetch.dispatcher)
+    "lib": ["ES2022"],
+    "paths": {
+      "@payloadcms/translations": ["../translations/dist/exports/index.d.ts"],
+      "@payloadcms/translations/utilities": ["../translations/dist/exports/utilities.d.ts"]
+    }
+  }
+}