@platformatic/next 3.71.1-alpha.0 → 3.73.0-alpha.0

package/eslint.config.js

@@ -1,5 +1,7 @@
+import { globalIgnores } from 'eslint/config'
 import neostandard from 'neostandard'
 
-export default neostandard({
-  ignores: ['**/.next', '**/dist', '**/tmp', 'test/fixtures/**'],
-})
+export default [
+  ...neostandard(),
+  globalIgnores(['**/.next', '**/dist', '**/tmp', 'test/fixtures/**'])
+]

package/lib/caching/valkey-common.js

@@ -7,9 +7,11 @@ import {
   getRoot,
   getValkeyClients,
   getWorkerId,
+  isBuilding,
   updateGlobals
 } from '@platformatic/globals'
 import { existsSync, readFileSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
 import { hostname } from 'node:os'
 import { resolve } from 'node:path'
@@ -112,12 +114,60 @@ export function createPlatformaticLogger () {
   return pino(pinoOptions)
 }
 
+// The subprefix is the build ID. During a build it is null until Next.js writes the ID,
+// so that nothing is stored under a subprefix the application will never read.
 export function getPlatformaticSubprefix () {
-  const root = fileURLToPath(getRoot())
+  const buildIdPath = resolve(fileURLToPath(getRoot()), '.next/BUILD_ID')
 
-  return existsSync(resolve(root, '.next/BUILD_ID'))
-    ? readFileSync(resolve(root, '.next/BUILD_ID'), 'utf-8').trim()
-    : 'development'
+  if (existsSync(buildIdPath)) {
+    return readFileSync(buildIdPath, 'utf-8').trim()
+  }
+
+  return isBuilding({ throwOnMissing: false }) ? null : 'development'
+}
+
+// Maps each "use cache" function ID to the file defining it, relative to the application.
+export async function loadCacheFunctionsFiles () {
+  const nextDir = resolve(fileURLToPath(getRoot()), '.next')
+  const files = new Map()
+
+  const [manifest, serverFiles] = await Promise.all([
+    readJSON(resolve(nextDir, 'server/server-reference-manifest.json')),
+    readJSON(resolve(nextDir, 'required-server-files.json'))
+  ])
+
+  if (!manifest || !serverFiles) {
+    return files
+  }
+
+  // Turbopack reports files relative to the workspace root, which can contain the application
+  const appPrefix = serverFiles.relativeAppDir ? serverFiles.relativeAppDir + '/' : ''
+
+  for (const [id, { filename }] of Object.entries(manifest.node ?? {})) {
+    if (filename) {
+      files.set(id, filename.startsWith(appPrefix) ? filename.slice(appPrefix.length) : filename)
+    }
+  }
+
+  return files
+}
+
+// Returns null when the file does not exist, like in development.
+async function readJSON (path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf-8'))
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      return null
+    }
+    throw e
+  }
+}
+
+// The cache key is the React-encoded list of the function ID, its arguments and other parts.
+// The ID, a 42 characters hexadecimal string, is the first one of its kind in the key.
+export function getCacheFunctionId (cacheKey) {
+  return cacheKey.match(/"([0-9a-f]{42})"/)?.[1]
 }
 
 export function getPlatformaticMeta () {

package/lib/caching/valkey-components-remote.js

@@ -11,7 +11,8 @@ export const CACHE_MISS_METRIC = {
 
 export const sections = {
   values: 'remote:components:values',
-  tags: 'remote:components:tags'
+  tags: 'remote:components:tags',
+  revalidations: 'remote:components:revalidations'
 }
 
 export default new CacheHandler({

package/lib/caching/valkey-components.js

@@ -6,10 +6,12 @@ import {
   deserialize,
   ensureMsgpackr,
   ensureRedis,
+  getCacheFunctionId,
   getConnection,
   getPlatformaticMeta,
   getPlatformaticSubprefix,
   keyFor,
+  loadCacheFunctionsFiles,
   serialize
 } from './valkey-common.js'
 
@@ -22,10 +24,12 @@ export const CACHE_MISS_METRIC = {
   help: 'Next.js Components Cache (Valkey) Miss Count'
 }
 export const MAX_BATCH_SIZE = 100
+export const IMPLICIT_TAG_PREFIX = '_N_T_'
 
 export const sections = {
   values: 'components:values',
-  tags: 'components:tags'
+  tags: 'components:tags',
+  revalidations: 'components:revalidations'
 }
 
 export class CacheHandler {
@@ -35,6 +39,7 @@ export class CacheHandler {
   #prefix
   #subprefix
   #meta
+  #cacheFunctionsFiles
   #maxTTL
   #sections
   #cacheHitMetric
@@ -82,6 +87,10 @@ export class CacheHandler {
   async get (cacheKey, _, isRedisKey) {
     this.#logger.trace({ key: cacheKey }, 'cache get')
 
+    if (!isRedisKey && !this.#hasSubprefix()) {
+      return
+    }
+
     const key = isRedisKey ? cacheKey : this.#keyFor(cacheKey, this.#sections.values)
 
     let rawValue
@@ -143,8 +152,6 @@ export class CacheHandler {
 
     this.#logger.trace({ key: cacheKey, value, tags, revalidate }, 'cache set')
 
-    const key = isRedisKey ? cacheKey : this.#keyFor(cacheKey, this.#sections.values)
-
     try {
       // Gather the value
       const chunks = []
@@ -152,10 +159,24 @@ export class CacheHandler {
         chunks.push(chunk)
       }
 
+      if (!isRedisKey && !this.#hasSubprefix()) {
+        return
+      }
+
+      const key = isRedisKey ? cacheKey : this.#keyFor(cacheKey, this.#sections.values)
+
       // Compute the parameters to save
+
+      const file = await this.#fileFor(cacheKey)
+
+      let meta = this.#meta
+      if (file) {
+        meta = { ...meta, file }
+      }
+
       const toSerialize = serialize({
         maxTTL: this.#maxTTL,
-        meta: this.#meta,
+        meta,
         value: Buffer.concat(chunks),
         ...data
       })
@@ -193,12 +214,39 @@ export class CacheHandler {
   // This function is not necessary as we don't have a local state to synchronize.
   async refreshTags () {}
 
-  getExpiration (_tags) {
-    // Delegates the check to get method, only when appropriate.
-    return Number.POSITIVE_INFINITY
+  // Next.js calls this with the implicit tags of the current request (the ones revalidatePath()
+  // targets) and discards any entry created before the returned timestamp.
+  async getExpiration (tags) {
+    if (!tags?.length || !this.#hasSubprefix()) {
+      return 0
+    }
+
+    try {
+      const keys = tags.map(tag => this.#keyFor(tag, this.#sections.revalidations))
+      const timestamps = await this.#store.mget(keys)
+
+      let expiration = 0
+      for (const timestamp of timestamps) {
+        if (timestamp) {
+          expiration = Math.max(expiration, Number(timestamp))
+        }
+      }
+
+      return expiration
+    } catch (e) {
+      this.#logger.error(
+        { err: ensureLoggableError(e) },
+        'Cannot read cache tags expiration from Valkey'
+      )
+      return 0
+    }
   }
 
   async updateTags (tags) {
+    if (!this.#hasSubprefix()) {
+      return
+    }
+
     if (typeof tags === 'string') {
       tags = [tags]
     }
@@ -207,6 +255,17 @@ export class CacheHandler {
       const toDelete = new Set()
 
       for (const tag of tags) {
+        // Implicit tags are never attached to entries, so there is nothing to delete.
+        // Record when they were revalidated instead, getExpiration() will check it.
+        if (tag.startsWith(IMPLICIT_TAG_PREFIX)) {
+          if (this.#maxTTL >= 1) {
+            const revalidationKey = this.#keyFor(tag, this.#sections.revalidations)
+            await this.#store.set(revalidationKey, Date.now(), 'EX', this.#maxTTL)
+          }
+
+          continue
+        }
+
         const tagsKey = this.#keyFor(tag, this.#sections.tags)
 
         // For each key in the tag set, expire the key
@@ -256,6 +315,26 @@ export class CacheHandler {
     await Promise.all(promises)
   }
 
+  // The manifest is read once, on the first write
+  async #fileFor (cacheKey) {
+    this.#cacheFunctionsFiles ??= loadCacheFunctionsFiles().catch(e => {
+      this.#logger.error(
+        { err: ensureLoggableError(e) },
+        'Cannot read the server references manifest'
+      )
+      return new Map()
+    })
+
+    const files = await this.#cacheFunctionsFiles
+    return files.get(getCacheFunctionId(cacheKey))
+  }
+
+  // During a build, the subprefix is only known once Next.js writes the build ID
+  #hasSubprefix () {
+    this.#subprefix ??= getPlatformaticSubprefix()
+    return this.#subprefix !== null
+  }
+
   #keyFor (key, section) {
     return keyFor(this.#prefix, this.#subprefix, section, key)
   }

package/lib/caching/valkey-isr.js

@@ -88,6 +88,10 @@ export class CacheHandler {
   async get (cacheKey, _, isRedisKey) {
     this.#logger.trace({ key: cacheKey }, 'cache get')
 
+    if (!isRedisKey && !this.#hasSubprefix()) {
+      return
+    }
+
     const key = this.#standalone || isRedisKey ? cacheKey : this.#keyFor(cacheKey, sections.values)
 
     let rawValue
@@ -134,6 +138,10 @@ export class CacheHandler {
   }
 
   async set (cacheKey, value, ctx, isRedisKey) {
+    if (!isRedisKey && !this.#hasSubprefix()) {
+      return
+    }
+
     const tags = this.#getTags(ctx.tags, value)
     const revalidate = ctx.revalidate ?? ctx.cacheControl?.revalidate ?? value.revalidate ?? 0
 
@@ -181,6 +189,10 @@ export class CacheHandler {
   }
 
   async remove (cacheKey, isRedisKey) {
+    if (!isRedisKey && !this.#hasSubprefix()) {
+      return
+    }
+
     this.#logger.trace({ key: cacheKey }, 'cache remove')
 
     const key = this.#standalone || isRedisKey ? cacheKey : this.#keyFor(cacheKey, sections.values)
@@ -231,6 +243,10 @@ export class CacheHandler {
   }
 
   async revalidateTag (tags) {
+    if (!this.#hasSubprefix()) {
+      return
+    }
+
     this.#logger.trace({ tags }, 'cache revalidateTag')
 
     if (typeof tags === 'string') {
@@ -309,6 +325,12 @@ export class CacheHandler {
     await Promise.all(promises)
   }
 
+  // During a build, the subprefix is only known once Next.js writes the build ID
+  #hasSubprefix () {
+    this.#subprefix ??= getPlatformaticSubprefix()
+    return this.#subprefix !== null
+  }
+
   #keyFor (key, section) {
     return keyFor(this.#prefix, this.#subprefix, section, key)
   }

package/lib/capability.js

@@ -21,6 +21,8 @@ import { parseStandaloneNextConfig, requireStandaloneStartServer, resolveStandal
 
 export const supportedVersions = ['^14.0.0', '^15.0.0', '^16.0.0']
 
+const loaderOptions = { registerHooks: true }
+
 export function getCacheHandlerPath (name) {
   return fileURLToPath(new URL(`./caching/${name}.js`, import.meta.url)).replaceAll(sep, '/')
 }
@@ -166,7 +168,7 @@ export class NextCapability extends BaseCapability {
       command = ['node', resolvePath(this.#next, './dist/bin/next'), 'build', this.root]
     }
 
-    await this.buildWithCommand(command, this.#basePath, { loader, scripts: this.#getChildManagerScripts() })
+    await this.buildWithCommand(command, this.#basePath, { loader, loaderOptions, scripts: this.#getChildManagerScripts() })
     await this.#fixRequiredServerFiles()
   }
 
@@ -208,7 +210,7 @@ export class NextCapability extends BaseCapability {
     this.#basePath = config.application?.basePath ? cleanBasePath(config.application?.basePath) : ''
 
     if (command) {
-      return this.startWithCommand(command, loaderUrl, this.#getChildManagerScripts())
+      return this.startWithCommand(command, loaderUrl, this.#getChildManagerScripts(), { loaderOptions })
     }
 
     const { hostname, port } = this.serverConfig ?? {}
@@ -321,7 +323,7 @@ export class NextCapability extends BaseCapability {
       if (this.#nextVersion.major < 15 || (this.#nextVersion.major <= 15 && this.#nextVersion.minor < 1)) {
         childManagerScripts.push(new URL('./create-context-patch.js', import.meta.url))
       }
-      return this.startWithCommand(command, loaderUrl, childManagerScripts)
+      return this.startWithCommand(command, loaderUrl, childManagerScripts, { loaderOptions })
     }
 
     this.childManager = this.#createChildManager(
@@ -512,6 +514,7 @@ export class NextCapability extends BaseCapability {
   #createChildManager (loader, context, scripts) {
     const childManager = new ChildManager({
       loader,
+      loaderOptions,
       context,
       scripts
     })

package/lib/loader.js

@@ -10,6 +10,7 @@ import {
   variableDeclaration,
   variableDeclarator
 } from '@babel/types'
+import { readFileSync, realpathSync } from 'node:fs'
 import { readFile, realpath } from 'node:fs/promises'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
@@ -86,8 +87,8 @@ export function transformESM (source) {
   return generate.default(ast).code
 }
 
-export async function initialize (data) {
-  const realRoot = pathToFileURL(await realpath(fileURLToPath(data.root)))
+function initializeCandidates (data, realRootPath) {
+  const realRoot = pathToFileURL(realRootPath)
 
   if (!realRoot.pathname.endsWith('/')) {
     realRoot.pathname += '/'
@@ -100,6 +101,38 @@ export async function initialize (data) {
   candidates = candidates.map(c => new URL(c, realRoot).toString())
 }
 
+export function initializeSync (data) {
+  initializeCandidates(data, realpathSync(fileURLToPath(data.root)))
+}
+
+export async function initialize (data) {
+  initializeCandidates(data, await realpath(fileURLToPath(data.root)))
+}
+
+export function loadSync (url, context, nextLoad) {
+  // Load the original file
+  const result = nextLoad(url, context)
+
+  if (!url.startsWith('file:')) {
+    return result
+  }
+
+  url = pathToFileURL(realpathSync(fileURLToPath(url))).toString()
+
+  if (!candidates.includes(url)) {
+    return result
+  }
+
+  if (result.format === 'commonjs' || result.format == null) {
+    result.format ??= 'commonjs'
+    result.source = transformCJS(result.source ?? readFileSync(new URL(result.responseURL ?? url), 'utf-8'))
+  } else {
+    result.source = transformESM(result.source)
+  }
+
+  return result
+}
+
 export async function load (url, context, nextLoad) {
   // Load the original file
   const result = await nextLoad(url, context)
@@ -114,8 +147,8 @@ export async function load (url, context, nextLoad) {
     return result
   }
 
-  if (result.format === 'commonjs') {
-    await readFile(new URL(result.responseURL ?? url), 'utf-8')
+  if (result.format === 'commonjs' || result.format == null) {
+    result.format ??= 'commonjs'
     result.source = transformCJS(result.source ?? (await readFile(new URL(result.responseURL ?? url), 'utf-8')))
   } else {
     result.source = transformESM(result.source)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/next",
-  "version": "3.71.1-alpha.0",
+  "version": "3.73.0-alpha.0",
   "description": "Platformatic Next.js Capability",
   "main": "index.js",
   "type": "module",
@@ -19,33 +19,33 @@
     "@babel/parser": "^7.25.3",
     "@babel/traverse": "^7.25.3",
     "@babel/types": "^7.25.2",
+    "@platformatic/basic": "3.73.0-alpha.0",
+    "@platformatic/foundation": "3.73.0-alpha.0",
+    "@platformatic/globals": "3.73.0-alpha.0",
     "@platformatic/image-optimizer": "^0.2.1",
     "amaro": "^1.0.0",
-    "iovalkey": "^0.3.0",
+    "iovalkey": "^0.4.0",
     "light-my-request": "^6.0.0",
     "msgpackr": "^1.11.2",
-    "semver": "^7.6.3",
-    "@platformatic/basic": "3.71.1-alpha.0",
-    "@platformatic/foundation": "3.71.1-alpha.0",
-    "@platformatic/globals": "3.71.1-alpha.0"
+    "semver": "^7.6.3"
   },
   "devDependencies": {
     "@fastify/reply-from": "^12.0.0",
+    "@platformatic/gateway": "3.73.0-alpha.0",
+    "@platformatic/service": "3.73.0-alpha.0",
     "@types/node": "^22.5.0",
     "@types/react": "^19.1.11",
     "@types/react-dom": "^19.1.7",
-    "cleaner-spec-reporter": "^0.5.0",
+    "cleaner-spec-reporter": "^2.0.0",
     "eslint": "9",
     "tstyche": "^7.0.0",
     "execa": "^9.5.1",
     "fastify": "^5.7.3",
     "json-schema-to-typescript": "^15.0.1",
-    "neostandard": "^0.12.0",
+    "neostandard": "^0.14.0",
     "next": "^16.1.0",
     "typescript": "~6.0.3",
-    "ws": "^8.18.0",
-    "@platformatic/service": "3.71.1-alpha.0",
-    "@platformatic/gateway": "3.71.1-alpha.0"
+    "ws": "^8.18.0"
   },
   "engines": {
     "node": ">=22.19.0"

package/schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://schemas.platformatic.dev/@platformatic/next/3.71.1-alpha.0.json",
+  "$id": "https://schemas.platformatic.dev/@platformatic/next/3.73.0-alpha.0.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Platformatic Next.js Config",
   "type": "object",