Documentation is confusing around output options and bundle API

[matthew-dean]

Documentation Is:

• Missing
• Needed
• Confusing
• Not Sure?

Please Explain in Detail...

There are a number of places / plugins that specify the Rollup configuration as one object, such as https://github.com/TrySound/rollup-plugin-terser.

However, the Rollup API as documented is confusing, and doesn't seem to cover this use case. bundle.generate requires an output options object, as does bundle.write. I've been clicking through various plugins, and poring through the Rollup documentation, yet I can't seem to find a single example of:

1. Creating two bundles
2. Minifying one of them
3. Writing to a directory

The Rollup docs seem to have a number of fairly advanced examples, but either skip the simple ones, or I can't find them, or I don't understand a) when to use entry vs. input, or b) when to include output options in the main Rollup config or in one of the bundle methods. It's not clear to me why input/output options are sometimes together, sometimes apart, sometimes called to methods (and sometimes not needed?)

I seem to recall doing this very easily with Rollup some time ago, before the documentation site was created, and it seemed quite straightforward. (This was before async/await examples.) Now the API seems quite confusing and not intuitive as to what to do here.

Your Proposal for Changes

1. Provide simple use cases, including a common one like creating a minified second bundle.
2. Bury advanced options past the initial tutorial. A lot of advanced settings are mixed in very early on, such as in the rollup.rollup API.
3. Explain where to put output options and why they might live in the main configuration (what that's doing).
4. Document bundle.write and bundle.generate (the API of bundles seems to be missing or I can't find it?)

[matthew-dean]

I learned that I could write each filename twice in bundle.write, but I don't understand why I can't just define the output objects in the output property, and then just do bundle.write() or bundle.write({ dir: './dist' } and have that work. It's not clear why there seems to be duplicate output options.