graphite-app · Jan 9, 2026 · Jan 9, 2026
@@ -0,0 +1,53 @@
+**Multiple chunk groups with priorities**
+
+```js
+export default defineConfig({
+  output: {
+    advancedChunks: {
+      groups: [
+        {
+          name: 'react-vendor',
+          test: /node_modules[\\/]react/,
+          priority: 20,
+        },
+        {
+          name: 'ui-vendor',
+          test: /node_modules[\\/](antd|@mui)/,
+          priority: 15,
+        },
+        {
+          name: 'vendor',
+          test: /node_modules/,
+          priority: 10,
+        },
+        {
+          name: 'common',
+          minShareCount: 2,
+          minSize: 10000,
+          priority: 5,
+        },
+      ],
+    },
+  },
+});
+```
+
+**Size-based splitting**
+
+```js
+export default defineConfig({
+  output: {
+    advancedChunks: {
+      groups: [
+        {
+          name: 'large-libs',
+          test: /node_modules/,
+          minSize: 100000, // 100KB
+          maxSize: 250000, // 250KB
+          priority: 10,
+        },
+      ],
+    },
+  },
+});
+```
@@ -0,0 +1,14 @@
+:::warning
+
+When using `output.banner` with minification enabled, the banner content may be stripped out unless it is formatted as a legal comment. To ensure your banner persists through minification, do either:
+
+- Use [`output.postBanner`](/reference/OutputOptions.postBanner) instead, which are added after minification, or
+- Use one of these comment formats:
+  - Comments starting with `/*!` (e.g., `/*! My banner */`)
+  - Comments containing `@license` (e.g., `/* @license My banner */`)
+  - Comments containing `@preserve` (e.g., `/* @preserve My banner */`)
+  - Comments starting with `//!` (for single-line comments)
+
+The latter way's behavior is controlled by the [`output.legalComments`](/reference/OutputOptions.legalComments) option, which defaults to `'inline'` and preserves these special comment formats.
+
+:::
@@ -0,0 +1,105 @@
+#### Examples
+
+##### Basic usage
+
+```js
+export default {
+  output: {
+    cleanDir: true,
+  },
+};
+```
+
+##### Multiple outputs in one config
+
+When multiple outputs share the same directory, only set `cleanDir: true` for the first output:
+
+```js
+export default {
+  output: [
+    {
+      dir: 'dist',
+      format: 'es',
+      cleanDir: true, // Clean on first output
+    },
+    {
+      dir: 'dist',
+      format: 'cjs',
+      // cleanDir defaults to false, so files from first output are preserved
+    },
+  ],
+};
+```
+
+##### Multiple configurations
+
+When multiple configurations share the same directory, only set `cleanDir: true` for the first configuration:
+
+```js
+export default [
+  {
+    input: 'src/index.js',
+    output: {
+      dir: 'dist',
+      cleanDir: true, // Clean on first configuration
+    },
+  },
+  {
+    input: 'src/other.js',
+    output: {
+      dir: 'dist',
+      // cleanDir defaults to false, so files from first config are preserved
+    },
+  },
+];
+```
+
+##### Different directories in multiple outputs
+
+When multiple outputs use different directories, you can safely use `cleanDir: true` for each:
+
+```js
+export default {
+  output: [
+    {
+      dir: 'dist/es',
+      format: 'es',
+      cleanDir: true, // Safe - different directory
+    },
+    {
+      dir: 'dist/cjs',
+      format: 'cjs',
+      cleanDir: true, // Safe - different directory
+    },
+  ],
+};
+```
+
+#### In-depth
+
+##### Execution timing
+
+The timing of the directory cleanup is important for plugin compatibility:
+
+- The cleanup occurs **before** the `generateBundle` hook is called
+- Files created by plugins during `generateBundle` or `writeBundle` hooks are **not** deleted
+- This ensures that plugin-generated files are preserved even when `cleanDir` is enabled
+
+For advanced use cases involving multiple outputs with the same `output.dir`, consider using a separate cleanup script for more control over the cleanup process.
+
+##### ⚠️ Multiple configurations behavior
+
+When using multiple configurations or outputs, the `cleanDir` option will be executed **separately for each configuration/output** following the order they are defined.
+
+**The two patterns:**
+
+- **Multiple configurations**: `export default defineConfig([{ output: { cleanDir: true, ... } }, { output: {...} }])`
+- **Multiple outputs in one config**: `defineConfig({ output: [{ cleanDir: true, ... }, { ... }] })`
+
+**The problem:**
+
+If multiple outputs share the same `output.dir` and have `cleanDir: true`, later outputs may clean files generated by earlier outputs. This happens because each output executes its cleanup independently.
+
+**Best practice:**
+
+To avoid this issue, only set `cleanDir: true` for the first output, or use different output directories. This ensures that all generated files are preserved.
@@ -0,0 +1,14 @@
+:::warning
+
+When using `output.footer` with minification enabled, the footer content may be stripped out unless it is formatted as a legal comment. To ensure your footer persists through minification, do either:
+
+- Use [`output.postFooter`](/reference/OutputOptions.postFooter) instead, which is added after minification, or
+- Use one of these comment formats:
+  - Comments starting with `/*!` (e.g., `/*! My footer */`)
+  - Comments containing `@license` (e.g., `/* @license My footer */`)
+  - Comments containing `@preserve` (e.g., `/* @preserve My footer */`)
+  - Comments starting with `//!` (for single-line comments)
+
+The latter way's behavior is controlled by the [`output.legalComments`](/reference/OutputOptions.legalComments) option, which defaults to `'inline'` and preserves these special comment formats.
+
+:::
@@ -0,0 +1,7 @@
+::: warning Note
+
+Enabling this option makes the generated output more difficult to minify effectively. For this reason, it should generally be avoided for libraries and production builds.
+
+Only enable this option when you specifically need better profiling support during development or debugging.
+
+:::
@@ -364,8 +364,8 @@ export interface InputOptions {
    *    - The conditions setting does not automatically include any platform-specific values.
    *
    * @default
-   * - 'node' if the format is 'cjs'
-   * - 'browser' for other formats
+   * - `'node'` if the format is `'cjs'`
+   * - `'browser'` for other formats
    * {@include ./docs/platform.md}
    */
   platform?: 'node' | 'browser' | 'neutral';

@@ -26,6 +26,8 @@ export interface GeneratedCodeOptions {
    *   }
    * };
    * ```
+   *
+   * @default 'es2015'
    */
   preset?: GeneratedCodePreset;
   /**
@@ -34,9 +36,9 @@ export interface GeneratedCodeOptions {
    * When enabled, generated code will use descriptive variable names that correspond
    * to the original module names, making it easier to profile and debug the bundled code.
    *
-   * Note: Enabling this option makes the output more difficult to minify effectively.
-   *
    * @default false
+   *
+   * {@include ./docs/output-generated-code-profiler-names.md}
    */
   profilerNames?: boolean;
 }
@@ -140,17 +142,18 @@ export interface OutputOptions {
   /**
    * Whether to generate sourcemaps.
    *
-   * When `true`, a separate sourcemap file will be generated.
-   * When `'inline'`, the sourcemap will be appended to the output file as a data URL.
-   * When `'hidden'`, a separate sourcemap file will be generated, but the link to the sourcemap will not be included in the output file.
+   * - `false`: No sourcemap will be generated.
+   * - `true`: A separate sourcemap file will be generated.
+   * - `'inline'`: The sourcemap will be appended to the output file as a data URL.
+   * - `'hidden'`: A separate sourcemap file will be generated, but the link to the sourcemap (`//# sourceMappingURL` comment) will not be included in the output file.
    *
    * @default false
    */
   sourcemap?: boolean | 'inline' | 'hidden';
   /**
    * The base URL for the links to the sourcemap file in the output file.
    *
-   * By default, relative URLs are generated. If this option is set, an absolute URL with that base URL will be generated.
+   * By default, relative URLs are generated. If this option is set, an absolute URL with that base URL will be generated. This is useful when deploying source maps to a different location than your code, such as a CDN or separate debugging server.
    */
   sourcemapBaseUrl?: string;
   /**
@@ -196,18 +199,35 @@ export interface OutputOptions {
   sourcemapIgnoreList?: boolean | SourcemapIgnoreListOption | StringOrRegExp;
   /**
    * A transformation to apply to each path in a sourcemap.
+   *
+   * @example
+   * ```js
+   * export default defineConfig({
+   *   output: {
+   *     sourcemap: true,
+   *     sourcemapPathTransform: (source, sourcemapPath) => {
+   *       // Remove 'src/' prefix from all source paths
+   *       return source.replace(/^src\//, '');
+   *     },
+   *   },
+   * });
+   * ```
    */
   sourcemapPathTransform?: SourcemapPathTransformOption;
   /**
    * A string to prepend to the bundle before `renderChunk` hook.
    *
    * See [`output.intro`](https://rolldown.rs/reference/OutputOptions.intro), [`output.postBanner`](https://rolldown.rs/reference/OutputOptions.postBanner) as well.
+   *
+   * {@include ./docs/output-banner.md}
    */
   banner?: string | AddonFunction;
   /**
    * A string to append to the bundle before `renderChunk` hook.
    *
    * See [`output.outro`](https://rolldown.rs/reference/OutputOptions.outro), [`output.postFooter`](https://rolldown.rs/reference/OutputOptions.postFooter) as well.
+   *
+   * {@include ./docs/output-footer.md}
    */
   footer?: string | AddonFunction;
   /**
@@ -267,6 +287,8 @@ export interface OutputOptions {
    * Forward slashes (`/`) can be used to place files in sub-directories.
    *
    * See also [`output.chunkFileNames`](https://rolldown.rs/reference/OutputOptions.chunkFileNames), [`output.entryFileNames`](https://rolldown.rs/reference/OutputOptions.entryFileNames).
+   *
+   * @default 'assets/[name]-[hash][extname]'
    */
   assetFileNames?: string | AssetFileNamesFunction;
   /**
@@ -280,6 +302,8 @@ export interface OutputOptions {
    * Forward slashes (`/`) can be used to place files in sub-directories. This pattern will also be used for every file when setting the [`output.preserveModules`](https://rolldown.rs/reference/OutputOptions.preserveModules) option.
    *
    * See also [`output.assetFileNames`](https://rolldown.rs/reference/OutputOptions.assetFileNames), [`output.chunkFileNames`](https://rolldown.rs/reference/OutputOptions.chunkFileNames).
+   *
+   * @default '[name].js'
    */
   entryFileNames?: string | ChunkFileNamesFunction;
   /**
@@ -293,14 +317,18 @@ export interface OutputOptions {
    * Forward slashes (`/`) can be used to place files in sub-directories.
    *
    * See also [`output.assetFileNames`](https://rolldown.rs/reference/OutputOptions.assetFileNames), [`output.entryFileNames`](https://rolldown.rs/reference/OutputOptions.entryFileNames).
+   *
+   * @default '[name]-[hash].js'
    */
   chunkFileNames?: string | ChunkFileNamesFunction;
   /**
+   * @default '[name].css'
    * @experimental
    * @hidden not ready for public usage yet
    */
   cssEntryFileNames?: string | ChunkFileNamesFunction;
   /**
+   * @default '[name]-[hash].css'
    * @experimental
    * @hidden not ready for public usage yet
    */
