From 13f380b80d8ab27763f606cc2f5ee9e65348220a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A9lix=20Malfait?= Date: Fri, 3 Jul 2026 17:17:14 +0200 Subject: [PATCH] perf(front-component): fingerprint built-JS URLs by path for CDN caching (#22530) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Stacked on #22523** — base is that branch, so the diff shows only this commit. GitHub will retarget it to `main` automatically once #22523 merges. Follows up on @FelixMalfait's question on #22523: move the BuiltFrontComponent cache key from a query string into the path so it plays well with Cloudflare cache rules. ## What - URL: `/rest/front-components/:id?checksum=` → `/rest/front-components/:id/.js` (`getFrontComponentUrl`). - Route: the controller now accepts `[':frontComponentId', ':frontComponentId/:cacheKey']`. `:cacheKey` is a pure cache-buster the server **ignores** — it still resolves by `:frontComponentId`, exactly as the query param did. ## Why a path segment (not `:id-.js`) A path-based, extension-bearing URL is matched by Cloudflare's **default** static-asset caching and by trivial `*.js` path cache rules, and it's immune to any "ignore query string" cache setting that would otherwise collapse `?checksum=` to one entry and serve stale JS. I used a path **segment** (`/:id/:checksum.js`) rather than the literal `:id-.js` you sketched because the id is a **UUID — which itself contains hyphens** — so a `-` separator is ambiguous to parse. A segment is unambiguous and equally CDN-friendly (still ends in `.js`). ## Backward compatibility The bare `:frontComponentId` route is kept, so URLs minted before this deploys (query-string form, or in-flight pages) still resolve. It can be dropped in a later release once no client mints the old form. No data migration — the URL is computed at render time from `frontComponentId` + `builtComponentChecksum`. ## ⚠️ Decision for you: this alone does not edge-cache — `private` vs `public` BFC is served behind `WorkspaceAuthGuard` and #22523 set its header to **`private`**, max-age, immutable. `private` means shared caches (Cloudflare) **won't** store it — so today this is browser-cache only, and the path change just makes it *ready* for edge caching + clean cache rules. To actually get **edge** caching you'd additionally either flip BFC to `public` or add a Cloudflare rule that overrides cache-control — which means **accepting that the `id`+`checksum` URL becomes the access capability** (a cache hit is served without re-checking origin auth). The cache key is unique per component+build so there's no cross-workspace mixup, but the built JS effectively becomes public-by-URL (same posture PublicAsset already has). I've **left it `private`** here; flipping to `public` is your call and can be a one-line follow-up. ## Tests - `getFrontComponentUrl` unit test: fingerprinted path when a checksum is present, bare fallback otherwise. - Integration test: the `/front-components/:id/:checksum.js` path serves the built JS with `Content-Type: application/javascript` and `Cache-Control: private, max-age=86400, immutable`. Existing bare-route tests remain and still pass. https://claude.ai/code/session_01AKwhTxYFDhWhCZ4b7sf35W --- _Generated by [Claude Code](https://claude.ai/code/session_01AKwhTxYFDhWhCZ4b7sf35W)_ Review in cubic --- .../__tests__/getFrontComponentUrl.test.ts | 21 +++++++++++++++++++ .../utils/getFrontComponentUrl.ts | 2 +- .../controllers/front-component.controller.ts | 2 +- ...ont-component-built-js.integration-spec.ts | 14 +++++++++++++ 4 files changed, 37 insertions(+), 2 deletions(-) create mode 100644 packages/twenty-front/src/modules/front-components/utils/__tests__/getFrontComponentUrl.test.ts diff --git a/packages/twenty-front/src/modules/front-components/utils/__tests__/getFrontComponentUrl.test.ts b/packages/twenty-front/src/modules/front-components/utils/__tests__/getFrontComponentUrl.test.ts new file mode 100644 index 0000000000..53867c6e4b --- /dev/null +++ b/packages/twenty-front/src/modules/front-components/utils/__tests__/getFrontComponentUrl.test.ts @@ -0,0 +1,21 @@ +import { REST_API_BASE_URL } from '@/apollo/constant/rest-api-base-url'; +import { getFrontComponentUrl } from '@/front-components/utils/getFrontComponentUrl'; + +describe('getFrontComponentUrl', () => { + it('builds a checksum-fingerprinted path URL when a checksum is provided', () => { + expect( + getFrontComponentUrl({ + frontComponentId: 'front-component-id', + checksum: 'abc123', + }), + ).toBe( + `${REST_API_BASE_URL}/front-components/front-component-id/abc123.js`, + ); + }); + + it('falls back to the bare id URL when no checksum is provided', () => { + expect( + getFrontComponentUrl({ frontComponentId: 'front-component-id' }), + ).toBe(`${REST_API_BASE_URL}/front-components/front-component-id`); + }); +}); diff --git a/packages/twenty-front/src/modules/front-components/utils/getFrontComponentUrl.ts b/packages/twenty-front/src/modules/front-components/utils/getFrontComponentUrl.ts index a5afcfe5a2..891d9c59fd 100644 --- a/packages/twenty-front/src/modules/front-components/utils/getFrontComponentUrl.ts +++ b/packages/twenty-front/src/modules/front-components/utils/getFrontComponentUrl.ts @@ -9,6 +9,6 @@ export const getFrontComponentUrl = ({ checksum?: string; }): string => { return isDefined(checksum) - ? `${REST_API_BASE_URL}/front-components/${frontComponentId}?checksum=${checksum}` + ? `${REST_API_BASE_URL}/front-components/${frontComponentId}/${checksum}.js` : `${REST_API_BASE_URL}/front-components/${frontComponentId}`; }; diff --git a/packages/twenty-server/src/engine/metadata-modules/front-component/controllers/front-component.controller.ts b/packages/twenty-server/src/engine/metadata-modules/front-component/controllers/front-component.controller.ts index 410493cac7..430ef15c29 100644 --- a/packages/twenty-server/src/engine/metadata-modules/front-component/controllers/front-component.controller.ts +++ b/packages/twenty-server/src/engine/metadata-modules/front-component/controllers/front-component.controller.ts @@ -46,7 +46,7 @@ export class FrontComponentController { constructor(private readonly frontComponentService: FrontComponentService) {} - @Get(':frontComponentId') + @Get([':frontComponentId', ':frontComponentId/:cacheKey']) @UseGuards(NoPermissionGuard) async getBuiltJs( @Res() res: Response, diff --git a/packages/twenty-server/test/integration/rest/suites/front-component-built-js.integration-spec.ts b/packages/twenty-server/test/integration/rest/suites/front-component-built-js.integration-spec.ts index 1d759b7443..c3d389cf04 100644 --- a/packages/twenty-server/test/integration/rest/suites/front-component-built-js.integration-spec.ts +++ b/packages/twenty-server/test/integration/rest/suites/front-component-built-js.integration-spec.ts @@ -55,6 +55,20 @@ describe('Front component built JS endpoint', () => { }); }); + it('should serve the built JS from the checksum-fingerprinted path with an immutable cache header', async () => { + await makeRestAPIRequest({ + method: 'get', + path: `/front-components/${frontComponentId}/test-checksum-123.js`, + bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN, + }) + .expect(200) + .expect('Content-Type', /application\/javascript/) + .expect('Cache-Control', 'private, max-age=86400, immutable') + .expect((res) => { + expect(res.text).toBe('dummy built component content'); + }); + }); + it('should return 404 for a non-existent front component ID', async () => { const nonExistentId = '00000000-0000-0000-0000-000000000000';