diff --git a/.changeset/script-locator-cache-key.md b/.changeset/script-locator-cache-key.md new file mode 100644 index 000000000..24c88451c --- /dev/null +++ b/.changeset/script-locator-cache-key.md @@ -0,0 +1,5 @@ +--- +"@callstack/repack": minor +--- + +Add an optional `cacheKey` to `ScriptLocator`. When it is set, it is appended to the script's `uniqueId` (`_@`), so each key gets its own cache entry and its own file on the device. This lets an app keep several versions of the same script, for example to load the previous version again when a new one fails. diff --git a/packages/repack/src/modules/ScriptManager/Script.ts b/packages/repack/src/modules/ScriptManager/Script.ts index 6ec329446..58f5a3e30 100644 --- a/packages/repack/src/modules/ScriptManager/Script.ts +++ b/packages/repack/src/modules/ScriptManager/Script.ts @@ -91,7 +91,10 @@ export class Script { headers[key.toLowerCase()] = value; }); - const uniqueId = Script.getScriptUniqueId(key.scriptId, key.caller); + const baseId = Script.getScriptUniqueId(key.scriptId, key.caller); + const uniqueId = locator.cacheKey + ? `${baseId}@${locator.cacheKey}` + : baseId; let body: NormalizedScriptLocator['body']; if (locator.body instanceof FormData) { diff --git a/packages/repack/src/modules/ScriptManager/__tests__/ScriptManager.test.ts b/packages/repack/src/modules/ScriptManager/__tests__/ScriptManager.test.ts index 3172a008e..b56440dfd 100644 --- a/packages/repack/src/modules/ScriptManager/__tests__/ScriptManager.test.ts +++ b/packages/repack/src/modules/ScriptManager/__tests__/ScriptManager.test.ts @@ -193,6 +193,44 @@ describe('ScriptManagerAPI', () => { expect(script.locator.uniqueId).toEqual('src_App_js'); }); + it('should append cacheKey to uniqueId', async () => { + ScriptManager.shared.addResolver(async (scriptId) => ({ + url: Script.getRemoteURL(`http://domain.ext/v1/${scriptId}`), + cacheKey: 'v1', + })); + + const script = await ScriptManager.shared.resolveScript( + 'src_App_js', + 'main' + ); + expect(script.locator.uniqueId).toEqual('main_src_App_js@v1'); + }); + + it('should keep a separate cache entry for each cacheKey', async () => { + const cache = new FakeCache(); + ScriptManager.shared.setStorage(cache); + + let version = 'v1'; + ScriptManager.shared.addResolver(async (scriptId) => ({ + url: Script.getRemoteURL(`http://domain.ext/${version}/${scriptId}`), + cacheKey: version, + })); + + await ScriptManager.shared.loadScript('src_App_js', 'main'); + + version = 'v2'; + const v2 = await ScriptManager.shared.resolveScript('src_App_js', 'main'); + expect(v2.locator.uniqueId).toEqual('main_src_App_js@v2'); + expect(v2.locator.fetch).toBe(true); + + await ScriptManager.shared.loadScript('src_App_js', 'main'); + + version = 'v1'; + const v1 = await ScriptManager.shared.resolveScript('src_App_js', 'main'); + expect(v1.locator.uniqueId).toEqual('main_src_App_js@v1'); + expect(v1.locator.fetch).toBe(false); + }); + it('should resolve with url only', async () => { const cache = new FakeCache(); diff --git a/packages/repack/src/modules/ScriptManager/types.ts b/packages/repack/src/modules/ScriptManager/types.ts index 65d7545e7..9df558d69 100644 --- a/packages/repack/src/modules/ScriptManager/types.ts +++ b/packages/repack/src/modules/ScriptManager/types.ts @@ -102,6 +102,20 @@ export interface ScriptLocator { */ cache?: boolean; + /** + * Optional key that gives the script its own cache entry and its own file on the device. + * + * By default, a script is cached under an id made of its caller and script id only, so + * a new version of the script (e.g. one with a different `url`) replaces the previous one. + * When `cacheKey` is set, it is appended to that id (`_@`), + * so each key keeps its own cached copy. Use it to keep several versions of the same + * script on the device, e.g. by passing a release id or a content hash. + * + * The key becomes a part of a file name on the device, so it must not contain `/`. + * To remove one cached copy, pass the full id (with the key) to `invalidateScripts`. + */ + cacheKey?: string; + /** * Flag to enable script's code-signature verification. By default set to `none` * diff --git a/website/src/latest/api/runtime/script-manager.md b/website/src/latest/api/runtime/script-manager.md index 0c840aaa2..b5b959b34 100644 --- a/website/src/latest/api/runtime/script-manager.md +++ b/website/src/latest/api/runtime/script-manager.md @@ -278,6 +278,23 @@ ScriptManager.shared.hooks.afterResolve(async (args) => { }); ``` +### Keeping several versions of a script on the device + +By default, a script is cached under its caller and script id, so a new version replaces the previous one on the device. Set `cacheKey` to give each version its own cached copy, for example to load the previous version again without a network call: + +```js +ScriptManager.shared.hooks.afterResolve(async (args) => { + // e.g. https://cdn.example.com/my-remote/1.4.0/src_App_js.chunk.bundle + const version = getVersionFromUrl(args.locator.url); + if (version) { + args.locator.cacheKey = version; + } + return args; +}); +``` + +The script is then cached as `_@`. Pass that id to `invalidateScripts` to remove one version. + ### Override script locator URL after resolution ```js