1.0 changes

[guybedford]

This PR is considered to be release candidate status and can be tested by installing rollup via

npm install rollup/rollup#1.0

List of Breaking Changes

• All deprecated options that have previously caused warnings have been removed:
  • transform, load, resolveId, resolveExternal (note that the corresponding plugin hooks still exist): use the plugin API
  • entry: use input
  • dest: use output.file
  • moduleName: use output.name
  • name: use output.name
  • extend: use output.extend
  • globals: use output.globals
  • indent: use output.indent
  • noConflict: use output.noConflict
  • paths: use output.paths
  • sourcemap: use output.sourcemap
  • sourceMap: use output.sourcemap
  • sourceMapFile: use output.sourcemapFile
  • useStrict: use output.strict
  • strict: use output.strict
  • format: use output.format
  • banner: use output.banner
  • footer: use output.footer
  • intro: use output.intro
  • outro: use output.outro
  • interop: use output.interop
  • freeze: use output.freeze
  • exports: use output.exports
  • targets: use output as an array
  • pureExternalModules: use treeshake.pureExternalModules
  • output.moduleId: use output.amd.id
• When using the JavaScript API, bundle.generate and bundle.write now return a new format:

  {
    output: [
      {
        // both chunks and assets
        isAsset: boolean,
        fileName: string,
  
        // assets only
        source: string | Buffer,
  
        // chunks only
        code: string,
        map?: SourceMap,
        isEntry: boolean,
        imports: string[],
        exports: string[],
        modules: {
          [moduleId]: {
            renderedExports: string[],
            removedExports: string[],
            renderedLength: string,
            originalLength: string,
          },
          ...
        }
      },
      ...
    ]
  }
  

• Using dynamic import(...) will now by default create a new chunk unless inlineDynamicImports is set to true
• the following experimental options have been removed because they are considered to be always on now:
  • experimentalCodeSplitting
  • experimentalDynamicImport
• the experimentalPreserveModules option has been renamed preserveModules
• accessing this.watcher on the plugin context is still possible but considered deprecated and will cause a warning: use watchChange instead
• the following plugin hooks still work but are considered deprecated and will cause warnings:
  • transformBundle: use renderChunk
  • transformChunk: use renderChunk
  • ongenerate: use generateBundle
  • onwrite: use generateBundle
• Rollup is now using acorn@6 which means that only acorn@6-compatible plugins can be used

Original PR Description

This is a candidate PR for the 1.0 branch which represents the breaking API changes for the 1.0 release. All current deprecations are maintained to make the breaks of this upgrade path as minimal as possible, rather the deprecations for things like entry and onwrite can happen in a later major. In terms of release process there is a lot more than just these API changes as well for a 1.0, so I hope we can continue the wider discussions elsewhere too.

Update: This PR now also includes all deprecations from #2409.

Removing experimental flags

The breaking changes here are enabling experimentalCodeSplitting on by default, renaming experimentalPreserveModules to preserveModules, and applying the API changes to allow for a single consistent API between single-file builds and code splitting builds.

We do this by firstly allowing the input to always be used interchangeably as a string, array or object and there are no "special case" concerns - all input types are treated the same.

The defaults and validations have been updated to reflect this while allowing the most flexibility:

• By default inlineDynamicImports is now set to false. Combined with asset emission, this means that all builds now have the possibility of outputting multiple output files.
• If there is only a single output chunk, output.file will continue to work fine.
• If there is ever more than one output chunk for whatever reason, the build will throw an error that output.dir is needed.
• If using output.dir for a single file build, this works fine too.

CLI changes

The CLI has been updated to support multiple output files for stdout, providing file name headers in colour, something like:

$ ./bin/rollup test.js dep.js -f es

test.js, dep.js → stdout...

test.js:
import("./dep.js").then(x => console.log(x));

dep.js:
var dep = 42;
export default dep;
created stdout in 43ms

where ./bin/rollup -i test.js -i dep.js -f es would provide the same output.

API Changes

The API has been updated along the following lines:

const build = await rollup.rollup({
  input: ['main1', 'main2']
});

// these have been deprecated:
build.modules // undefined
build.imports // undefined
build.exports // undefined

// output is now an object on the result of generate
// this was to support possible additional result values in future
const { output } = await build.generate(outputOptions);

// output is an array of output files (chunks and assets)
console.log(output[0].fileName)
console.log(output[0].code)

The main new change here is that the output is an Array of OutputChunk | OutputAsset, where each will have a fileName property. Previously this was an object record keyed by fileName to the chunk or asset. The reason for this is that when running single-file builds, output[0] is much easier to write than to try and somehow iterate the single fileName property from an object.

In addition the output array is carefully ordered - entry points, then common chunks, then assets. output[0] will always correspond to the first input etc in order. Even asset order is maintained to match order of emission.

Questions

While the main API changes are likely roughly in place, this is very much open to discussion and feedback, and then it would be worth keeping this open for a while to test out these changes against the ecosystem before rushing out the release candidate.

Some open-ended ideas of where this API may be inconsistent currently, and some other things that could be possible:

• It might be seen as a bit inconsistent that we still maintain an object form of the output files keyed by fileName, which is also passed to generateBundle, which is permitted to make modifications. But this still seems part of the flexibility of that hook.
• We could possibly provide result.entries, result.chunks and results.assets as separate arrays instead of a single combined result.output array. Currently for filtering we have isAsset on assets and and isEntry on chunks to make these distinctions.
• Assets provide a .source property, while chunks provide a .code property. Previously assets were direct Buffer or string objects in the record, but now they need their own interfaces. It may be inconsistent to use separate properties here.
• Having removed the .modules etc stuff from the rollup.rollup build return, there could still be a space here for the graph metadata to be reported before the output.
• It's a good time now to consider what other deprecation warnings we should add to this release - eg warning for using the onwrite or ongenerate plugin hooks. Alternatively it may make sense to wait until enough of the plugin ecosystem has upgraded to avoid noise too.

[TrySound]

Maybe force migrating to esm instead of es for 1.0?

[guybedford]

I'm also wondering if we should deprecate automatic ".js" extension adding to be put behind an option flag for this release.

[TrySound]

I think extension resolving should be handled only on node resolve plugin side

[guybedford]

@TrySound automatic extension adding is even debatable still for the Node es modules resolution :)

[lukastaegert]

One thing I noticed is that when the file option is given, no error occurs but the outputs simply overwrite each other in the following situations:

• multiple inputs are provided, or
• preserveModules is used.

I would expect the process to abort with an error, if the file option is provided and:

• More than one input is provided (one input in array form should be ok, though)
• The object form of the input is provided: If you use the object form, then you probably want to name your chunk, even if it is only a single one; subject to be discussed, though
• preserveModules is used

A lot more checking to be done by me, though...

[shellscape]

In addition the output array is carefully ordered - entry points, then common chunks, then assets. output[0] will always correspond to the first input etc in order. Even asset order is maintained to match order of emission.

I can dig this. Has any thought been given to convenience methods to iterate over different types? Something along the type of what you'd find in an AST tree or PostCSS. output.walkAssets or similar. Might be overkill, but quick and easy iteration would allow for easy reporter custom creation.

We could possibly provide result.entries, result.chunks and results.assets as separate arrays

Would probably make the previous question moot. Instead of separate arrays, I'd recommend readonly properties that produced an array for each on-demand.

Regarding the hook changes; it seems perfectly reasonable. I do still have some catching up to do so take that for what it's worth coming from a very green third party perspective.