From d4471b4a6a743e533be93235822c029e800f7c08 Mon Sep 17 00:00:00 2001 From: Lukas Taegert-Atkinson Date: Thu, 17 Feb 2022 06:28:09 +0100 Subject: [PATCH] Document how resolveId is cached (#4407) --- docs/05-plugin-development.md | 6 +++++- docs/build-hooks.mmd | 6 +++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/05-plugin-development.md b/docs/05-plugin-development.md index 9beecebc79f..4b73a042072 100644 --- a/docs/05-plugin-development.md +++ b/docs/05-plugin-development.md @@ -262,6 +262,8 @@ Note that while `resolveId` will be called for each import of a module and can t When triggering this hook from a plugin via [`this.resolve`](guide/en/#thisresolve), it is possible to pass a custom options object to this hook. While this object will be passed unmodified, plugins should follow the convention of adding a `custom` property with an object where the keys correspond to the names of the plugins that the options are intended for. For details see [custom resolver options](guide/en/#custom-resolver-options). +In watch mode or when using the cache explicitly, the resolved imports of a cached module are also taken from the cache and not determined via the `resolveId` hook again. To prevent this, you can return `true` from the [`shouldTransformCachedModule`](guide/en/#shouldtransformcachedmodule) hook for that module. This will remove the module and its import resolutions from cache and call `transform` and `resolveId` again. + #### `shouldTransformCachedModule` **Type:** `({id: string, code: string, ast: ESTree.Program, meta: {[plugin: string]: any}, moduleSideEffects: boolean | "no-treeshake", syntheticNamedExports: string | boolean}) => boolean`
**Kind:** `async, first`
**Previous Hook:** [`load`](guide/en/#load) where the cached file was loaded to compare its code with the cached version.
**Next Hook:** [`moduleParsed`](guide/en/#moduleparsed) if no plugin returns `true`, otherwise [`transform`](guide/en/#transform). @@ -278,7 +280,9 @@ If a plugin does not return `true`, Rollup will trigger this hook for other plug Can be used to transform individual modules. To prevent additional parsing overhead in case e.g. this hook already used `this.parse` to generate an AST for some reason, this hook can optionally return a `{ code, ast, map }` object. The `ast` must be a standard ESTree AST with `start` and `end` properties for each node. If the transformation does not move code, you can preserve existing sourcemaps by setting `map` to `null`. Otherwise you might need to generate the source map. See [the section on source code transformations](#source-code-transformations). -Note that in watch mode, the result of this hook is cached when rebuilding and the hook is only triggered again for a module `id` if either the `code` of the module has changed or a file has changed that was added via `this.addWatchFile` the last time the hook was triggered for this module. +Note that in watch mode or when using the cache explicitly, the result of this hook is cached when rebuilding and the hook is only triggered again for a module `id` if either the `code` of the module has changed or a file has changed that was added via `this.addWatchFile` the last time the hook was triggered for this module. + +In all other cases, the [`shouldTransformCachedModule`](guide/en/#shouldtransformcachedmodule) hook is triggered instead, which gives access to the cached module. Returning `true` from `shouldTransformCachedModule` will remove the module from cache and instead call `transform` again. You can also use the object form of the return value to configure additional properties of the module. Note that it's possible to return only properties and no code transformations. diff --git a/docs/build-hooks.mmd b/docs/build-hooks.mmd index 512dc5916b0..93da9f1a6b9 100644 --- a/docs/build-hooks.mmd +++ b/docs/build-hooks.mmd @@ -3,6 +3,7 @@ flowchart TB classDef hook-sequential fill:#ffd2b3,stroke:#000; classDef hook-first fill:#fff2b3,stroke:#000; classDef hook-sequential-sync fill:#ffd2b3,stroke:#f00; + classDef hook-first-sync fill:#fff2b3,stroke:#f00; buildend("buildEnd"):::hook-parallel click buildend "/guide/en/#buildend" _parent @@ -60,7 +61,10 @@ flowchart TB --> |non-external|load moduleparsed - --> |each import|resolveid + --> |"each import\n(cached)"|load + + moduleparsed + --> |"each import\n(not cached)"|resolveid resolvedynamicimport .-> |external|buildend