@platformatic/next 3.72.0 → 4.0.0-alpha.1

package/index.d.ts

@@ -1,4 +1,4 @@
-import { BaseCapability, BaseContext, BaseOptions } from '@platformatic/basic'
+import { ApplicationDefinition, BaseCapability, BaseContext, BaseOptions, CapabilityFactoryOptions, ConfigContext, DeferredApplicationDefinition } from '@platformatic/basic'
 import { Configuration, ConfigurationOptions } from '@platformatic/foundation'
 import { JSONSchemaType } from 'ajv'
 import { FastifyError } from 'fastify'
@@ -6,6 +6,26 @@ import type { PlatformaticNextJsConfig } from './config.d.ts'
 
 export type { PlatformaticNextJsConfig } from './config.d.ts'
 
+/*
+  The option types this capability's configuration is built from, generated from the audited schema.
+  `NextHttpsOptions` is Next's own and sits next to `AppServerOptions['https']`, which is
+  `HttpsOptions`: two adjacent keys spelled almost alike, which is exactly why both have names.
+*/
+export type {
+  AppLoggerOptions,
+  AppServerOptions,
+  ApplicationHealthOptions,
+  ApplicationTelemetryOverrides,
+  ApplicationWorkersOptions,
+  BuildableApplicationOptions,
+  HttpsOptions,
+  ImageOptimizerOptions,
+  NextCacheOptions,
+  NextHttpsOptions,
+  PermissionsOptions,
+  WatchOptions
+} from './config.d.ts'
+
 export interface NextContext extends BaseContext {}
 
 export type NextConfiguration = Configuration<PlatformaticNextJsConfig>
@@ -55,3 +75,10 @@ export namespace errors {
   export const StandaloneServerNotFound: () => FastifyError
   export const CannotParseStandaloneServer: () => FastifyError
 }
+
+export type NextConfigOptions = CapabilityFactoryOptions<PlatformaticNextJsConfig, 'next', never>
+
+export declare function createNextConfig (options?: NextConfigOptions): ApplicationDefinition
+export declare function createNextConfig (
+  callback: (context: ConfigContext) => NextConfigOptions | Promise<NextConfigOptions>
+): DeferredApplicationDefinition

package/index.js

@@ -57,6 +57,25 @@ function enhanceNextCacheConfig (nextConfig, modifications) {
   }
 }
 
+function externalizeGlobals (nextConfig, nextVersion) {
+  const packageName = '@platformatic/globals'
+
+  if (nextVersion.major >= 15) {
+    nextConfig.serverExternalPackages ??= []
+
+    if (!nextConfig.serverExternalPackages.includes(packageName)) {
+      nextConfig.serverExternalPackages.push(packageName)
+    }
+  } else {
+    nextConfig.experimental ??= {}
+    nextConfig.experimental.serverComponentsExternalPackages ??= []
+
+    if (!nextConfig.experimental.serverComponentsExternalPackages.includes(packageName)) {
+      nextConfig.experimental.serverComponentsExternalPackages.push(packageName)
+    }
+  }
+}
+
 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
