diff --git a/docs/02-javascript-api.md b/docs/02-javascript-api.md index aa70f6707ab..86b4b6fa77f 100755 --- a/docs/02-javascript-api.md +++ b/docs/02-javascript-api.md @@ -66,7 +66,7 @@ async function build() { build(); ``` -#### inputOptions +#### inputOptions object The `inputOptions` object can contain the following properties (see the [big list of options](guide/en#big-list-of-options) for full details on these): @@ -103,7 +103,7 @@ const inputOptions = { }; ``` -#### outputOptions +#### outputOptions object The `outputOptions` object can contain the following properties (see the [big list of options](guide/en#big-list-of-options) for full details on these): diff --git a/docs/04-tutorial.md b/docs/04-tutorial.md index 4b04435e53c..697b0e2f102 100755 --- a/docs/04-tutorial.md +++ b/docs/04-tutorial.md @@ -215,7 +215,7 @@ Rollup will use the dynamic import to create a separate chunk that is only loade rollup src/main.js -f cjs -d dist ``` -This will create a folder `dist` containing two files, `main.js` and `chunk-[hash].js`, where `[hash]` is a content based hash string. You can supply your own naming patterns by specifying the [`output.chunkFileNames`](guide/en#output-chunkfilenames) and [`output.entryFileNames`](guide/en#output-entryfilenames) options. +This will create a folder `dist` containing two files, `main.js` and `chunk-[hash].js`, where `[hash]` is a content based hash string. You can supply your own naming patterns by specifying the [`output.chunkFileNames`](guide/en#outputchunkfilenames) and [`output.entryFileNames`](guide/en#outputentryfilenames) options. You can still run your code as before with the same output, albeit a little slower as loading and parsing of `./foo.js` will only commence once we call the exported function for the first time. diff --git a/docs/05-plugins.md b/docs/05-plugin-development.md similarity index 91% rename from docs/05-plugins.md rename to docs/05-plugin-development.md index 3533f34b45c..62f1a882ed7 100644 --- a/docs/05-plugins.md +++ b/docs/05-plugin-development.md @@ -1,5 +1,5 @@ --- -title: Plugins +title: Plugin Development --- ### Plugins Overview @@ -76,7 +76,7 @@ In addition to properties defining the identity of your plugin, you may also spe Type: `string | (() => string)`
Kind: `async, parallel` -Cf. [`output.banner/output.footer`](guide/en#output-banner-output-footer). +Cf. [`output.banner/output.footer`](guide/en#outputbanneroutputfooter). #### `buildEnd` Type: `(error?: Error) => void`
@@ -94,7 +94,7 @@ Called on each `rollup.rollup` build. Type: `string | (() => string)`
Kind: `async, parallel` -Cf. [`output.banner/output.footer`](guide/en#output-banner-output-footer). +Cf. [`output.banner/output.footer`](guide/en#outputbanneroutputfooter). #### `generateBundle` Type: `(options: OutputOptions, bundle: { [fileName: string]: AssetInfo | ChunkInfo }, isWrite: boolean) => void`
@@ -137,7 +137,7 @@ Called at the end of `bundle.generate()` or immediately before the files are wri Type: `string | (() => string)`
Kind: `async, parallel` -Cf. [`output.intro/output.outro`](guide/en#output-intro-output-outro). +Cf. [`output.intro/output.outro`](guide/en#outputintrooutputoutro). #### `load` Type: `(id: string) => string | null | { code: string, map?: string | SourceMap, ast? : ESTree.Program, moduleSideEffects?: boolean | null }`
@@ -147,7 +147,7 @@ Defines a custom loader. Returning `null` defers to other `load` functions (and If `false` is returned for `moduleSideEffects` and no other module imports anything from this module, then this module will not be included in the bundle without checking for actual side-effects inside the module. If `true` is returned, Rollup will use its default algorithm to include all statements in the module that have side-effects (such as modifying a global or exported variable). If `null` is returned or the flag is omitted, then `moduleSideEffects` will be determined by the first `resolveId` hook that resolved this module, the `treeshake.moduleSideEffects` option, or eventually default to `true`. The `transform` hook can override this. -You can use [`this.getModuleInfo`](guide/en#this-getmoduleinfo-moduleid-string-moduleinfo) to find out the previous value of `moduleSideEffects` inside this hook. +You can use [`this.getModuleInfo`](guide/en#thisgetmoduleinfomoduleid-string--moduleinfo) to find out the previous value of `moduleSideEffects` inside this hook. #### `options` Type: `(options: InputOptions) => InputOptions | null`
@@ -165,7 +165,7 @@ Reads and replaces or manipulates the output options object passed to `bundle.ge Type: `string | (() => string)`
Kind: `async, parallel` -Cf. [`output.intro/output.outro`](guide/en#output-intro-output-outro). +Cf. [`output.intro/output.outro`](guide/en#outputintrooutputoutro). #### `renderChunk` Type: `(code: string, chunk: ChunkInfo, options: OutputOptions) => string | { code: string, map: SourceMap } | null`
@@ -198,7 +198,7 @@ In case a dynamic import is not passed a string as argument, this hook gets acce - If a string is returned, this string is *not* interpreted as a module id but is instead used as a replacement for the import argument. It is the responsibility of the plugin to make sure the generated code is valid. - To resolve such an import to an existing module, you can still return an object `{id, external}`. -Note that the return value of this hook will not be passed to `resolveId` afterwards; if you need access to the static resolution algorithm, you can use [`this.resolve(source, importer)`](guide/en#this-resolve-source-string-importer-string-promise-id-string-external-boolean-null) on the plugin context. +Note that the return value of this hook will not be passed to `resolveId` afterwards; if you need access to the static resolution algorithm, you can use [`this.resolve(source, importer)`](guide/en#thisresolvesource-string-importer-string-options-skipself-boolean--promiseid-string-external-boolean--null) on the plugin context. #### `resolveFileUrl` Type: `({assetReferenceId: string | null, chunkId: string, chunkReferenceId: string | null, fileName: string, format: string, moduleId: string, relativePath: string}) => string | null`
@@ -280,7 +280,7 @@ Note that in watch mode, the result of this hook is cached when rebuilding and t If `false` is returned for `moduleSideEffects` and no other module imports anything from this module, then this module will not be included without checking for actual side-effects inside the module. If `true` is returned, Rollup will use its default algorithm to include all statements in the module that have side-effects (such as modifying a global or exported variable). If `null` is returned or the flag is omitted, then `moduleSideEffects` will be determined by the first `resolveId` hook that resolved this module, the `treeshake.moduleSideEffects` option, or eventually default to `true`. -You can use [`this.getModuleInfo`](guide/en#this-getmoduleinfo-moduleid-string-moduleinfo) to find out the previous value of `moduleSideEffects` inside this hook. +You can use [`this.getModuleInfo`](guide/en#thisgetmoduleinfomoduleid-string--moduleinfo) to find out the previous value of `moduleSideEffects` inside this hook. #### `watchChange` Type: `(id: string) => void`
@@ -329,19 +329,19 @@ In general, it is recommended to use `this.addWatchfile` from within the hook th #### `this.emitAsset(assetName: string, source: string) => string` -Emits a custom file that is included in the build output, returning an `assetReferenceId` that can be used to reference the emitted file. You can defer setting the source if you provide it later via [`this.setAssetSource(assetReferenceId, source)`](guide/en#this-setassetsource-assetreferenceid-string-source-string-buffer-void). A string or Buffer source must be set for each asset through either method or an error will be thrown on generate completion. +Emits a custom file that is included in the build output, returning an `assetReferenceId` that can be used to reference the emitted file. You can defer setting the source if you provide it later via [`this.setAssetSource(assetReferenceId, source)`](guide/en#thissetassetsourceassetreferenceid-string-source-string--buffer--void). A string or Buffer source must be set for each asset through either method or an error will be thrown on generate completion. -Emitted assets will follow the [`output.assetFileNames`](guide/en#output-assetfilenames) naming scheme. You can reference the URL of the file in any code returned by a [`load`](guide/en#load) or [`transform`](guide/en#transform) plugin hook via `import.meta.ROLLUP_ASSET_URL_assetReferenceId`. See [Asset URLs](guide/en#asset-urls) for more details and an example. +Emitted assets will follow the [`output.assetFileNames`](guide/en#outputassetfilenames) naming scheme. You can reference the URL of the file in any code returned by a [`load`](guide/en#load) or [`transform`](guide/en#transform) plugin hook via `import.meta.ROLLUP_ASSET_URL_assetReferenceId`. See [Asset URLs](guide/en#asset-urls) for more details and an example. -The generated code that replaces `import.meta.ROLLUP_ASSET_URL_assetReferenceId` can be customized via the [`resolveFileUrl`](guide/en#resolvefileurl) plugin hook. Once the asset has been finalized during `generate`, you can also use [`this.getAssetFileName(assetReferenceId)`](guide/en#this-getassetfilename-assetreferenceid-string-string) to determine the file name. +The generated code that replaces `import.meta.ROLLUP_ASSET_URL_assetReferenceId` can be customized via the [`resolveFileUrl`](guide/en#resolvefileurl) plugin hook. Once the asset has been finalized during `generate`, you can also use [`this.getAssetFileName(assetReferenceId)`](guide/en#thisgetassetfilenameassetreferenceid-string--string) to determine the file name. #### `this.emitChunk(moduleId: string, options?: {name?: string}) => string` Emits a new chunk with the given module as entry point. This will not result in duplicate modules in the graph, instead if necessary, existing chunks will be split. It returns a `chunkReferenceId` that can be used to later access the generated file name of the chunk. -Emitted chunks will follow the [`output.chunkFileNames`](guide/en#output-chunkfilenames), [`output.entryFileNames`](guide/en#output-entryfilenames) naming scheme. If a `name` is provided, this will be used for the `[name]` file name placeholder, otherwise the name will be derived from the file name. If a `name` is provided, this name must not conflict with any other entry point names unless the entry points reference the same entry module. You can reference the URL of the emitted chunk in any code returned by a [`load`](guide/en#load) or [`transform`](guide/en#transform) plugin hook via `import.meta.ROLLUP_CHUNK_URL_chunkReferenceId`. +Emitted chunks will follow the [`output.chunkFileNames`](guide/en#outputchunkfilenames), [`output.entryFileNames`](guide/en#outputentryfilenames) naming scheme. If a `name` is provided, this will be used for the `[name]` file name placeholder, otherwise the name will be derived from the file name. If a `name` is provided, this name must not conflict with any other entry point names unless the entry points reference the same entry module. You can reference the URL of the emitted chunk in any code returned by a [`load`](guide/en#load) or [`transform`](guide/en#transform) plugin hook via `import.meta.ROLLUP_CHUNK_URL_chunkReferenceId`. -The generated code that replaces `import.meta.ROLLUP_CHUNK_URL_chunkReferenceId` can be customized via the [`resolveFileUrl`](guide/en#resolvefileurl) plugin hook. Once the chunk has been rendered during `generate`, you can also use [`this.getChunkFileName(chunkReferenceId)`](guide/en#this-getchunkfilename-chunkreferenceid-string-string) to determine the file name. +The generated code that replaces `import.meta.ROLLUP_CHUNK_URL_chunkReferenceId` can be customized via the [`resolveFileUrl`](guide/en#resolvefileurl) plugin hook. Once the chunk has been rendered during `generate`, you can also use [`this.getChunkFileName(chunkReferenceId)`](guide/en#thisgetchunkfilenamechunkreferenceid-string--string) to determine the file name. #### `this.error(error: string | Error, position?: number) => void` @@ -418,9 +418,9 @@ The `position` argument is a character index where the warning was raised. If pr ☢️ These context utility functions have been deprecated and may be removed in a future Rollup version. -- `this.isExternal(id: string, importer: string, isResolved: boolean): boolean` - _**Use [`this.resolve`](guide/en#this-resolve-source-string-importer-string-promise-id-string-external-boolean-null)**_ - Determine if a given module ID is external when imported by `importer`. When `isResolved` is false, Rollup will try to resolve the id before testing if it is external. +- `this.isExternal(id: string, importer: string, isResolved: boolean): boolean` - _**Use [`this.resolve`](guide/en#thisresolvesource-string-importer-string-options-skipself-boolean--promiseid-string-external-boolean--null)**_ - Determine if a given module ID is external when imported by `importer`. When `isResolved` is false, Rollup will try to resolve the id before testing if it is external. -- `this.resolveId(source: string, importer: string) => Promise` - _**Use [`this.resolve`](guide/en#this-resolve-source-string-importer-string-promise-id-string-external-boolean-null)**_ - Resolve imports to module ids (i.e. file names) using the same plugins that Rollup uses. Returns `null` if an id cannot be resolved. +- `this.resolveId(source: string, importer: string) => Promise` - _**Use [`this.resolve`](guide/en#thisresolvesource-string-importer-string-options-skipself-boolean--promiseid-string-external-boolean--null)**_ - Resolve imports to module ids (i.e. file names) using the same plugins that Rollup uses. Returns `null` if an id cannot be resolved. ### Asset URLs diff --git a/docs/999-big-list-of-options.md b/docs/999-big-list-of-options.md index 6484f9269b5..e811ffe7cc8 100755 --- a/docs/999-big-list-of-options.md +++ b/docs/999-big-list-of-options.md @@ -69,7 +69,7 @@ The conversion back to a relative import is done as if `output.file` or `output. Type: `string | string [] | { [entryName: string]: string }`
CLI: `-i`/`--input ` -The bundle's entry point(s) (e.g. your `main.js` or `app.js` or `index.js`). If you provide an array of entry points or an object mapping names to entry points, they will be bundled to separate output chunks. Unless the [`output.file`](guide/en#output-file) option is used, generated chunk names will follow the [`output.entryFileNames`](guide/en#output-entryfilenames) option. When using the object form, the `[name]` portion of the file name will be the name of the object property while for the array form, it will be the file name of the entry point. +The bundle's entry point(s) (e.g. your `main.js` or `app.js` or `index.js`). If you provide an array of entry points or an object mapping names to entry points, they will be bundled to separate output chunks. Unless the [`output.file`](guide/en#outputfile) option is used, generated chunk names will follow the [`output.entryFileNames`](guide/en#outputentryfilenames) option. When using the object form, the `[name]` portion of the file name will be the name of the object property while for the array form, it will be the file name of the entry point. Note that it is possible when using the object form to put entry points into different sub-folders by adding a `/` to the name. The following will generate at least two entry chunks with the names `entry-a.js` and `entry-b/index.js`, i.e. the file `index.js` is placed in the folder `entry-b`: @@ -229,7 +229,7 @@ this.a.b.c = ... #### plugins Type: `Plugin | (Plugin | void)[]` -See [Using plugins](guide/en#using-plugins) for more information on how to use plugins and [Plugins](guide/en#plugins) on how to write your own (try it out, it's not as difficult as it may sound and very much extends what you can do with Rollup!). For plugins imported from packages, remember to call the imported plugin function (i.e. `commonjs()`, not just `commonjs`). Falsy plugins will be ignored, which can be used to easily activate or deactivate plugins. +See [Using plugins](guide/en#using-plugins) for more information on how to use plugins and [Plugins](guide/en#plugin-development) on how to write your own (try it out, it's not as difficult as it may sound and very much extends what you can do with Rollup!). For plugins imported from packages, remember to call the imported plugin function (i.e. `commonjs()`, not just `commonjs`). Falsy plugins will be ignored, which can be used to easily activate or deactivate plugins. ```js // rollup.config.js @@ -367,7 +367,7 @@ The pattern to use for naming custom emitted assets to include in the build outp * `[hash]`: A hash based on the name and content of the asset. * `[name]`: The file name of the asset excluding any extension. -Forward slashes `/` can be used to place files in sub-directories. See also `[`output.chunkFileNames`](guide/en#output-chunkfilenames)`, [`output.entryFileNames`](guide/en#output-entryfilenames). +Forward slashes `/` can be used to place files in sub-directories. See also `[`output.chunkFileNames`](guide/en#outputchunkfilenames)`, [`output.entryFileNames`](guide/en#outputentryfilenames). #### output.banner/output.footer Type: `string | (() => string | Promise)`
@@ -387,7 +387,7 @@ export default { }; ``` -See also [`output.intro/output.outro`](guide/en#output-intro-output-outro). +See also [`output.intro/output.outro`](guide/en#outputintrooutputoutro). #### output.chunkFileNames Type: `string`
@@ -399,7 +399,7 @@ The pattern to use for naming shared chunks created when code-splitting. Pattern * `[hash]`: A hash based on the content of the chunk and the content of all its dependencies. * `[name]`: The name of the chunk. This will be `chunk` unless the chunk was created via the [`manualChunks`](guide/en#manualchunks) options. -Forward slashes `/` can be used to place files in sub-directories. See also [`output.assetFileNames`](guide/en#output-assetfilenames), [`output.entryFileNames`](guide/en#output-entryfilenames). +Forward slashes `/` can be used to place files in sub-directories. See also [`output.assetFileNames`](guide/en#outputassetfilenames), [`output.entryFileNames`](guide/en#outputentryfilenames). #### output.compact Type: `boolean`
@@ -418,7 +418,7 @@ The pattern to use for chunks created from entry points. Pattern supports the fo * `[hash]`: A hash based on the content of the entry point and the content of all its dependencies. * `[name]`: The file name (without extension) of the entry point. -Forward slashes `/` can be used to place files in sub-directories. See also [`output.assetFileNames`](guide/en#output-assetfilenames), [`output.chunkFileNames`](guide/en#output-chunkfilenames). +Forward slashes `/` can be used to place files in sub-directories. See also [`output.assetFileNames`](guide/en#outputassetfilenames), [`output.chunkFileNames`](guide/en#outputchunkfilenames). #### output.extend Type: `boolean`
@@ -438,7 +438,7 @@ Whether or not to add an 'interop block'. By default (`interop: true`), for safe Type: `string | (() => string | Promise)`
CLI: `--intro`/`--outro ` -Similar to [`output.banner/output.footer`](guide/en#output-banner-output-footer), except that the code goes *inside* any format-specific wrapper. +Similar to [`output.banner/output.footer`](guide/en#outputbanneroutputfooter), except that the code goes *inside* any format-specific wrapper. ```js export default { @@ -531,7 +531,7 @@ Type: `boolean`
CLI: `--preserveModules`/`--no-preserveModules`
Default: `false` -Instead of creating as few chunks as possible, this mode will create separate chunks for all modules using the original module names as file names. Requires the [`output.dir`](guide/en#output-dir) option. Tree-shaking will still be applied, suppressing files that are not used by the provided entry points or do not have side-effects when executed. This mode can be used to transform a file structure to a different module format. +Instead of creating as few chunks as possible, this mode will create separate chunks for all modules using the original module names as file names. Requires the [`output.dir`](guide/en#outputdir) option. Tree-shaking will still be applied, suppressing files that are not used by the provided entry points or do not have side-effects when executed. This mode can be used to transform a file structure to a different module format. #### strictDeprecations Type: `boolean`