Cache documentation is misleading.

[GeorgeTailor]

Documentation Is:

• Missing
• Needed
• Confusing
• Not Sure?

Please Explain in Detail...

https://rollupjs.org/guide/en/#cache says:

Setting this option explicitly to false will prevent generating the cache property on the bundle and also deactivate caching for plugins.

However, by looking at the actual options passed as InputOptions during the first build it's

cache: { modules: [] }

Setting cache property to false (as stated in the docs) via InputOptions does not work at all, for example:

export default [
	{
		input: 'src/components.js',
		output: {
			sourcemap: true,
			format: 'esm',
			file: 'docs/components.js',
			name: 'components'
		},
		cache: false, // THIS IS IGNORED
		plugins: [ watcher() ]
	}
];

I have created a custom plugin to additionally watch *.css and *.html files, which are injected dynamically during build phase, but due to rollup caching mechanism my custom plugin fires only once during first build. I am building quite a small library and the first build takes around ~400ms, so I don't really need any caching and that's why I tried to disable it.

workaround
as of now the way I managed to solve this issue is by adding a hook to my custom plugin:

function watcher() {
	return {
		buildStart(options) {
			console.log(options)
			let include = ['src/**/*.html', 'src/**/*.css'];
			for (const item of include) {
				glob.sync(path.resolve(item)).forEach(filename => this.addWatchFile(filename));
			}
		},
		options(options) {
			options.cache = {}; // THIS LINE DISABLES CACHE
			return options;
		}
	}
}

the above way is the only way I found working and it is not consistent with the docs.

Rollup version that I used was 2.27.1

Your Proposal for Changes

I am not sure if it's something in the docs that should be fixed or in rollup logic itself, but the whole situation is greatly confusing.

[Amareis]

This is definitely watcher incosistency, because of way how it handle transform dependencies. If cache is not presented in options - there is no cache in rollup result, so watcher forced to using cache. But there is no such need - if we don't use cache, transform dependencies will not be, uhm, cached! So it's really simple patch, but I think it should be applied after #3841 is merged.

[lukastaegert]

This is interesting. I see it still looks correct after normalizeInputOptions. And there is also a test in the hooks section that verifies that no cache is generated at the end (which is the costly operation that is to be avoided) for cache: false.

[Amareis]

This is only applies to watcher, which always add cache to options here. It can be fixed easily, just additional check at top of Task::run and Task::updateWatchedFiles