Supporting multiple entries/inputs in the Javascript API

Documentation Is:

• Missing
• Needed
• Confusing
• Not Sure?

Please Explain in Detail...

The documentation surrounding supporting multiple entries in the Javascript API is confusing.

The docs cover multiple entries/inputs briefly and suggest using a rollup.config.js that exports an array as opposed to an object, i.e:

export default [{
  input: 'main-a.js',
  output: {
    file: 'dist/bundle-a.js',
    format: 'cjs'
  }
}, {
  input: 'main-b.js',
  output: [
    {
      file: 'dist/bundle-b1.js',
      format: 'cjs'
    },
    {
      file: 'dist/bundle-b2.js',
      format: 'esm'
    }
  ]
}];

Alternatively see #2935 for a more in depth discussion surrounding this.

What is unclear is whether or not you can use this in the Javascript API, essentially I thought I would be able to call rollup.rollup and pass it an array similar to the one exported in the above example, however this results in the following error:

Unknown input option: 0. Allowed options: acorn, acornInjectPlugins, cache, chunkGroupingSize, context, experimentalCacheExpiry, experimentalOptimizeChunks, experimentalTopLevelAwait, external, inlineDynamicImports, input, manualChunks, moduleContext, onwarn, perf, plugins, preserveModules, preserveSymlinks, shimMissingExports, strictDeprecations, treeshake, watch
Error: You must supply options.input to rollup

I have since realized that rollup.rollup is only capable of accepting one config object and must be called multiple times with each config.

Based on this comment in #863 this is not possible (although from what I can see rollup.watch may accept multiple arguments and as mentioned in the referenced comment this may warrant it's own issue).

As a side note it is also unclear that rollup.watch does accept an array when rollup.rollup does not.

Your Proposal for Changes

If this is the intended behaviour and there is not a planned changed on the immediate horizon I think it would be good to explicitly highlight that the Javascript API does not support multiple entries.

I think it would also be beneficial to perhaps give a rudimentary example of calling rollup.rollup multiple times in the event that a user needs to bundle multiple entries/inputs.

something like:

const { rollup } = require('rollup');

const buildEntries = entries => {
    const pending = entries.map(async item => {
        const [inputOptions, outputOptions] = item;

        const bundle = await rollup(inputOptions);
        await bundle.write(outputOptions);
        return;
    });

    // returns promise that resolves when all rollups complete
    return Promise.all(pending);
}

export default buildEntries;

Where entries would look something like:

[[{
    input: 'component.js',
    plugins: []
},
{
    dir: '/dist',
    name: 'Component',
    format: 'umd'
}]]

Start with the linked Configuration Files and Javascript API documentation, then compare their descriptions of multiple inputs and entries with the reported rollup.rollup and rollup.watch behavior. Done means the API documentation clearly states whether each API accepts multiple configurations and includes guidance or an example for bundling multiple entries.