From a7ee87a90ea99e37a22938ab4448fd5d35526974 Mon Sep 17 00:00:00 2001 From: Lukas Taegert-Atkinson Date: Thu, 20 Dec 2018 19:12:40 +0100 Subject: [PATCH] Update docs for latest rollup 0.x --- CHANGELOG.md | 4 +-- docs/01-command-line-reference.md | 2 +- docs/02-javascript-api.md | 23 +++++++++++-- docs/05-plugins.md | 54 ++++++++++++++++++++++--------- docs/999-big-list-of-options.md | 14 ++++++-- 5 files changed, 74 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7c89a860b09..1add0705596 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,7 +13,7 @@ *2018-12-16* ### Breaking Changes -* `optimizeImports` is renamed to `experimentalOptimizeImports` to reflect this feature is not production-ready yet (#2575) +* `optimizeChunks` is renamed to `experimentalOptimizeChunks` to reflect this feature is not production-ready yet (#2575) ### Features * Plugins can iterate all module ids via `this.moduleIds` (#2565) @@ -42,7 +42,7 @@ ### Pull Requests * [#2565](https://github.com/rollup/rollup/pull/2565): Provide module graph information on the plugin context (@samccone) -* [#2575](https://github.com/rollup/rollup/pull/2575): Extend bundle information, tree-shake dynamic imports, fix dynamic import facade creation, support manual chunks with multiple entry points, make `optimizeImports` experimental (@lukastaegert) +* [#2575](https://github.com/rollup/rollup/pull/2575): Extend bundle information, tree-shake dynamic imports, fix dynamic import facade creation, support manual chunks with multiple entry points, make `optimizeChunks` experimental (@lukastaegert) * [#2577](https://github.com/rollup/rollup/pull/2577): Update dependencies (@lukastaegert) * [#2584](https://github.com/rollup/rollup/pull/2584): Prune tree-shaken chunk imports, fix missing export shimming, support dynamic namespaces when preserving modules, improve chunk execution order (@lukastaegert) * [#2587](https://github.com/rollup/rollup/pull/2587): Support exports using destructuring declarations and assignments in SystemJS (@lukastaegert) diff --git a/docs/01-command-line-reference.md b/docs/01-command-line-reference.md index ba3bd8b4991..4f12be99a14 100755 --- a/docs/01-command-line-reference.md +++ b/docs/01-command-line-reference.md @@ -49,7 +49,7 @@ export default { // can be an array (for multiple inputs) // experimental experimentalCodeSplitting, manualChunks, - optimizeChunks, + experimentalOptimizeChunks, chunkGroupingSize, output: { // required (can be an array, for multiple outputs) diff --git a/docs/02-javascript-api.md b/docs/02-javascript-api.md index 048753fb2aa..add5d651852 100755 --- a/docs/02-javascript-api.md +++ b/docs/02-javascript-api.md @@ -24,7 +24,26 @@ async function build() { console.log(bundle.modules); // an array of module objects // generate code and a sourcemap - const { code, map } = await bundle.generate(outputOptions); + const output = await bundle.generate(outputOptions); + + // output contains the following information about the generated bundle: + // { + // code: string, // the generated JS code + // map: string | null, // sourcemaps if present + // dynamicImports: string[], // external modules imported dynamically by the bundle + // exports: string[], // exported variable names + // fileName: string, // the generated bundle file name + // imports: string[], // external modules imported statically by the bundle + // modules: { // a list of all modules in the bundle with tree-shaking statistics + // [id: string]: { + // renderedExports: string[]; + // removedExports: string[]; + // renderedLength: number; + // originalLength: number; + // }; + // } + // } + console.log(output); // or write the bundle to disk await bundle.write(outputOptions); @@ -60,7 +79,7 @@ const inputOptions = { // experimental experimentalCodeSplitting, manualChunks, - optimizeChunks, + experimentalOptimizeChunks, chunkGroupingSize }; ``` diff --git a/docs/05-plugins.md b/docs/05-plugins.md index 616cd12f203..b1e8a0bd50f 100644 --- a/docs/05-plugins.md +++ b/docs/05-plugins.md @@ -63,21 +63,15 @@ Type: `String` The name of the plugin, for use in error messages and warnings. -#### `banner` -Type: `String|Function` - -A `String`, or a `Function` that returns a `String` or `Promise`. - -#### `options` -Type: `Function`
-Signature: `( inputOptions ) => options` - -Replaces or manipulates the options object passed to `rollup.rollup`. Returning `null` does not replace anything. - ### Hooks In addition to properties defining the identity of your plugin, you may also specify properties that correspond to available build hooks. Hooks can affect how a build is run, provide information about a build, or modify a build once complete. +#### `banner` +Type: `String|Function` + +A `String`, or a `Function` that returns a `String` or `Promise`. Cf. [output.banner/output.footer](output-banner-output-footer-banner-footer). + #### `buildEnd` Type: `Function`
Signature: `( error ) => void` @@ -93,7 +87,7 @@ Called on each `rollup.rollup` build. #### `footer` Type: `String|Function` -A `String`, or a `Function` that returns a `String` or `Promise`. +A `String`, or a `Function` that returns a `String` or `Promise`. Cf. [output.banner/output.footer](output-banner-output-footer-banner-footer). #### `generateBundle` Type: `Function`
@@ -104,7 +98,7 @@ Called at the end of `bundle.generate()` or `bundle.write()`. `bundle` provides #### `intro` Type: `String|Function` -A `String`, or a `Function` that returns a `String` or `Promise`. +A `String`, or a `Function` that returns a `String` or `Promise`. Cf. [output.intro/output.outro](output-intro-output-outro-intro-outro). #### `load` Type: `Function`
@@ -112,10 +106,16 @@ Signature: `( id ) => (code | { code, map } | Promise)` Defines a custom loader. Returning `null` defers to other `load` functions (and eventually the default behavior of loading from the file system). +#### `options` +Type: `Function`
+Signature: `( inputOptions ) => options` + +Reads and replaces or manipulates the options object passed to `rollup.rollup`. Returning `null` does not replace anything. + #### `outro` Type: `String|Function` -A `String`, or a `Function` that returns a `String` or `Promise`. +A `String`, or a `Function` that returns a `String` or `Promise`. Cf. [output.intro/output.outro](output-intro-output-outro-intro-outro). #### `renderChunk` Type: `Function`
@@ -188,6 +188,20 @@ Structurally equivalent to `this.warn`, except that it will also abort the bundl Get the file name of an asset, according to the `assetFileNames` output option pattern. +#### `this.getModuleInfo( moduleId )` + +Returns additional information about the module in question in the form + +```js +{ + id, // the id of the module, for convenience + isExternal, // for external modules that are not included in the graph + importedIds // the module ids imported by this module +} +``` + +If the module id cannot be found, an error is thrown. + #### `this.isExternal( id, parentId, isResolved )` Determine if a given module ID is external. @@ -197,11 +211,21 @@ Determine if a given module ID is external. An `Object` containing potentially useful Rollup metadata. eg. `this.meta.rollupVersion` +#### `this.moduleIds` + +An `Iterator` that gives access to all module ids in the current graph. It can be iterated via + +```js +for (const moduleId of this.moduleIds) { /* ... */ } +``` + +or converted into an Array via `Array.from(this.moduleIds)`. + #### `this.parse( code, acornOptions )` Use Rollup's internal acorn instance to parse code to an AST. -#### `this.resolveId(importee, importer)` +#### `this.resolveId( importee, importer )` Resolve imports to module ids (i.e. file names). Uses the same hooks as Rollup itself. diff --git a/docs/999-big-list-of-options.md b/docs/999-big-list-of-options.md index a3fc23c2528..531737db16b 100755 --- a/docs/999-big-list-of-options.md +++ b/docs/999-big-list-of-options.md @@ -59,18 +59,22 @@ this.a.b.c = ... #### plugins -`Array` of plugin objects (or a single plugin object) – see [Using plugins](guide/en#using-plugins) for more information. Remember to call the imported plugin function (i.e. `commonjs()`, not just `commonjs`). +`Array` of plugin objects (or a single plugin object) – see [Using plugins](guide/en#using-plugins) for more information. 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 import resolve from 'rollup-plugin-node-resolve'; import commonjs from 'rollup-plugin-commonjs'; +import {terser} from 'rollup-plugin-terser'; + +const isProduction = process.env.NODE_ENV === 'production'; export default { entry: 'main.js', plugins: [ resolve(), - commonjs() + commonjs(), + isProduction && terser() ] }; ``` @@ -304,6 +308,10 @@ If `true`, a separate sourcemap file will be created. If `inline`, the sourcemap `sourcemapFile` is not required if `output` is specified, in which case an output filename will be inferred by adding ".map" to the output filename for the bundle. +#### output.sourcemapExcludeSources *`--sourcemapExcludeSources`* + +`true` or `false` (defaults to `false`) – if `true`, the actual sources will not be added to the sourcemaps making them considerably smaller. + #### output.sourcemapPathTransform `Function` A transformation to apply to each path in a sourcemap. For instance the following will change all paths to be relative to the `src` directory. @@ -555,7 +563,7 @@ These options reflect new features that have not yet been fully finalized. Speci #### inlineDynamicImports *`--inlineDynamicImports`* `true` or `false` (defaults to `false)` - will inline dynamic imports instead of creating new chunks when code-splitting is enabled. Only possible if a single input is provided. -#### optimizeChunks *`--optimizeChunks`* +#### experimentalOptimizeChunks *`--experimentalOptimizeChunks`* `true` or `false` (defaults to `false)` - experimental feature to optimize chunk groupings. When a large number of chunks are generated in code-splitting, this allows smaller chunks to group together as long as they are within the `chunkGroupingSize` limit. It results in unnecessary code being loaded in some cases in order to have a smaller number of chunks overall. Disabled by default as it may cause unwanted side effects when loading unexpected code.