Unifying Rollup options

README.md

Rollup 0.48 introduces a few changes to the options object, because the current options are confusingly different between the CLI and the options exported by your config file.

Changes to the config file

• entry is now input
• sourceMap and sourceMapFile are now sourcemap and sourcemapFile (note casing)
• moduleName is now name
• useStrict is now strict

The dest and format options are now grouped together as a single output: { file, format, ... } object. output can also be an array of { file, format, ... } objects, in which case it behaves similarly to the current targets. Other output options — exports, paths and so on — can be added to the output object (though they will fall back to their top-level namesakes, if unspecified).

So this...

// old rollup.config.js
export default {
  entry: 'src/main.js',
  dest: 'public/bundle.js',
  format: 'iife',
  moduleName: 'App',
  sourceMap: true
};

...would become this:

// new rollup.config.js
export default {
  input: 'src/main.js',
  output: {
    file: 'public/bundle.js',
    format: 'iife',
    name: 'App',
    sourcemap: true
  }
};

A config with multiple outputs (say, a CommonJS main and a ESM module output) might look like this:

import pkg from './package.json';

export default {
  input: 'src/index.js',
  output: [
    { file: pkg.main, format: 'umd', name: 'MyLibrary' },
    { file: pkg.module, format: 'es' }
  ],
  
  // other output options specified here will be shared by
  // all outputs, unless overridden
  sourcemap: true
};

Changes to the API

The same changes apply if you're using the API directly:

rollup.rollup({
  input: 'src/main.js'
}).then(bundle => {
  return bundle.write({
    file: 'public/bundle.js',
    format: 'iife',
    name: 'App',
    sourcemap: true
  });
});

Changes to the CLI

The --output and --format can now also be specified as --output.file and --output.format respectively. The shorthand -o and -f options are unchanged.

@Rich-Harris it seems it's possible to pass name as options.name and options.output.name - which one is preferred, is 1 of them going to be deprecated? Also it seems helpful migration console.log suggests the former, but docs suggest the latter - should be unified in some way I think. Might send a PR for this, aint sure which one is 'more correct' though

@Rich-Harris Why did you decide to change the API to match the CLI instead of the other way around? I would expect soft humans to have an easier time digesting such a change.

@Andarist Output options will fall back to their top-level equivalents, so options.name will be used if options.output.name is unspecified. I.e. name isn't a special case here, it's just behaving like other output options. Neither will be deprecated.

@permutatrix I felt the CLI options were better and more explicit — input and output are easier to grok than entry and dest, and name is much nicer than moduleName. Even though it's a more severe change, I think it sets us up better for the future.

Let's update https://github.com/rollup/rollup-starter-lib/

@Rich-Harris Is there an error in example

A config with multiple outputs

it's saying setup is for "CommonJS" and ESM, but instead of:

{ file: pkg.main, format: 'cjs', name: 'MyLibrary' },

it has:

{ file: pkg.main, format: 'umd', name: 'MyLibrary' },

???

And real umd would be mapped to pkg.browser field then?

how to customize the bundle file's name, just like webpack did!

/*
    // webpack
    path: path.resolve(__dirname, "build/js/"),
    filename: '[name].min.js',

*/

???

The changes of moving global to output should be recorded

it is globals not global

If I use output as an array, where do I put output.globals?

@mAAdhaTTah
At the moment it seems inside every item in the output array, for example:

export default {
  output: [
    { file: pkg.main, format: 'umd', globals: {} }, 
    { file: pkg.module, format: 'es' , globals: {}}
  ],
  ...
}

To avoid duplicate code I do it as follows:

const globals = { };
const output = [
    { file: pkg.main, format: 'umd' }, 
    { file: pkg.module, format: 'es' }
  ].map(out => ({ ...out, globals}));

export default {
  output,
  ...
}

@mAAdhaTTah
At the moment it seems inside every item in the output array, for example:

export default {
  output: [
    { file: pkg.main, format: 'umd', globals: {} }, 
    { file: pkg.module, format: 'es' , globals: {}}
  ],
  ...
}

To avoid duplicate code I do it as follows:

const globals = { };
const output = [
    { file: pkg.main, format: 'umd' }, 
    { file: pkg.module, format: 'es' }
  ].map(out => ({ ...out, globals}));

export default {
  output,
  ...
}

how do i pass output array to bundle.generate or bundle.write?

@aelbore Arrays are only supported for the CLI. The CLI then maps the array to separate calls to bundle.write. If you use the JS API, you have to do it yourself, i.e. call bundle.generate or bundle.write once per output.

@lukastaegert how you combine bundle.write with watch?

watch accepts basically config files, i.e. arrays of configs etc.