@@ -67,8 +86,11 @@ export async function enhanceNextConfig (nextConfig, ...args) {
 
   const basePath = getBasePath()
   const config = getConfig()
+  const nextVersion = getNextVersion()
   const notifyConfig = getNotifyConfig()
 
+  externalizeGlobals(nextConfig, nextVersion)
+
   if (typeof nextConfig.basePath === 'undefined') {
     nextConfig.basePath = basePath
   }
@@ -109,3 +131,5 @@ export * from './lib/config.js'
 export * as errors from './lib/errors.js'
 export * from './lib/image-optimizer.js'
 export { packageJson, schema, schemaComponents, version } from './lib/schema.js'
+
+export * from './lib/factory.js'

package/lib/caching/valkey-isr.js

@@ -16,8 +16,6 @@ export const CACHE_HIT_METRIC = { name: 'next_cache_valkey_hit_count', help: 'Ne
 export const CACHE_MISS_METRIC = { name: 'next_cache_valkey_miss_count', help: 'Next.js Cache (Valkey) Miss Count' }
 export const MAX_BATCH_SIZE = 100
 
-const NEXT_CACHE_TAGS_HEADER = 'x-next-cache-tags'
-
 export const sections = {
   values: 'values',
   tags: 'tags'
@@ -101,7 +99,7 @@ export class CacheHandler {
     } catch (e) {
       this.#cacheMissMetric?.inc()
       this.#logger.error({ err: ensureLoggableError(e) }, 'Cannot read cache value from Valkey')
-      return
+      throw new Error('Cannot read cache value from Valkey', { cause: e })
     }
 
     let value
@@ -134,7 +132,7 @@ export class CacheHandler {
   }
 
   async set (cacheKey, value, ctx, isRedisKey) {
-    const tags = this.#getTags(ctx.tags, value)
+    const tags = ctx.tags
     const revalidate = ctx.revalidate ?? ctx.cacheControl?.revalidate ?? value.revalidate ?? 0
 
     this.#logger.trace({ key: cacheKey, value, tags, revalidate }, 'cache set')
@@ -269,25 +267,6 @@ export class CacheHandler {
     }
   }
 
-  #getTags (tags, value) {
-    // Next.js stores page and route tags in this header instead of ctx.tags.
-    const tagsHeader = value?.headers?.[NEXT_CACHE_TAGS_HEADER]
-
-    if (typeof tagsHeader !== 'string') {
-      return tags
-    }
-
-    const combinedTags = new Set(tags)
-
-    for (const tag of tagsHeader.split(',')) {
-      if (tag) {
-        combinedTags.add(tag)
-      }
-    }
-
-    return [...combinedTags]
-  }
-
   async #refreshKey (key, value) {
     const life = Math.round((Date.now() - value.lastModified) / 1000)
     const expire = Math.min(value.revalidate - life, this.#maxTTL)

package/lib/capability.js

@@ -75,13 +75,8 @@ export class NextCapability extends BaseCapability {
     }
   }
 
-  async start ({ listen }) {
-    // Make this idempotent
-    if (this.url) {
-      return this.url
-    }
-
-    await super._start({ listen })
+  async _start () {
+    await super._start()
 
     this.on('config', config => {
       this.#configModified = true
@@ -89,9 +84,9 @@ export class NextCapability extends BaseCapability {
     })
 
     if (this.isProduction) {
-      await this.#startProduction(listen)
+      await this.#startProduction()
     } else {
-      await this.#startDevelopment(listen)
+      await this.#startDevelopment()
     }
 
     await this._collectMetrics()
@@ -109,8 +104,8 @@ export class NextCapability extends BaseCapability {
     }
   }
 
-  async stop () {
-    await super.stop()
+  async _stop () {
+    await super._stop()
 
     if (this.subprocess) {
       return this.stopCommand()
@@ -179,14 +174,12 @@ export class NextCapability extends BaseCapability {
   }
 
   getMeta () {
-    const gateway = { prefix: this.basePath ?? this.#basePath, wantsAbsoluteUrls: true, needsRootTrailingSlash: false }
-
-    if (this.url) {
-      gateway.tcp = true
-      gateway.url = this.url
-    }
-
-    return { gateway }
+    return super.getMeta({
+      includeConnection: true,
+      prefix: this.basePath ?? this.#basePath,
+      wantsAbsoluteUrls: true,
+      needsRootTrailingSlash: false
+    })
   }
 
   async getChildManagerContext (basePath) {
@@ -211,7 +204,11 @@ export class NextCapability extends BaseCapability {
       return this.startWithCommand(command, loaderUrl, this.#getChildManagerScripts())
     }
 
-    const { hostname, port } = this.serverConfig ?? {}
+    if (typeof this.serverConfig?.port === 'undefined') {
+      return
+    }
+
+    const { hostname, port } = this.serverConfig
     const serverOptions = {
       host: hostname || '127.0.0.1',
       port: port || 0
@@ -317,13 +314,13 @@ export class NextCapability extends BaseCapability {
 
     if (command) {
       const childManagerScripts = this.#getChildManagerScripts()
-
-      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)
     }
 
+    if (typeof this.serverConfig?.port === 'undefined') {
+      return
+    }
+
     this.childManager = this.#createChildManager(
       loaderUrl,
       await this.getChildManagerContext(this.#basePath),
@@ -342,25 +339,20 @@ export class NextCapability extends BaseCapability {
     try {
       updateGlobals({ config: this.config })
       await this.childManager.inject()
+      await this.childManager.register()
       const { nextStart } = await importFile(resolvePath(this.#next, './dist/cli/next-start.js'))
 
-      const { hostname, port, backlog } = this.serverConfig ?? {}
+      const { hostname, port } = this.serverConfig ?? {}
       const serverOptions = {
         hostname: hostname || '127.0.0.1',
         port: port || 0
       }
 
-      await this.childManager.register()
-
-      const serverPromise = createServerListener(
-        (this.isEntrypoint ? serverOptions?.port : undefined) ?? true,
-        (this.isEntrypoint ? serverOptions?.hostname : undefined) ?? true,
-        typeof backlog === 'number' ? { backlog } : {}
-      )
+      const serverPromise = createServerListener()
 
       if (this.#nextVersion.major === 14 && this.#nextVersion.minor < 2) {
         await nextStart({
-          '--hostname': serverOptions.host,
+          '--hostname': serverOptions.hostname,
           '--port': serverOptions.port,
           _: [this.root]
         })
@@ -403,17 +395,13 @@ export class NextCapability extends BaseCapability {
       await this.childManager.inject()
       await this.childManager.register()
 
-      const { hostname, port, backlog } = this.serverConfig ?? {}
+      const { hostname, port } = 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 } : {}
-      )
+      const serverPromise = createServerListener()
 
       let keepAliveTimeout = parseInt(process.env.KEEP_ALIVE_TIMEOUT, 10)
       if (Number.isNaN(keepAliveTimeout) || !Number.isFinite(keepAliveTimeout) || keepAliveTimeout < 0) {
@@ -448,6 +436,10 @@ export class NextCapability extends BaseCapability {
       scripts.push(new URL('./loader-next-15.cjs', import.meta.url))
     }
 
+    if (this.#nextVersion.major < 15 || (this.#nextVersion.major === 15 && this.#nextVersion.minor < 1)) {
+      scripts.push(new URL('./create-context-patch.js', import.meta.url))
+    }
+
     return scripts
   }
 

package/lib/commands/pack.js

@@ -37,7 +37,16 @@ export async function packCommand (logger, configFile, args, context) {
 
   let config
   try {
-    config = await loadConfiguration(configFile)
+    /*
+      A command receives the application's already-resolved configuration as data -- the loader
+      evaluated it once, main-side, and validated it against this capability's schema -- so
+      `resolved` says the reading is done. A path is still accepted, which is what a caller outside
+      a running project supplies, and it is loaded the way a boot loads one.
+    */
+    config =
+      typeof configFile === 'string'
+        ? await loadConfiguration(configFile)
+        : await loadConfiguration(context.application?.path ?? process.cwd(), configFile, { resolved: true })
   } catch (error) {
     return logFatalError(
       logger,

package/lib/config.js

@@ -1,5 +1,4 @@
-import { transform as basicTransform, resolve, validationOptions } from '@platformatic/basic'
-import { loadConfiguration as utilsLoadConfiguration } from '@platformatic/foundation'
+import { transform as basicTransform, loadCapabilityConfiguration, validationOptions } from '@platformatic/basic'
 import { schema } from './schema.js'
 
 export async function transform (config, schema, options) {
@@ -14,13 +13,11 @@ export async function transform (config, schema, options) {
 }
 
 export async function loadConfiguration (configOrRoot, sourceOrConfig, context) {
-  const { root, source } = await resolve(configOrRoot, sourceOrConfig, 'application')
-
-  return utilsLoadConfiguration(source, context?.schema ?? schema, {
+  return loadCapabilityConfiguration(configOrRoot, sourceOrConfig, context, {
+    schema,
+    scope: import.meta.filename,
+    suffixes: 'application',
     validationOptions,
-    transform,
-    replaceEnv: true,
-    root,
-    ...context
+    transform
   })
 }

package/lib/create-context-patch.js

@@ -1,7 +1,7 @@
 'use strict'
 
 import { createRequire } from 'node:module'
-import { getGlobalDispatcher } from 'undici'
+import { fetch, getGlobalDispatcher } from 'undici'
 
 // Next.js runs middlewares in it's own patched vm context. So the global dispatcher in
 // the middleware context is different from an application global dispatcher. This
@@ -16,12 +16,16 @@ export function patchVmCreateContext () {
     const globalDispatcher = getGlobalDispatcher()
     const context = originalCreateContext(contextObject, opts)
     queueMicrotask(() => {
-      if (contextObject.fetch === undefined) return
+      if (context.fetch === undefined) return
 
-      const originalFetch = contextObject.fetch
-      contextObject.fetch = (input, init = {}) => {
-        init.dispatcher = globalDispatcher
-        return originalFetch(input, init)
+      const originalFetch = context.fetch
+      context.fetch = (input, init = {}) => {
+        const url = typeof input === 'string' ? input : input?.url
+        if (!url?.startsWith('http://') && !url?.startsWith('https://')) {
+          return originalFetch(input, init)
+        }
+
+        return fetch(input, { ...init, dispatcher: globalDispatcher })
       }
     })
     return context

package/lib/factory.js

@@ -0,0 +1,7 @@
+import { defineCapabilityFactory } from '@platformatic/basic'
+import { schema, version } from './schema.js'
+
+export const createNextConfig = defineCapabilityFactory('@platformatic/next', schema, {
+  version,
+  flatten: ['next']
+})

package/lib/image-optimizer.js

@@ -1,14 +1,13 @@
 import {
   BaseCapability,
   buildListenOptions,
-  errors as basicErrors,
   createServerListener,
+  errors as basicErrors,
   getServerUrl,
   importFile,
-  resolvePackageViaCJS
+  resolvePackageViaCJS, cleanBasePath
 } from '@platformatic/basic'
-import { cleanBasePath } from '@platformatic/basic/lib/utils.js'
-import { ensureLoggableError } from '@platformatic/foundation/lib/errors.js'
+import { ensureLoggableError } from '@platformatic/foundation'
 import { getEvents } from '@platformatic/globals'
 import { createQueue } from '@platformatic/image-optimizer'
 import { FileStorage, MemoryStorage, RedisStorage } from '@platformatic/job-queue'
@@ -72,37 +71,10 @@ export class NextImageOptimizerCapability extends BaseCapability {
     this.#queue = await this.#createQueue(imageOptimizerConfig)
   }
 
-  async start ({ listen }) {
-    // Make this idempotent
-    if (this.url) {
-      return this.url
-    }
-
+  async _start () {
     const config = this.config
     this.#basePath = config.application?.basePath ? cleanBasePath(config.application?.basePath) : ''
-    await super._start({ listen })
-
-    if (this.#app && listen) {
-      const serverOptions = this.serverConfig
-      const listenOptions = buildListenOptions(serverOptions)
-
-      if (typeof serverOptions?.backlog === 'number') {
-        createServerListener(false, false, { backlog: serverOptions.backlog })
-        listenOptions.backlog = serverOptions.backlog
-      }
-
-      this.#server = await new Promise((resolve, reject) => {
-        return this.#app
-          .listen(listenOptions, function () {
-            resolve(this)
-          })
-          .on('error', reject)
-      })
-
-      this.url = getServerUrl(this.#server)
-
-      return this.url
-    }
+    await super._start()
 
     const { ImageOptimizerCache } = await importFile(resolvePath(this.#next, './dist/server/image-optimizer.js'))
     this.#validateParams = ImageOptimizerCache.validateParams.bind(ImageOptimizerCache)
@@ -118,10 +90,32 @@ export class NextImageOptimizerCapability extends BaseCapability {
     this.#app = createServer(this.#handleRequest.bind(this))
     this.#dispatcher = this.#app.listeners('request')[0]
     await this.#queue.start()
+
+    if (typeof this.serverConfig?.port === 'undefined') {
+      return
+    }
+
+    const serverOptions = this.serverConfig
+    const listenOptions = buildListenOptions(serverOptions)
+    const serverPromise = createServerListener()
+
+    const [server] = await Promise.all([
+      new Promise((resolve, reject) => {
+        return this.#app
+          .listen(listenOptions, function () {
+            resolve(this)
+          })
+          .on('error', reject)
+      }),
+      serverPromise
+    ])
+    this.#server = server
+
+    this.url = getServerUrl(this.#server)
   }
 
-  async stop () {
-    await super.stop()
+  async _stop () {
+    await super._stop()
     await this.#queue?.stop()
 
     const events = getEvents()

package/lib/pack.js

@@ -15,7 +15,7 @@ import {
   symlink,
   writeFile
 } from 'node:fs/promises'
-import { createRequire } from 'node:module'
+import { findPackageJSON } from 'node:module'
 import { tmpdir } from 'node:os'
 import { dirname, isAbsolute, relative, resolve as resolvePath } from 'node:path'
 import { version as platformaticVersion } from './schema.js'
@@ -169,60 +169,15 @@ async function loadPackageFromRoot (root, fallbackName) {
 }
 
 async function resolvePackageRoot (name, from) {
-  const require = createRequire(from)
-
   try {
-    const packageJsonPath = require.resolve(`${name}/package.json`)
-    return dirname(packageJsonPath)
+    return dirname(findPackageJSON(name, from))
   } catch (error) {
-    const packageJsonPath = resolvePackageJsonFromSearchPaths(require, name)
-    if (packageJsonPath) {
-      return dirname(packageJsonPath)
-    }
-
-    try {
-      const resolvedEntry = require.resolve(name)
-      return await findPackageRoot(dirname(resolvedEntry))
-    } catch (resolveError) {
-      const workspacePackage = resolveWorkspacePackageRoot(name)
-      if (workspacePackage) {
-        return workspacePackage
-      }
-
-      throw resolveError
-    }
-  }
-}
-
-function resolvePackageJsonFromSearchPaths (require, name) {
-  const searchPaths = require.resolve.paths(name) ?? []
-  const packageSegments = name.split('/')
-
-  for (const searchPath of searchPaths) {
-    const candidate = resolvePath(searchPath, ...packageSegments, 'package.json')
-    if (existsSync(candidate)) {
-      return candidate
-    }
-  }
-
-  return null
-}
-
-async function findPackageRoot (directory) {
-  let current = directory
-
-  while (true) {
-    const candidate = resolvePath(current, 'package.json')
-    if (existsSync(candidate)) {
-      return current
-    }
-
-    const parent = resolvePath(current, '..')
-    if (parent === current) {
-      throw new Error(`Cannot determine package root for ${directory}.`)
+    const workspacePackage = resolveWorkspacePackageRoot(name)
+    if (workspacePackage) {
+      return workspacePackage
     }
 
-    current = parent
+    throw error
   }
 }
 

package/lib/schema.js

@@ -1,11 +1,14 @@
-import { schemaComponents as basicSchemaComponents } from '@platformatic/basic'
-import { schemaComponents as utilsSchemaComponents } from '@platformatic/foundation'
+import { schemaComponents as basicSchemaComponents } from '@platformatic/basic/schema'
+import { schemaComponents as utilsSchemaComponents } from '@platformatic/foundation/schema'
 import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 
 export const packageJson = JSON.parse(readFileSync(resolve(import.meta.dirname, '../package.json'), 'utf8'))
 export const version = packageJson.version
 
+// The port is checked before any startup path is selected, so no port means no start.
+export const servesWithoutPort = { development: false, production: false }
+
 export const cache = {
   type: 'object',
   properties: {
@@ -240,6 +243,15 @@ const next = {
   additionalProperties: false
 }
 
+/*
+  The names the generated types carry -- see the table in `foundation/lib/schema.js` for why they
+  are assigned rather than written at each site. `https` is Next's own, distinct from `server.https`
+  next to it, and the two names are what keeps that adjacency legible.
+*/
+next.properties.https.title = 'NextHttpsOptions'
+next.properties.imageOptimizer.title = 'ImageOptimizerOptions'
+cache.title = 'NextCacheOptions'
+
 export const schemaComponents = { next }
 
 export const schema = {

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@platformatic/next",
-  "version": "3.72.0",
+  "version": "4.0.0-alpha.1",
   "description": "Platformatic Next.js Capability",
   "main": "index.js",
   "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./schema": "./schema.js",
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/platformatic/platformatic.git"
@@ -19,21 +25,19 @@
     "@babel/parser": "^7.25.3",
     "@babel/traverse": "^7.25.3",
     "@babel/types": "^7.25.2",
-    "@platformatic/basic": "3.72.0",
-    "@platformatic/foundation": "3.72.0",
-    "@platformatic/globals": "3.72.0",
     "@platformatic/image-optimizer": "^0.2.1",
     "amaro": "^1.0.0",
     "iovalkey": "^0.3.0",
     "light-my-request": "^6.0.0",
     "msgpackr": "^1.11.2",
-    "semver": "^7.6.3"
+    "semver": "^7.6.3",
+    "@platformatic/foundation": "4.0.0-alpha.1",
+    "@platformatic/basic": "4.0.0-alpha.1",
+    "@platformatic/globals": "4.0.0-alpha.1"
   },
   "devDependencies": {
     "@fastify/reply-from": "^12.0.0",
-    "@platformatic/gateway": "3.72.0",
-    "@platformatic/service": "3.72.0",
-    "@types/node": "^22.5.0",
+    "@types/node": "^24.0.0",
     "@types/react": "^19.1.11",
     "@types/react-dom": "^19.1.7",
     "cleaner-spec-reporter": "^0.5.0",
@@ -45,10 +49,12 @@
     "neostandard": "^0.12.0",
     "next": "^16.1.0",
     "typescript": "~6.0.3",
-    "ws": "^8.18.0"
+    "ws": "^8.18.0",
+    "@platformatic/gateway": "4.0.0-alpha.1",
+    "@platformatic/service": "4.0.0-alpha.1"
   },
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=24.20.0"
   },
   "scripts": {
     "test": "npm run test:types && npm run test:main && npm run test:caching && npm run test:compatibility && npm run test:integration",
@@ -56,6 +62,8 @@
     "test:main": "node --test --test-reporter=cleaner-spec-reporter --test-concurrency=1 --test-timeout=2000000 test/*.test.js",
     "test:caching": "node --test --test-reporter=cleaner-spec-reporter --test-concurrency=1 --test-timeout=2000000 test/caching/*.test.js",
     "test:compatibility": "node --test --test-reporter=cleaner-spec-reporter --test-concurrency=1 --test-timeout=2000000 test/compatibility/*.test.js",
+    "test:compatibility-development": "PLATFORMATIC_NEXT_COMPATIBILITY_MODE=development node --test --test-reporter=cleaner-spec-reporter --test-concurrency=1 --test-timeout=2000000 test/compatibility/*.test.js",
+    "test:compatibility-production": "PLATFORMATIC_NEXT_COMPATIBILITY_MODE=production node --test --test-reporter=cleaner-spec-reporter --test-concurrency=1 --test-timeout=2000000 test/compatibility/*.test.js",
     "test:integration": "node --test --test-reporter=cleaner-spec-reporter --test-concurrency=1 --test-timeout=2000000 test/integration/*.test.js",
     "gen-schema": "node lib/schema.js > schema.json",
     "gen-types": "json2ts > config.d.ts < schema.json",

package/schema.js

@@ -0,0 +1,7 @@
+// The light /schema subpath, part of the capability contract. It carries the schema and the
+// package-level metadata main-side preparation needs, and imports nothing that would pull the
+// capability's implementation in with it — boot resolves this rather than the package entry.
+//
+// Light is a statement about import cost, never about safety: this executes in the main process
+// with full privileges, like any capability code.
+export * from './lib/schema.js'