New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

1.0 changes #2293

Merged
merged 20 commits into from Dec 28, 2018

Conversation

Projects
6 participants
@guybedford
Copy link
Contributor

guybedford commented Jun 21, 2018

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

This comment has been minimized.

Copy link
Member

TrySound commented Jun 21, 2018

Maybe force migrating to esm instead of es for 1.0?

@guybedford guybedford force-pushed the 1.0 branch 2 times, most recently from ae13e77 to f2508d8 Jun 23, 2018

@guybedford

This comment has been minimized.

Copy link
Contributor

guybedford commented Jun 23, 2018

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

@TrySound

This comment has been minimized.

Copy link
Member

TrySound commented Jun 23, 2018

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

@guybedford

This comment has been minimized.

Copy link
Contributor

guybedford commented Jun 23, 2018

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

@lukastaegert lukastaegert added this to the 1.0.0 milestone Jun 24, 2018

@lukastaegert lukastaegert added this to In progress in Release 1.0.0 via automation Jun 24, 2018

@lukastaegert lukastaegert moved this from In progress to In Review in Release 1.0.0 Jun 24, 2018

@lukastaegert

This comment has been minimized.

Copy link
Member

lukastaegert commented Jul 13, 2018

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

This comment has been minimized.

Copy link
Contributor

shellscape commented Jul 14, 2018

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.

@guybedford guybedford changed the base branch from master to plugin-cache Aug 10, 2018

@guybedford guybedford force-pushed the 1.0 branch 2 times, most recently from bda5c67 to 141ede3 Aug 10, 2018

@guybedford guybedford force-pushed the plugin-cache branch from 53862cf to 8ecb1e0 Aug 11, 2018

@guybedford guybedford force-pushed the plugin-cache branch from 8ecb1e0 to 164b280 Aug 12, 2018

@guybedford guybedford force-pushed the plugin-cache branch from 164b280 to f649f17 Aug 12, 2018

@guybedford guybedford changed the base branch from plugin-cache to master Aug 12, 2018

@guybedford guybedford changed the base branch from master to plugin-cache Aug 12, 2018

@guybedford guybedford changed the base branch from plugin-cache to master Aug 12, 2018

@guybedford guybedford force-pushed the 1.0 branch 2 times, most recently from 0d209a4 to 0eaf7e8 Aug 12, 2018

@guybedford guybedford changed the base branch from master to render-chunk-fix Aug 13, 2018

@guybedford guybedford force-pushed the render-chunk-fix branch from 68cdff5 to c98761e Aug 13, 2018

@lukastaegert lukastaegert force-pushed the 1.0 branch 2 times, most recently from b527617 to ae731a9 Dec 23, 2018

Lukas Taegert-Atkinson and others added some commits Dec 20, 2018

@lukastaegert lukastaegert merged commit 4f19233 into master Dec 28, 2018

0 of 3 checks passed

ci/circleci: dependency_cache Your tests are queued behind your running builds
Details
continuous-integration/appveyor/branch Waiting for AppVeyor build to complete
Details
continuous-integration/appveyor/pr Waiting for AppVeyor build to complete
Details

@lukastaegert lukastaegert deleted the 1.0 branch Dec 28, 2018

@panoply panoply referenced this pull request Dec 30, 2018

Closed

Rollup v1.0.0 changes #15

@simonhaenisch simonhaenisch referenced this pull request Jan 10, 2019

Merged

Update Rollup #1310

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment