Visitar URL original
docs(options): port content from options page to reference page (#7822) · rolldown/rolldown@cb8db7d · GitHub
Skip to content

Commit cb8db7d

Browse files
sapphi-redsapphi-red
committed
docs(options): port content from options page to reference page (#7822)
Ported content under `/options` to `/reference`
1 parent 66957b4 commit cb8db7d

7 files changed

Lines changed: 253 additions & 14 deletions

File tree

‎packages/rolldown/src/options/docs/output-advanced-chunks.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
**Multiple chunk groups with priorities**
2+
3+
```js
4+
export default defineConfig({
5+
output: {
6+
advancedChunks: {
7+
groups: [
8+
{
9+
name: 'react-vendor',
10+
test: /node_modules[\\/]react/,
11+
priority: 20,
12+
},
13+
{
14+
name: 'ui-vendor',
15+
test: /node_modules[\\/](antd|@mui)/,
16+
priority: 15,
17+
},
18+
{
19+
name: 'vendor',
20+
test: /node_modules/,
21+
priority: 10,
22+
},
23+
{
24+
name: 'common',
25+
minShareCount: 2,
26+
minSize: 10000,
27+
priority: 5,
28+
},
29+
],
30+
},
31+
},
32+
});
33+
```
34+
35+
**Size-based splitting**
36+
37+
```js
38+
export default defineConfig({
39+
output: {
40+
advancedChunks: {
41+
groups: [
42+
{
43+
name: 'large-libs',
44+
test: /node_modules/,
45+
minSize: 100000, // 100KB
46+
maxSize: 250000, // 250KB
47+
priority: 10,
48+
},
49+
],
50+
},
51+
},
52+
});
53+
```

‎packages/rolldown/src/options/docs/output-banner.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
:::warning
2+
3+
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:
4+
5+
- Use [`output.postBanner`](/reference/OutputOptions.postBanner) instead, which are added after minification, or
6+
- Use one of these comment formats:
7+
- Comments starting with `/*!` (e.g., `/*! My banner */`)
8+
- Comments containing `@license` (e.g., `/* @license My banner */`)
9+
- Comments containing `@preserve` (e.g., `/* @preserve My banner */`)
10+
- Comments starting with `//!` (for single-line comments)
11+
12+
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.
13+
14+
:::

‎packages/rolldown/src/options/docs/output-clean-dir.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
#### Examples
2+
3+
##### Basic usage
4+
5+
```js
6+
export default {
7+
output: {
8+
cleanDir: true,
9+
},
10+
};
11+
```
12+
13+
##### Multiple outputs in one config
14+
15+
When multiple outputs share the same directory, only set `cleanDir: true` for the first output:
16+
17+
```js
18+
export default {
19+
output: [
20+
{
21+
dir: 'dist',
22+
format: 'es',
23+
cleanDir: true, // Clean on first output
24+
},
25+
{
26+
dir: 'dist',
27+
format: 'cjs',
28+
// cleanDir defaults to false, so files from first output are preserved
29+
},
30+
],
31+
};
32+
```
33+
34+
##### Multiple configurations
35+
36+
When multiple configurations share the same directory, only set `cleanDir: true` for the first configuration:
37+
38+
```js
39+
export default [
40+
{
41+
input: 'src/index.js',
42+
output: {
43+
dir: 'dist',
44+
cleanDir: true, // Clean on first configuration
45+
},
46+
},
47+
{
48+
input: 'src/other.js',
49+
output: {
50+
dir: 'dist',
51+
// cleanDir defaults to false, so files from first config are preserved
52+
},
53+
},
54+
];
55+
```
56+
57+
##### Different directories in multiple outputs
58+
59+
When multiple outputs use different directories, you can safely use `cleanDir: true` for each:
60+
61+
```js
62+
export default {
63+
output: [
64+
{
65+
dir: 'dist/es',
66+
format: 'es',
67+
cleanDir: true, // Safe - different directory
68+
},
69+
{
70+
dir: 'dist/cjs',
71+
format: 'cjs',
72+
cleanDir: true, // Safe - different directory
73+
},
74+
],
75+
};
76+
```
77+
78+
#### In-depth
79+
80+
##### Execution timing
81+
82+
The timing of the directory cleanup is important for plugin compatibility:
83+
84+
- The cleanup occurs **before** the `generateBundle` hook is called
85+
- Files created by plugins during `generateBundle` or `writeBundle` hooks are **not** deleted
86+
- This ensures that plugin-generated files are preserved even when `cleanDir` is enabled
87+
88+
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.
89+
90+
##### ⚠️ Multiple configurations behavior
91+
92+
When using multiple configurations or outputs, the `cleanDir` option will be executed **separately for each configuration/output** following the order they are defined.
93+
94+
**The two patterns:**
95+
96+
- **Multiple configurations**: `export default defineConfig([{ output: { cleanDir: true, ... } }, { output: {...} }])`
97+
- **Multiple outputs in one config**: `defineConfig({ output: [{ cleanDir: true, ... }, { ... }] })`
98+
99+
**The problem:**
100+
101+
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.
102+
103+
**Best practice:**
104+
105+
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.

‎packages/rolldown/src/options/docs/output-footer.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
:::warning
2+
3+
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:
4+
5+
- Use [`output.postFooter`](/reference/OutputOptions.postFooter) instead, which is added after minification, or
6+
- Use one of these comment formats:
7+
- Comments starting with `/*!` (e.g., `/*! My footer */`)
8+
- Comments containing `@license` (e.g., `/* @license My footer */`)
9+
- Comments containing `@preserve` (e.g., `/* @preserve My footer */`)
10+
- Comments starting with `//!` (for single-line comments)
11+
12+
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.
13+
14+
:::

‎packages/rolldown/src/options/docs/output-generated-code-profiler-names.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
::: warning Note
2+
3+
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.
4+
5+
Only enable this option when you specifically need better profiling support during development or debugging.
6+
7+
:::

‎packages/rolldown/src/options/input-options.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -364,8 +364,8 @@ export interface InputOptions {
364364
* - The conditions setting does not automatically include any platform-specific values.
365365
*
366366
* @default
367-
* - 'node' if the format is 'cjs'
368-
* - 'browser' for other formats
367+
* - `'node'` if the format is `'cjs'`
368+
* - `'browser'` for other formats
369369
* {@include ./docs/platform.md}
370370
*/
371371
platform?: 'node' | 'browser' | 'neutral';

‎packages/rolldown/src/options/output-options.ts‎

Lines changed: 58 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ export interface GeneratedCodeOptions {
2626
* }
2727
* };
2828
* ```
29+
*
30+
* @default 'es2015'
2931
*/
3032
preset?: GeneratedCodePreset;
3133
/**
@@ -34,9 +36,9 @@ export interface GeneratedCodeOptions {
3436
* When enabled, generated code will use descriptive variable names that correspond
3537
* to the original module names, making it easier to profile and debug the bundled code.
3638
*
37-
* Note: Enabling this option makes the output more difficult to minify effectively.
38-
*
3939
* @default false
40+
*
41+
* {@include ./docs/output-generated-code-profiler-names.md}
4042
*/
4143
profilerNames?: boolean;
4244
}
@@ -140,17 +142,18 @@ export interface OutputOptions {
140142
/**
141143
* Whether to generate sourcemaps.
142144
*
143-
* When `true`, a separate sourcemap file will be generated.
144-
* When `'inline'`, the sourcemap will be appended to the output file as a data URL.
145-
* When `'hidden'`, a separate sourcemap file will be generated, but the link to the sourcemap will not be included in the output file.
145+
* - `false`: No sourcemap will be generated.
146+
* - `true`: A separate sourcemap file will be generated.
147+
* - `'inline'`: The sourcemap will be appended to the output file as a data URL.
148+
* - `'hidden'`: A separate sourcemap file will be generated, but the link to the sourcemap (`//# sourceMappingURL` comment) will not be included in the output file.
146149
*
147150
* @default false
148151
*/
149152
sourcemap?: boolean | 'inline' | 'hidden';
150153
/**
151154
* The base URL for the links to the sourcemap file in the output file.
152155
*
153-
* By default, relative URLs are generated. If this option is set, an absolute URL with that base URL will be generated.
156+
* 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.
154157
*/
155158
sourcemapBaseUrl?: string;
156159
/**
@@ -196,18 +199,35 @@ export interface OutputOptions {
196199
sourcemapIgnoreList?: boolean | SourcemapIgnoreListOption | StringOrRegExp;
197200
/**
198201
* A transformation to apply to each path in a sourcemap.
202+
*
203+
* @example
204+
* ```js
205+
* export default defineConfig({
206+
* output: {
207+
* sourcemap: true,
208+
* sourcemapPathTransform: (source, sourcemapPath) => {
209+
* // Remove 'src/' prefix from all source paths
210+
* return source.replace(/^src\//, '');
211+
* },
212+
* },
213+
* });
214+
* ```
199215
*/
200216
sourcemapPathTransform?: SourcemapPathTransformOption;
201217
/**
202218
* A string to prepend to the bundle before `renderChunk` hook.
203219
*
204220
* See [`output.intro`](https://rolldown.rs/reference/OutputOptions.intro), [`output.postBanner`](https://rolldown.rs/reference/OutputOptions.postBanner) as well.
221+
*
222+
* {@include ./docs/output-banner.md}
205223
*/
206224
banner?: string | AddonFunction;
207225
/**
208226
* A string to append to the bundle before `renderChunk` hook.
209227
*
210228
* See [`output.outro`](https://rolldown.rs/reference/OutputOptions.outro), [`output.postFooter`](https://rolldown.rs/reference/OutputOptions.postFooter) as well.
229+
*
230+
* {@include ./docs/output-footer.md}
211231
*/
212232
footer?: string | AddonFunction;
213233
/**
@@ -267,6 +287,8 @@ export interface OutputOptions {
267287
* Forward slashes (`/`) can be used to place files in sub-directories.
268288
*
269289
* See also [`output.chunkFileNames`](https://rolldown.rs/reference/OutputOptions.chunkFileNames), [`output.entryFileNames`](https://rolldown.rs/reference/OutputOptions.entryFileNames).
290+
*
291+
* @default 'assets/[name]-[hash][extname]'
270292
*/
271293
assetFileNames?: string | AssetFileNamesFunction;
272294
/**
@@ -280,6 +302,8 @@ export interface OutputOptions {
280302
* 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.
281303
*
282304
* See also [`output.assetFileNames`](https://rolldown.rs/reference/OutputOptions.assetFileNames), [`output.chunkFileNames`](https://rolldown.rs/reference/OutputOptions.chunkFileNames).
305+
*
306+
* @default '[name].js'
283307
*/
284308
entryFileNames?: string | ChunkFileNamesFunction;
285309
/**
@@ -293,14 +317,18 @@ export interface OutputOptions {
293317
* Forward slashes (`/`) can be used to place files in sub-directories.
294318
*
295319
* See also [`output.assetFileNames`](https://rolldown.rs/reference/OutputOptions.assetFileNames), [`output.entryFileNames`](https://rolldown.rs/reference/OutputOptions.entryFileNames).
320+
*
321+
* @default '[name]-[hash].js'
296322
*/
297323
chunkFileNames?: string | ChunkFileNamesFunction;
298324
/**
325+
* @default '[name].css'
299326
* @experimental
300327
* @hidden not ready for public usage yet
301328
*/
302329
cssEntryFileNames?: string | ChunkFileNamesFunction;
303330
/**
331+
* @default '[name]-[hash].css'
304332
* @experimental
305333
* @hidden not ready for public usage yet
306334
*/
@@ -488,6 +516,25 @@ export interface OutputOptions {
488516
manualChunks?: ManualChunksFunction;
489517
/**
490518
* Allows you to do manual chunking. For deeper understanding, please refer to the in-depth [documentation](https://rolldown.rs/in-depth/advanced-chunks).
519+
*
520+
* @example
521+
* **Basic vendor chunk**
522+
* ```js
523+
* export default defineConfig({
524+
* output: {
525+
* advancedChunks: {
526+
* minSize: 20000,
527+
* groups: [
528+
* {
529+
* name: 'vendor',
530+
* test: /node_modules/,
531+
* },
532+
* ],
533+
* },
534+
* },
535+
* });
536+
* ```
537+
* {@include ./docs/output-advanced-chunks.md}
491538
*/
492539
advancedChunks?: {
493540
/**
@@ -594,6 +641,8 @@ export interface OutputOptions {
594641
* Clean output directory ([`output.dir`](https://rolldown.rs/reference/OutputOptions.dir)) before emitting output.
595642
*
596643
* @default false
644+
*
645+
* {@include ./docs/output-clean-dir.md}
597646
*/
598647
cleanDir?: boolean;
599648
/**
@@ -680,8 +729,7 @@ export type AdvancedChunksGroup = {
680729
*
681730
* If two groups have the same priority, the group whose index is smaller will be chosen.
682731
*
683-
* For example,
684-
*
732+
* @example
685733
* ```js
686734
* import { defineConfig } from 'rolldown';
687735
*
@@ -691,19 +739,17 @@ export type AdvancedChunksGroup = {
691739
* {
692740
* name: 'react',
693741
* test: /node_modules[\\/]react/,
694-
* priority: 1,
742+
* priority: 2,
695743
* },
696744
* {
697745
* name: 'other-libs',
698746
* test: /node_modules/,
699-
* priority: 2,
747+
* priority: 1,
700748
* },
701749
* ],
702750
* });
703751
* ```
704752
*
705-
* 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.
706-
*
707753
* @default 0
708754
*/
709755
priority?: number;

0 commit comments

Comments
 (0)