@faststore/core 3.100.7 → 3.100.8

package/.turbo/turbo-build.log

@@ -1,23 +1,23 @@
 
-> @faststore/core@3.100.6 prebuild /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.100.7 prebuild /home/runner/work/faststore/faststore/packages/core
 > na run partytown && na run generate
 
 
-> @faststore/core@3.100.6 partytown /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.100.7 partytown /home/runner/work/faststore/faststore/packages/core
 > partytown copylib ./public/~partytown
 
 Partytown lib copied to: /home/runner/work/faststore/faststore/packages/core/public/~partytown
 
-> @faststore/core@3.100.6 generate /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.100.7 generate /home/runner/work/faststore/faststore/packages/core
 > na run generate:schema && na run generate:codegen && na run format:generated
 
 
-> @faststore/core@3.100.6 generate:schema /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.100.7 generate:schema /home/runner/work/faststore/faststore/packages/core
 > tsx src/server/generator/generateGraphQLSchemaFile.ts
 
 Schema GraphQL file generated successfully
 
-> @faststore/core@3.100.6 generate:codegen /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.100.7 generate:codegen /home/runner/work/faststore/faststore/packages/core
 > graphql-codegen
 
 [STARTED] Parse Configuration
@@ -37,11 +37,11 @@ Running lifecycle hook "afterStart" scripts...
 [CLI] Loading Documents
 [CLI] Generating output
 
-> @faststore/core@3.100.6 format:generated /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.100.7 format:generated /home/runner/work/faststore/faststore/packages/core
 > prettier --write "@generated/**/*.{ts,js,tsx,jsx,json}" --loglevel error
 
 
-> @faststore/core@3.100.6 build /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.100.7 build /home/runner/work/faststore/faststore/packages/core
 > next build
 
 ⚠ No build cache found. Please configure build caching for faster rebuilds. Read more: https://nextjs.org/docs/messages/no-cache
@@ -101,10 +101,10 @@ Import trace for requested module:
    Generating static pages (0/8) ...
 
   Generating static pages (2/8) 
 Search not found. Add a new component for this section or remove it from the CMS
-Search not found. Add a new component for this section or remove it from the CMS
 Warning: Dynamic Content not found for the page: home. Refer to the Dynamic Content documentation at https://developers.vtex.com/docs/guides/faststore/dynamic-content-overview for mapping the page and the corresponding data-fetching function.
-
   Generating static pages (4/8) 
 Search not found. Add a new component for this section or remove it from the CMS
+Search not found. Add a new component for this section or remove it from the CMS
+
   Generating static pages (4/8) 
 Search not found. Add a new component for this section or remove it from the CMS
 
   Generating static pages (6/8) 
 Search not found. Add a new component for this section or remove it from the CMS
@@ -154,7 +154,7 @@ Route (pages)                              Size     First Load JS
   ├ chunks/framework-d514426edf885c68.js   45.4 kB
   ├ chunks/main-a2d1cfe626f2fef1.js        33.4 kB
   ├ chunks/pages/_app-35e8dda638ee2672.js  26.6 kB
-  ├ chunks/webpack-bde714c56fd09a0c.js     3.9 kB
+  ├ chunks/webpack-62bcb2a452e15476.js     3.9 kB
   └ css/146a8678babc61bf.css               9.2 kB
 
 ƒ Middleware                               44.8 kB

package/.turbo/turbo-test.log

@@ -1,23 +1,24 @@
 
-> @faststore/core@3.100.6 test /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.100.7 test /home/runner/work/faststore/faststore/packages/core
 > jest
 
-PASS test/server/content/service.test.ts (15.95 s)
-PASS test/utils/cookieCacheBusting.test.ts (15.164 s)
-PASS test/server/password-protection-service.test.ts (17.702 s)
+PASS test/server/content/service.test.ts (13.432 s)
+PASS test/utils/cookieCacheBusting.test.ts (11.728 s)
+PASS test/server/password-protection-service.test.ts (13.8 s)
 PASS test/utils/multipleTemplates.test.ts
 PASS test/utils/clearCookies.test.ts
+PASS test/server/cms/index.test.ts
 PASS test/sdk/redirects/index.test.ts
 PASS test/utils/trustedForwardedHost.test.ts
-PASS test/utils/validateSessionRefreshToken.test.ts
+PASS test/server/content/promiseCache.test.ts
 PASS test/server/cms/global.test.ts
+PASS test/utils/validateSessionRefreshToken.test.ts
 PASS test/utils/isLocalHost.test.ts
 PASS test/utils/isLocalHost.browser.test.ts
