@platformatic/next 3.27.0 → 3.28.0

package/config.d.ts

@@ -499,6 +499,7 @@ export interface PlatformaticNextJsConfig {
       [k: string]: string;
     };
     sourceMaps?: boolean;
+    nodeModulesSourceMaps?: string[];
     scheduler?: {
       enabled?: boolean | string;
       name: string;
@@ -553,6 +554,7 @@ export interface PlatformaticNextJsConfig {
       };
       envfile?: string;
       sourceMaps?: boolean;
+      nodeModulesSourceMaps?: string[];
       packageManager?: "npm" | "pnpm" | "yarn";
       preload?: string | string[];
       nodeOptions?: string;
@@ -584,6 +586,7 @@ export interface PlatformaticNextJsConfig {
   };
   next?: {
     trailingSlash?: boolean;
+    useExperimentalAdapter?: boolean;
   };
   cache?: {
     adapter: "redis" | "valkey";

package/index.js

@@ -1,14 +1,9 @@
 import { transform as basicTransform, resolve, validationOptions } from '@platformatic/basic'
 import { kMetadata, loadConfiguration as utilsLoadConfiguration } from '@platformatic/foundation'
-import { sep } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { NextCapability } from './lib/capability.js'
+import { resolve as resolvePath } from 'node:path'
+import { getCacheHandlerPath, NextCapability } from './lib/capability.js'
 import { schema } from './lib/schema.js'
 
-function getCacheHandlerPath (name) {
-  return fileURLToPath(new URL(`./lib/caching/${name}.js`, import.meta.url)).replaceAll(sep, '/')
-}
-
 /* c8 ignore next 9 */
 export async function transform (config, schema, options) {
   config = await basicTransform(config, schema, options)
@@ -21,6 +16,10 @@ export async function transform (config, schema, options) {
   return config
 }
 
+export function getAdapterPath () {
+  return resolvePath(import.meta.dirname, 'lib', 'adapter.js')
+}
+
 export async function enhanceNextConfig (nextConfig, ...args) {
   // This is to avoid https://github.com/vercel/next.js/issues/76981
   Headers.prototype[Symbol.for('nodejs.util.inspect.custom')] = undefined
@@ -35,20 +34,30 @@ export async function enhanceNextConfig (nextConfig, ...args) {
     nextConfig.basePath = basePath
   }
 
+  const modifications = []
+
   if (config.cache?.adapter) {
     if (nextVersion.major > 15 && config.cache?.cacheComponents && typeof nextConfig.cacheComponents === 'undefined') {
       nextConfig.cacheComponents = true
       nextConfig.cacheHandler = getCacheHandlerPath('null-isr')
       nextConfig.cacheHandlers = { default: getCacheHandlerPath(`${config.cache.adapter}-components`) }
       nextConfig.cacheMaxMemorySize = 0
+      modifications.push(['componentsCache', config.cache.adapter])
     } else if (typeof nextConfig.cacheHandler === 'undefined') {
       nextConfig.cacheHandler = getCacheHandlerPath(`${config.cache.adapter}-isr`)
       nextConfig.cacheMaxMemorySize = 0
+      modifications.push(['isrCache', config.cache.adapter])
     }
   }
 
   if (config.next?.trailingSlash && typeof nextConfig.trailingSlash === 'undefined') {
     nextConfig.trailingSlash = true
+    modifications.push(['trailingSlash', 'enabled'])
+  }
+
+  if (modifications.length > 0) {
+    nextConfig.env ??= {}
+    nextConfig.env.PLT_NEXT_MODIFICATIONS = JSON.stringify(Object.fromEntries(modifications))
   }
 
   globalThis.platformatic.notifyConfig(nextConfig)
@@ -74,4 +83,5 @@ export async function create (configOrRoot, sourceOrConfig, context) {
 
 export * as cachingValkey from './lib/caching/valkey-isr.js'
 export * from './lib/capability.js'
+export * as errors from './lib/errors.js'
 export { packageJson, schema, schemaComponents, version } from './lib/schema.js'

package/lib/adapter.js

@@ -0,0 +1,10 @@
+import { enhanceNextConfig } from '../index.js'
+
+export const adapter = {
+  name: '@platformatic/next/adapter',
+  async modifyConfig (config) {
+    return enhanceNextConfig(config)
+  }
+}
+
+export default adapter

package/lib/capability.js

@@ -1,30 +1,37 @@
 import {
   BaseCapability,
+  errors as basicErrors,
   ChildManager,
   cleanBasePath,
   createChildProcessListener,
   createServerListener,
-  errors,
   getServerUrl,
-  importFile
+  importFile,
+  resolvePackageViaCJS
 } from '@platformatic/basic'
-import { resolvePackageViaCJS } from '@platformatic/basic/lib/utils.js'
 import { ChildProcess } from 'node:child_process'
 import { once } from 'node:events'
-import { readFile, writeFile } from 'node:fs/promises'
-import { dirname, resolve as resolvePath } from 'node:path'
+import { existsSync } from 'node:fs'
+import { glob, readFile, writeFile } from 'node:fs/promises'
+import { dirname, resolve as resolvePath, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { parse, satisfies } from 'semver'
+import * as errors from './errors.js'
 import { version } from './schema.js'
 
-const kITC = Symbol.for('plt.runtime.itc')
 const supportedVersions = ['^14.0.0', '^15.0.0', '^16.0.0']
 
+export function getCacheHandlerPath (name) {
+  return fileURLToPath(new URL(`./caching/${name}.js`, import.meta.url)).replaceAll(sep, '/')
+}
+
 export class NextCapability extends BaseCapability {
   #basePath
   #next
   #nextVersion
   #child
   #server
+  #configModified
 
   constructor (root, config, context) {
     super('next', version, root, config, context)
@@ -51,9 +58,13 @@ export class NextCapability extends BaseCapability {
       await import('./create-context-patch.js')
     }
 
+    if (this.#nextVersion.major < 16 && this.config.next?.useExperimentalAdapter === true) {
+      this.config.next.useExperimentalAdapter = false
+    }
+
     /* c8 ignore next 3 */
     if (!supportedVersions.some(v => satisfies(nextPackage.version, v))) {
-      throw new errors.UnsupportedVersion('next', nextPackage.version, supportedVersions)
+      throw new basicErrors.UnsupportedVersion('next', nextPackage.version, supportedVersions)
     }
   }
 
@@ -66,6 +77,7 @@ export class NextCapability extends BaseCapability {
     await super._start({ listen })
 
     this.on('config', config => {
+      this.#configModified = true
       this.#basePath = config.basePath
     })
 
@@ -76,6 +88,18 @@ export class NextCapability extends BaseCapability {
     }
 
     await this._collectMetrics()
+
+    if (!this.#configModified && this.config.next?.useExperimentalAdapter) {
+      this.logger.warn(
+        'The experimental Next.js adapterPath is enabled but the @platformatic/next adapter was not included.'
+      )
+      this.logger.warn(
+        'Please ensure that your next.config.js is correctly set up to use the Platformatic Next.js adapter.'
+      )
+      this.logger.warn(
+        'Refer to the documentation for more details: https://platformatic.dev/docs/reference/next/configuration#next.'
+      )
+    }
   }
 
   async stop () {
@@ -88,17 +112,7 @@ export class NextCapability extends BaseCapability {
     globalThis.platformatic.events.emit('plt:next:close')
 
     if (this.isProduction && this.#server) {
-      await new Promise((resolve, reject) => {
-        this.#server.close(error => {
-          /* c8 ignore next 3 */
-          if (error) {
-            return reject(error)
-          }
-
-          resolve()
-        })
-      })
-
+      await this._closeServer(this.#server)
       await this.childManager.close()
     } else if (this.#child) {
       const exitPromise = once(this.#child, 'exit')
@@ -125,21 +139,7 @@ export class NextCapability extends BaseCapability {
     }
 
     await this.buildWithCommand(command, this.#basePath, { loader, scripts: this.#getChildManagerScripts() })
-
-    // This is need to avoid Next.js 15.4+ to throw an error as process.cwd() is not the root of the Next.js application
-    if (
-      config.cache?.adapter &&
-      (this.#nextVersion.major > 15 || (this.#nextVersion.major === 15 && this.#nextVersion.minor >= 4))
-    ) {
-      const distDir = resolvePath(this.root, '.next')
-      const requiredServerFilesPath = resolvePath(distDir, 'required-server-files.json')
-      const requiredServerFiles = JSON.parse(await readFile(requiredServerFilesPath, 'utf-8'))
-
-      if (requiredServerFiles.config.cacheHandler) {
-        requiredServerFiles.config.cacheHandler = resolvePath(distDir, requiredServerFiles.config.cacheHandler)
-        await writeFile(requiredServerFilesPath, JSON.stringify(requiredServerFiles, null, 2))
-      }
-    }
+    await this.#fixRequiredServerFiles()
   }
 
   /* c8 ignore next 5 */
@@ -254,7 +254,12 @@ export class NextCapability extends BaseCapability {
     )
 
     this.verifyOutputDirectory(resolvePath(this.root, '.next'))
-    await this.#startProductionNext()
+
+    if (existsSync(resolvePath(this.root, '.next/standalone'))) {
+      return this.#startProductionStandaloneNext()
+    } else {
+      return this.#startProductionNext()
+    }
   }
 
   async #startProductionNext () {
@@ -294,6 +299,96 @@ export class NextCapability extends BaseCapability {
     }
   }
 
+  async #startProductionStandaloneNext () {
+    const rootDir = resolvePath(this.root, '.next', 'standalone')
+
+    // If built in standalone mode, the generated standalone directory is not on the root of the project but somewhere
+    // inside .next/standalone due to turbopack limitations in determining the root of the project.
+    // In that case we search a server.js next to a .next folder inside the .next /standalone folder.
+    const serverEntrypoints = await Array.fromAsync(
+      glob(['**/server.js'], { cwd: rootDir, ignore: ['node_modules', '**/node_modules/**'] })
+    )
+
+    let serverEntrypoint
+    for (const entrypoint of serverEntrypoints) {
+      if (existsSync(resolvePath(rootDir, dirname(entrypoint), '.next'))) {
+        serverEntrypoint = resolvePath(rootDir, entrypoint)
+        break
+      }
+    }
+
+    if (!serverEntrypoint) {
+      throw new errors.StandaloneServerNotFound()
+    }
+
+    // The default Next.js standalone server uses chdir, which is not supported in worker threads.
+    // Therefore we need to reproduce the server.js logic here, which what we do in the rest of this method.
+
+    // Parse the server.js to extract the nextConfig.
+    // For now we use simple regex parsing, if it breaks, we can switch to proper AST parsing.
+    let nextConfig
+    try {
+      const serverJsContent = await readFile(serverEntrypoint, 'utf-8')
+      const nextConfigMatch = serverJsContent.match(/(?:const|let)\s*nextConfig\s*=\s*(\{.+)/)
+      nextConfig = JSON.parse(nextConfigMatch[1])
+    } catch (e) {
+      throw new errors.CannotParseStandaloneServer({ cause: e })
+    }
+
+    // Fix cache handlers path
+    if (nextConfig.env?.PLT_NEXT_MODIFICATIONS) {
+      const pltNextModifications = JSON.parse(nextConfig.env.PLT_NEXT_MODIFICATIONS)
+
+      if (pltNextModifications.isrCache) {
+        nextConfig.cacheHandler = getCacheHandlerPath(`${pltNextModifications.isrCache}-isr`)
+      } else if (pltNextModifications.componentsCache) {
+        nextConfig.cacheHandler = getCacheHandlerPath('null-isr')
+        nextConfig.cacheHandlers.default = getCacheHandlerPath(`${pltNextModifications.componentsCache}-components`)
+      }
+    }
+
+    try {
+      await this.childManager.inject()
+      await this.childManager.register()
+
+      const { hostname, port, backlog } = this.serverConfig ?? {}
+      const serverOptions = {
+        hostname: hostname || '127.0.0.1',
+        port: port || 0
+      }
+
+      const serverPromise = createServerListener(
+        (this.isEntrypoint ? serverOptions?.port : undefined) ?? true,
+        (this.isEntrypoint ? serverOptions?.hostname : undefined) ?? true,
+        typeof backlog === 'number' ? { backlog } : {}
+      )
+
+      let keepAliveTimeout = parseInt(process.env.KEEP_ALIVE_TIMEOUT, 10)
+      if (Number.isNaN(keepAliveTimeout) || !Number.isFinite(keepAliveTimeout) || keepAliveTimeout < 0) {
+        keepAliveTimeout = undefined
+      }
+
+      // This is needed by Next.js standalone server to pick up the correct configuration
+      process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify(nextConfig)
+      const { startServer } = await importFile(resolvePath(this.#next, './dist/server/lib/start-server.js'))
+
+      await startServer({
+        dir: dirname(serverEntrypoint),
+        isDev: false,
+        config: nextConfig,
+        hostname: serverOptions.hostname,
+        port: serverOptions.port,
+        allowRetry: false,
+        keepAliveTimeout
+      })
+
+      this.#server = await serverPromise
+      this.url = getServerUrl(this.#server)
+    } finally {
+      await this.childManager.eject()
+    }
+  }
+
   #getChildManagerScripts () {
     const scripts = []
 
@@ -334,11 +429,27 @@ export class NextCapability extends BaseCapability {
       scripts
     })
 
-    childManager.on('event', event => {
-      globalThis[kITC].notify('event', event)
-      this.emit('application:worker:event:' + event.event, event.payload)
-    })
-
+    this.setupChildManagerEventsForwarding(childManager)
     return childManager
   }
+
+  async #fixRequiredServerFiles () {
+    const config = this.config
+    const distDir = resolvePath(this.root, '.next')
+
+    // This is need to avoid Next.js 15.4+ to throw an error as process.cwd() is not the root of the Next.js application
+    if (
+      config.cache?.adapter &&
+      (this.#nextVersion.major > 15 || (this.#nextVersion.major === 15 && this.#nextVersion.minor >= 4))
+    ) {
+      const requiredServerFilesPath = resolvePath(distDir, 'required-server-files.json')
+      const requiredServerFiles = JSON.parse(await readFile(requiredServerFilesPath, 'utf-8'))
+
+      if (requiredServerFiles.config.cacheHandler) {
+        requiredServerFiles.config.cacheHandler = resolvePath(distDir, requiredServerFiles.config.cacheHandler)
+        await writeFile(requiredServerFilesPath, JSON.stringify(requiredServerFiles, null, 2))
+      }
+    }
+    return distDir
+  }
 }

package/lib/errors.js

@@ -0,0 +1,13 @@
+import createError from '@fastify/error'
+
+export const ERROR_PREFIX = 'PLT_NEXT'
+
+export const StandaloneServerNotFound = createError(
+  `${ERROR_PREFIX}_CANNOT_FIND_STANDALONE_SERVER`,
+  'Cannot find server.js entrypoint in .next/standalone.'
+)
+
+export const CannotParseStandaloneServer = createError(
+  `${ERROR_PREFIX}_CANNOT_PARSE_STANDALONE_SERVER`,
+  'Cannot parse nextConfig from standalone server.js.'
+)

package/lib/loader-next-15.cjs

@@ -40,13 +40,18 @@ fsPromises.readFile = async function readAndPatchNextConfigTS (url, options) {
     return contents
   }
 
-  const { code } = transformSync(contents.toString('utf-8'), { mode: 'strip-only' })
+  let transformed = contents
 
-  const { transformESM, transformCJS } = await import('./loader.js')
-  const transformer = detectFormat(code) === 'esm' ? transformESM : transformCJS
-  const transformed = transformer(code)
+  if (!globalThis.platformatic.config.next?.useExperimentalAdapter) {
+    const { code } = transformSync(contents.toString('utf-8'), { mode: 'strip-only' })
+
+    const { transformESM, transformCJS } = await import('./loader.js')
+    const transformer = detectFormat(code) === 'esm' ? transformESM : transformCJS
+    transformed = transformer(code)
+
+    // Restore the original method
+    fsPromises.readFile = originalReadFile
+  }
 
-  // Restore the original method
-  fsPromises.readFile = originalReadFile
   return transformed
 }

package/lib/loader.js

@@ -93,6 +93,10 @@ export async function initialize (data) {
     realRoot.pathname += '/'
   }
 
+  if (data.config.next?.useExperimentalAdapter === true) {
+    return
+  }
+
   candidates = candidates.map(c => new URL(c, realRoot).toString())
 }
 

package/lib/schema.js

@@ -45,6 +45,10 @@ const next = {
     trailingSlash: {
       type: 'boolean',
       default: false
+    },
+    useExperimentalAdapter: {
+      type: 'boolean',
+      default: false
     }
   },
   default: {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/next",
-  "version": "3.27.0",
+  "version": "3.28.0",
   "description": "Platformatic Next.js Capability",
   "main": "index.js",
   "type": "module",
@@ -23,8 +23,8 @@
     "iovalkey": "^0.3.0",
     "msgpackr": "^1.11.2",
     "semver": "^7.6.3",
-    "@platformatic/foundation": "3.27.0",
-    "@platformatic/basic": "3.27.0"
+    "@platformatic/basic": "3.28.0",
+    "@platformatic/foundation": "3.28.0"
   },
   "devDependencies": {
     "@fastify/reply-from": "^12.0.0",
@@ -40,8 +40,8 @@
     "next": "^16.0.0",
     "typescript": "^5.5.4",
     "ws": "^8.18.0",
-    "@platformatic/service": "3.27.0",
-    "@platformatic/gateway": "3.27.0"
+    "@platformatic/gateway": "3.28.0",
+    "@platformatic/service": "3.28.0"
   },
   "engines": {
     "node": ">=22.19.0"

package/schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://schemas.platformatic.dev/@platformatic/next/3.27.0.json",
+  "$id": "https://schemas.platformatic.dev/@platformatic/next/3.28.0.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Platformatic Next.js Config",
   "type": "object",
@@ -593,6 +593,12 @@
               "sourceMaps": {
                 "type": "boolean"
               },
+              "nodeModulesSourceMaps": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
               "packageManager": {
                 "type": "string",
                 "enum": [
@@ -1839,6 +1845,13 @@
           "type": "boolean",
           "default": false
         },
+        "nodeModulesSourceMaps": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        },
         "scheduler": {
           "type": "array",
           "items": {
@@ -2092,6 +2105,12 @@
             "sourceMaps": {
               "type": "boolean"
             },
+            "nodeModulesSourceMaps": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
             "packageManager": {
               "type": "string",
               "enum": [
@@ -2194,6 +2213,10 @@
         "trailingSlash": {
           "type": "boolean",
           "default": false
+        },
+        "useExperimentalAdapter": {
+          "type": "boolean",
+          "default": false
         }
       },
       "default": {},