@@ -488,6 +516,25 @@ export interface OutputOptions {
   manualChunks?: ManualChunksFunction;
   /**
    * Allows you to do manual chunking. For deeper understanding, please refer to the in-depth [documentation](https://rolldown.rs/in-depth/advanced-chunks).
+   *
+   * @example
+   * **Basic vendor chunk**
+   * ```js
+   * export default defineConfig({
+   *   output: {
+   *     advancedChunks: {
+   *       minSize: 20000,
+   *       groups: [
+   *         {
+   *           name: 'vendor',
+   *           test: /node_modules/,
+   *         },
+   *       ],
+   *     },
+   *   },
+   * });
+   * ```
+   * {@include ./docs/output-advanced-chunks.md}
    */
   advancedChunks?: {
     /**
@@ -594,6 +641,8 @@ export interface OutputOptions {
    * Clean output directory ([`output.dir`](https://rolldown.rs/reference/OutputOptions.dir)) before emitting output.
    *
    * @default false
+   *
+   * {@include ./docs/output-clean-dir.md}
    */
   cleanDir?: boolean;
   /**
@@ -680,8 +729,7 @@ export type AdvancedChunksGroup = {
    *
    * If two groups have the same priority, the group whose index is smaller will be chosen.
    *
-   * For example,
-   *
+   * @example
    * ```js
    * import { defineConfig } from 'rolldown';
    *
@@ -691,19 +739,17 @@ export type AdvancedChunksGroup = {
    *      {
    *        name: 'react',
    *        test: /node_modules[\\/]react/,
-   *        priority: 1,
+   *        priority: 2,
    *      },
    *      {
    *        name: 'other-libs',
    *        test: /node_modules/,
-   *        priority: 2,
+   *        priority: 1,
    *      },
    *   ],
    * });
    * ```
    *
-   * This is a clearly __incorrect__ example. Though `react` group is defined before `other-libs`, it has a lower priority, so the modules in `react` group will be captured in `other-libs` group.
-   *
    * @default 0
    */
   priority?: number;