-PASS test/server/cms/index.test.ts
-PASS test/server/index.test.ts (9.929 s)
+PASS test/server/index.test.ts (5.995 s)
 
-Test Suites: 13 passed, 13 total
-Tests:       128 passed, 128 total
+Test Suites: 14 passed, 14 total
+Tests:       155 passed, 155 total
 Snapshots:   0 total
-Time:        28.81 s
+Time:        21.421 s
 Ran all test suites.

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.100.8](https://github.com/vtex/faststore/compare/v3.100.7...v3.100.8) (2026-10-27)
+
+### Bug Fixes
+
+- **core:** address review feedback on CMS cache (3.x) ([ef77b3f](https://github.com/vtex/faststore/commit/ef77b3fa73d2cd475fef6129a3d0a948b9b59cbc))
+- **core:** cache Content Platform template list across page generations (3.x) ([6480dd5](https://github.com/vtex/faststore/commit/6480dd5850baaacd3e9cc698be4690795b63ab7a)), closes [#3526](https://github.com/vtex/faststore/issues/3526)
+- **core:** cache global and single CMS content across page generations (3.x) ([01d1b3a](https://github.com/vtex/faststore/commit/01d1b3a6ab6df30676f38275399ba6e5d3e0213b))
+- **core:** do not cache empty required CMS content (3.x) ([df849cb](https://github.com/vtex/faststore/commit/df849cb3b967b305fa67b2cc7b3f7fdafabcba99))
+
 ## [3.100.7](https://github.com/vtex/faststore/compare/v3.100.6...v3.100.7) (2026-10-26)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faststore/core",
-  "version": "3.100.7",
+  "version": "3.100.8",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -127,5 +127,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.3.2"
   },
-  "gitHead": "fc9b34b4fc943c17e225249677b49e393dc2d1f4"
+  "gitHead": "e742ac062ea5c0dd4df931f2431123bbbf973f34"
 }

package/src/server/cms/index.ts

@@ -2,6 +2,7 @@ import type { ContentData, ContentTypeOptions, Locator } from '@vtex/client-cms'
 import ClientCMS from '@vtex/client-cms'
 
 import MultipleContentError from 'src/sdk/error/MultipleContentError'
+import { createPromiseCache } from 'src/server/content/promiseCache'
 import { sanitizeHost } from 'src/utils/utilities'
 import config from '../../../discovery.config'
 
@@ -71,16 +72,64 @@ export const clientCMS = new ClientCMS({
   host: sanitizeHost(config.storeUrl),
 })
 
+type CMSPageResult = { data: ContentData[] }
+
+export const cmsPageCache = createPromiseCache<CMSPageResult>()
+
+type GetCMSPageOptions = {
+  /**
+   * Reuse a document fetched by locator. Only safe when the locator does not
+   * come from a preview, since preview versions change between requests.
+   */
+  cache?: boolean
+}
+
+/**
+ * Listings by content type never carry preview data (previews always resolve
+ * to a locator), so they are shared across pages. Filtered listings depend on
+ * the page (e.g. landing page slug) and stay uncached.
+ */
 export const getCMSPage = async (
   options: Options,
-  cmsClient: ClientCMS = clientCMS
-) => {
+  cmsClient: ClientCMS = clientCMS,
+  { cache = false }: GetCMSPageOptions = {}
+): Promise<CMSPageResult> => {
+  const shareable = cmsClient === clientCMS
+
   if (isLocator(options)) {
-    return await cmsClient
-      .getCMSPage(options)
-      .then((page) => ({ data: [page] }))
+    const fetchByLocator = () =>
+      cmsClient.getCMSPage(options).then((page) => ({ data: [page] }))
+
+    if (!cache || !shareable) {
+      return fetchByLocator()
+    }
+
+    const { contentType, documentId, versionId, releaseId } = options
+    return cmsPageCache.get(
+      JSON.stringify([
+        'locator',
+        contentType,
+        documentId,
+        versionId,
+        releaseId,
+      ]),
+      fetchByLocator
+    )
+  }
+
+  if (options.filters || !shareable) {
+    return listCMSPages(options, cmsClient)
   }
 
+  return cmsPageCache.get(JSON.stringify(['list', options.contentType]), () =>
+    listCMSPages(options, cmsClient)
+  )
+}
+
+const listCMSPages = async (
+  options: Exclude<Options, Locator>,
+  cmsClient: ClientCMS
+): Promise<CMSPageResult> => {
   const pages = []
   const page = 1
   const perPage = 10
@@ -116,8 +165,11 @@ export const getCMSPage = async (
   return { data: pages }
 }
 
-export const getPage = async <T extends ContentData>(options: Options) => {
-  const result = await getCMSPage(options)
+export const getPage = async <T extends ContentData>(
+  options: Options,
+  getOptions?: GetCMSPageOptions
+) => {
+  const result = await getCMSPage(options, clientCMS, getOptions)
 
   const pages = result.data
 

package/src/server/cms/pdp.ts

@@ -57,11 +57,16 @@ const getPDPFromCmsEnvData = async (
 
   const template = findBestPDPTemplate(pages, product)
 
-  return getPage<PDPContentType>({
-    contentType: 'pdp',
-    documentId: template.documentId as string,
-    versionId: template.versionId,
-  })
+  // The template locator comes from the build-time CMS data, never from a
+  // preview, so the fetched document can be shared across page generations.
+  return getPage<PDPContentType>(
+    {
+      contentType: 'pdp',
+      documentId: template.documentId as string,
+      versionId: template.versionId,
+    },
+    { cache: true }
+  )
 }
 
 const getPDPFromCms = async (

package/src/server/cms/plp.ts

@@ -71,11 +71,16 @@ const getPLPFromCmsEnvData = async (
 
   const template = findBestPLPTemplate(pages, slug, rewrites)
 
-  return getPage<PLPContentType>({
-    contentType: 'plp',
-    documentId: template.documentId as string,
-    versionId: template.versionId,
-  })
+  // The template locator comes from the build-time CMS data, never from a
+  // preview, so the fetched document can be shared across page generations.
+  return getPage<PLPContentType>(
+    {
+      contentType: 'plp',
+      documentId: template.documentId as string,
+      versionId: template.versionId,
+    },
+    { cache: true }
+  )
 }
 
 export const getPLPFromCms = async (

package/src/server/content/promiseCache.ts

@@ -0,0 +1,68 @@
+// Bounds how stale shared CMS content can get in long-lived processes (ISR);
+// a CMS publish already triggers a new build.
+export const CONTENT_CACHE_TTL_MS = 5 * 60 * 1000
+
+type PromiseCacheEntry<T> = {
+  expiresAt: number
+  promise: Promise<T>
+}
+
+/**
+ * Per-process memoization of async loaders. Concurrent callers share the
+ * in-flight promise, entries expire after `ttlMs`, and rejections are evicted
+ * so the next caller retries. When `shouldCache` rejects a resolved value, the
+ * entry is evicted too, so only the callers already waiting share that value.
+ * Expired entries are also dropped whenever a new one is stored, so keys that
+ * are never requested again (e.g. superseded document versions) do not pile up
+ * for the lifetime of the process.
+ */
+export function createPromiseCache<T>(ttlMs = CONTENT_CACHE_TTL_MS) {
+  const entries = new Map<string, PromiseCacheEntry<T>>()
+
+  return {
+    get(
+      key: string,
+      load: () => Promise<T>,
+      shouldCache: (value: T) => boolean = () => true
+    ): Promise<T> {
+      const cached = entries.get(key)
+      if (cached && cached.expiresAt > Date.now()) {
+        return cached.promise
+      }
+
+      const evict = () => {
+        if (entries.get(key)?.promise === promise) {
+          entries.delete(key)
+        }
+      }
+
+      const now = Date.now()
+      entries.forEach((entry, entryKey) => {
+        if (entry.expiresAt <= now) entries.delete(entryKey)
+      })
+
+      const promise = load().then(
+        (value) => {
+          if (!shouldCache(value)) evict()
+          return value
+        },
+        (err: unknown) => {
+          evict()
+          throw err
+        }
+      )
+
+      entries.set(key, { expiresAt: now + ttlMs, promise })
+
+      return promise
+    },
+
+    clear() {
+      entries.clear()
+    },
+
+    get size() {
+      return entries.size
+    },
+  }
+}

package/src/server/content/service.ts

@@ -15,23 +15,24 @@ import MissingContentError from 'src/sdk/error/MissingContentError'
 import { getPDP, type PDPContentType } from '../cms/pdp'
 import MultipleContentError from 'src/sdk/error/MultipleContentError'
 import type { ServerProductQueryQuery } from '@generated/graphql'
+import { createPromiseCache } from './promiseCache'
 import { isBranchPreview, isContentPlatformSource } from './utils'
 
 type ContentResult = ContentData | (ContentEntry & PageContentType)
 
-type ContentListCacheEntry = {
-  expiresAt: number
-  promise: Promise<{ data: ContentResult[] }>
-}
-
-// Bounds how stale the template list can get in long-lived processes (ISR);
-// a CMS publish already triggers a new build.
-const CONTENT_LIST_CACHE_TTL_MS = 5 * 60 * 1000
+const OPTIONAL_CONTENT_TYPES = [
+  'globalHeaderSections',
+  'globalFooterSections',
+] as const
 
 export class ContentService {
   private clientCP: ClientCP
 
-  private readonly contentListCache = new Map<string, ContentListCacheEntry>()
+  private readonly contentListCache = createPromiseCache<{
+    data: ContentResult[]
+  }>()
+
+  private readonly firstEntryCache = createPromiseCache<PageContentType>()
 
   constructor() {
     this.clientCP = new ClientCP({
@@ -47,7 +48,7 @@ export class ContentService {
     if (isContentPlatformSource()) {
       return this.getFromCP<T>(options)
     }
-    return getPage(options.cmsOptions)
+    return getPage(options.cmsOptions, { cache: !options.isPreview })
   }
 
   async getMultipleContent(
@@ -118,10 +119,15 @@ export class ContentService {
     options: ContentOptions
   ): Promise<T> {
     const params = this.convertOptionsToParams(options)
+    // Filters are forwarded to listEntries, so a filtered lookup is not shared.
+    const shareable =
+      !options.isPreview &&
+      !('filters' in options.cmsOptions && options.cmsOptions.filters)
     try {
       const entry: PageContentType = await this.getEntry(
         params,
-        options.isPreview
+        options.isPreview,
+        shareable
       )
       return entry as T
     } catch (err: unknown) {
@@ -133,30 +139,9 @@ export class ContentService {
   private getCachedContentList(
     serviceParams: EntryPathParams
   ): Promise<{ data: ContentResult[] }> {
-    // listEntries only depends on these fields; the page slug must stay out of the key.
-    const { accountName, storeId, contentType, locale } = serviceParams
-    const key = JSON.stringify([accountName, storeId, contentType, locale])
-
-    const cached = this.contentListCache.get(key)
-    if (cached && cached.expiresAt > Date.now()) {
-      return cached.promise
-    }
-
-    const promise = this.listAndFillEntries(serviceParams, false).catch(
-      (err: unknown) => {
-        if (this.contentListCache.get(key)?.promise === promise) {
-          this.contentListCache.delete(key)
-        }
-        throw err
-      }
+    return this.contentListCache.get(getContentTypeKey(serviceParams), () =>
+      this.listAndFillEntries(serviceParams, false)
     )
-
-    this.contentListCache.set(key, {
-      expiresAt: Date.now() + CONTENT_LIST_CACHE_TTL_MS,
-      promise,
-    })
-
-    return promise
   }
 
   private async listAndFillEntries(
@@ -203,11 +188,24 @@ export class ContentService {
 
   private async getEntry(
     params: EntryPathParams,
-    isPreview: boolean
+    isPreview: boolean,
+    shareable: boolean
   ): Promise<PageContentType> {
-    return params.entryId || params.slug
-      ? await this.getEntryData(params, isPreview)
-      : await this.fetchFirstEntryFromList(params, isPreview)
+    if (params.entryId || params.slug) {
+      return this.getEntryData(params, isPreview)
+    }
+
+    if (!shareable) {
+      return this.fetchFirstEntryFromList(params, isPreview)
+    }
+
+    // An empty required type is likely content that is about to be published,
+    // so it is not kept for the whole TTL. Optional types are empty by design.
+    return this.firstEntryCache.get(
+      getContentTypeKey(params),
+      () => this.fetchFirstEntryFromList(params, false),
+      (entry) => !isEmptyEntry(entry) || isOptionalContentType(params)
+    )
   }
 
   private async getEntryData(
@@ -338,6 +336,26 @@ export class ContentService {
   }
 }
 
+function isOptionalContentType({ contentType }: EntryPathParams): boolean {
+  return OPTIONAL_CONTENT_TYPES.includes(
+    contentType as (typeof OPTIONAL_CONTENT_TYPES)[number]
+  )
+}
+
+function isEmptyEntry(entry: PageContentType): boolean {
+  return Object.keys(entry).length === 0
+}
+
+// listEntries only depends on these fields; the page slug must stay out of the key.
+function getContentTypeKey({
+  accountName,
+  storeId,
+  contentType,
+  locale,
+}: EntryPathParams): string {
+  return JSON.stringify([accountName, storeId, contentType, locale])
+}
+
 function isNotFoundError(err: unknown): boolean {
   if (err instanceof MissingContentError) return true
   if (err instanceof Error && /\b404\b/.test(err.message)) return true

package/test/server/cms/index.test.ts

@@ -1,4 +1,9 @@
-import { clientCMS, getCMSPage } from '../../../src/server/cms'
+import {
+  clientCMS,
+  cmsPageCache,
+  getCMSPage,
+  getPage,
+} from '../../../src/server/cms'
 import { jest } from '@jest/globals'
 import type { ContentData } from '@vtex/client-cms'
 
@@ -18,15 +23,32 @@ describe('CMS Integration', () => {
     return data
   }
 
+  const mockListing = (count = 1) => {
+    const mockFunction: jest.Mock<typeof clientCMS.getCMSPagesByContentType> =
+      jest.fn()
+    mockFunction.mockImplementation(() =>
+      Promise.resolve({
+        data: mockData(count),
+        hasNextPage: false,
+        totalItems: count,
+      })
+    )
+    return mockFunction
+  }
+
+  const mockLocator = () => {
+    const mockFunction: jest.Mock<typeof clientCMS.getCMSPage> = jest.fn()
+    mockFunction.mockImplementation(() => Promise.resolve(mockData(1)[0]))
+    return mockFunction
+  }
+
+  beforeEach(() => {
+    cmsPageCache.clear()
+  })
+
   describe('getCMSPage', () => {
     it('returns the first page if there is only one page', async () => {
-      const mockFunction = jest.fn(() => {
-        return Promise.resolve({
-          data: mockData(3),
-          hasNextPage: false,
-          totalItems: 3,
-        })
-      })
+      const mockFunction = mockListing(3)
       clientCMS.getCMSPagesByContentType = mockFunction
 
       const result = await getCMSPage({ contentType: 'plp' }, clientCMS)
@@ -62,4 +84,86 @@ describe('CMS Integration', () => {
       expect(result.data.length).toBe(15)
     })
   })
+
+  describe('cache', () => {
+    it('shares a content type listing across concurrent callers', async () => {
+      const mockFunction = mockListing(3)
+      clientCMS.getCMSPagesByContentType = mockFunction
+
+      await Promise.all([
+        getCMSPage({ contentType: 'plp' }),
+        getCMSPage({ contentType: 'plp' }),
+        getCMSPage({ contentType: 'plp' }),
+      ])
+      await getCMSPage({ contentType: 'pdp' })
+
+      expect(
+        mockFunction.mock.calls.map(([contentType]) => contentType)
+      ).toEqual(['plp', 'pdp'])
+    })
+
+    it('does not cache filtered listings', async () => {
+      const mockFunction = mockListing(1)
+      clientCMS.getCMSPagesByContentType = mockFunction
+      const options = {
+        contentType: 'landingPage',
+        filters: { filters: { 'settings.seo.slug': '/summer-sale' } },
+      }
+
+      await getCMSPage(options)
+      await getCMSPage(options)
+
+      expect(mockFunction).toHaveBeenCalledTimes(2)
+    })
+
+    it('fetches a locator on every call by default', async () => {
+      const mockFunction = mockLocator()
+      clientCMS.getCMSPage = mockFunction
+      const locator = {
+        contentType: 'globalSections',
+        documentId: 'doc-1',
+        versionId: 'version-1',
+      }
+
+      await getPage(locator)
+      await getPage(locator)
+
+      expect(mockFunction).toHaveBeenCalledTimes(2)
+    })
+
+    it('reuses a locator fetch when caching is enabled', async () => {
+      const mockFunction = mockLocator()
+      clientCMS.getCMSPage = mockFunction
+      const locator = {
+        contentType: 'globalSections',
+        documentId: 'doc-1',
+        versionId: 'version-1',
+      }
+
+      const [first, second] = await Promise.all([
+        getPage(locator, { cache: true }),
+        getPage(locator, { cache: true }),
+      ])
+      await getPage({ ...locator, versionId: 'version-2' }, { cache: true })
+
+      expect(first).toEqual(second)
+      expect(mockFunction).toHaveBeenCalledTimes(2)
+    })
+
+    it('does not cache failures', async () => {
+      const error = new Error('Request failed with status code 500')
+      const mockFunction: jest.Mock<typeof clientCMS.getCMSPagesByContentType> =
+        jest.fn()
+      mockFunction
+        .mockRejectedValueOnce(error)
+        .mockResolvedValueOnce({ data: mockData(1), totalItems: 1 } as never)
+      clientCMS.getCMSPagesByContentType = mockFunction
+
+      await expect(getCMSPage({ contentType: 'plp' })).rejects.toBe(error)
+      const result = await getCMSPage({ contentType: 'plp' })
+
+      expect(result.data).toHaveLength(1)
+      expect(mockFunction).toHaveBeenCalledTimes(2)
+    })
+  })
 })