Feature: Enable Plugin loadContent caching, improve plugin reload perf

[milesj]

🚀 Feature

This feature request will help to avoid slow builds/hot reloads by allowing plugin authors to cache effectively.

Do note that this is a plugin author feature request and not for the end-user.

Have you read the Contributing Guidelines on issues?

Yes

Has this been requested on Canny?

No

Motivation

Plugin authors can utilize the loadContent life-cycle (docs) to async/sync load content needed for the plugin. However, this method is called every time a file is changed while the development server is running.

Typically this is ok and wanted functionality, but if the code within loadContent takes a considerable amount of time to process, then the entire experience is degraded. I ran into this while building docusaurus-plugin-typedoc-api, as the TypeDoc build process is rather slow (roughly 30 seconds).

To help alleviate this problem we can cache the long processes, but there is no way to invalidate the cache, or know when we should rebuild.

API Design

My proposal is to pass a "build state" object to the loadContent life-cycle method. This object would contain the following properties:

• firstLoad (boolean) - A flag representing the 1st time loadContent is called. Triggered by both build and start. This will allow authors to effectively cache miss on new builds.
• changedFiles (string[]) - A list of files that have changed since the last rebuild/reload. This will allow authors to determine whether to cache hit/miss based on file paths/extensions.

Using my TypeDoc problem above, an example of this in practice would look something like.

async loadContent({ firstLoad, changedFiles }) {
	const cachePath = path.join(context.generatedFilesDir, 'typedoc.json');
	const hasTsFiles = changedFiles.some(file => file.match(/\.tsx?$/));

	// Run TypeDoc and write to cache if first load or TS files have changed
	if (firstLoad || hasTsFiles) {
		await generateTypeDocJson(cachePath);
	}

	return import(cachePath);
}

Have you tried building it?

No, not yet...

I have tried to detect whether a rebuild is happening, but there's no way to persist plugin state. For example, the following does not work, it always logs 1.

export default function() {
	let count = 0;

	return {
		async loadContent() {
			count += 1;
			console.log(count);
		}
	};
}

Have also looked into environment variables, but nothing related to rebuilds.

[slorber]

You are right that currently, all this is not very optimized, and we should build a caching layer, or at least enable plugin authors to do so more easily.

Some things we want:

1. On plugin1 file change, do not reload plugin2 content (currently it does!)
2. Allow plugins to cache data across plugin reloads
3. Allow plugins to cache data across restarts
4. Allow plugins to sync incrementally their cache with event-based sources (useful for some CMS integration if there's a lot of data, a bit like what Gatsby CMS plugins do)

All this is not so easy to design in an elegant way IMHO, and your API proposal mostly addresses 2) but not the other cases.

I'd like to work on this someday, starting with 1) which is a thing we should handle in the core.

For 2) I don't feel a change in core is strictly required, and you can probably detect which files were updated in userland, but I agree it's not the most straightforward and we should provide something for that use case. You can probably persist the state to disk or outside the plugin function?

Note we use Chokidar for watching plugin files:
https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/commands/start.ts

For now, we don't have the infra to provide the list of files that have changed, as each file change can trigger its own reload that are debounced:

const fsWatcher = chokidar.watch(pathsToWatch, {
    cwd: siteDir,
    ignoreInitial: true,
    usePolling: !!cliOptions.poll,
    interval: Number.isInteger(cliOptions.poll)
      ? (cliOptions.poll as number)
      : undefined,
  });

  ['add', 'change', 'unlink', 'addDir', 'unlinkDir'].forEach((event) =>
    fsWatcher.on(event, reload),
  );

// Reload files processing.
  const reload = debounce(() => {
    loadSite()
      .catch((err) => {
        console.error(chalk.red(err.stack));
      });
  }, 500);

If we add this, what about having a new reloadContent lifecycle instead?

async loadContent({) {
	return generateTypeDocJson(cachePath);
}

async reloadContent({ previousContent, changedFiles }) {
	const hasTsFiles = changedFiles.some(file => file.match(/\.tsx?$/));
	if (firstLoad || hasTsFiles) {
		return loadContent();
	}
	return previousContent;
}

My motivation for this API is to receive the previousContent in params. This can be useful for example in the docs plugin where we could detect that only v1 files were modified, so it's not worth reloading all the other versions.

This lifecycle would be optional and fall-back to loadContent() for non-optimized plugins.

[milesj]

@slorber Great write up, all those ideas sound great. Looking forward to them, if they ever land (hah).

As for reloadContent, that also works for me. I don't really care what the API looks like, just as long as we have some kind of information/mechanism to handle cache hits/misses.

[milesj]

Would also like to note, that I also tried to keep track of the build state outside of the plugin in the module scope, but that didn't work either. It seems like the module is re-evaluated everytime a rebuild is triggered.

The only way to get this to work is to track the state on the filesystem.

[slorber]

Not too surprised, we use import-fresh so the module can actually be somehow hot reloaded without restarting the nodejs server (which otherwise has some caching system).

If you create the cache/global state in another file (that you import in the plugin entrypoint), I think it would work because we only apply importFresh to the plugin entrypoint and not the whole dependency graph.

This is definitively a bit confusing and was implemented that way a few years ago, I think it does not help users implement a caching layer in userland so I may try to remove that in the future.