feat: use Frameworks API

src/build/content/prerendered.ts

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs'
-import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { mkdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
 import { trace } from '@opentelemetry/api'
@@ -8,7 +8,6 @@ import { glob } from 'fast-glob'
 import pLimit from 'p-limit'
 import { satisfies } from 'semver'
 
-import { encodeBlobKey } from '../../shared/blobkey.js'
 import type {
   CachedFetchValue,
   NetlifyCachedAppPageValue,
@@ -31,13 +30,11 @@ const writeCacheEntry = async (
   lastModified: number,
   ctx: PluginContext,
 ): Promise<void> => {
-  const path = join(ctx.blobDir, await encodeBlobKey(route))
   const entry = JSON.stringify({
     lastModified,
     value,
   } satisfies NetlifyCacheHandlerValue)
-
-  await writeFile(path, entry, 'utf-8')
+  await ctx.setBlob(route, entry)
 }
 
 /**

src/build/content/static.ts

@@ -1,12 +1,11 @@
 import { existsSync } from 'node:fs'
-import { cp, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { cp, mkdir, readFile, rename, rm } from 'node:fs/promises'
 import { basename, join } from 'node:path'
 
 import { trace } from '@opentelemetry/api'
 import { wrapTracer } from '@opentelemetry/api/experimental'
 import glob from 'fast-glob'
 
-import { encodeBlobKey } from '../../shared/blobkey.js'
 import { PluginContext } from '../plugin-context.js'
 import { verifyNetlifyForms } from '../verification.js'
 
@@ -33,7 +32,7 @@ export const copyStaticContent = async (ctx: PluginContext): Promise<void> => {
           .map(async (path): Promise<void> => {
             const html = await readFile(join(srcDir, path), 'utf-8')
             verifyNetlifyForms(ctx, html)
-            await writeFile(join(destDir, await encodeBlobKey(path)), html, 'utf-8')
+            await ctx.setBlob(path, html)
           }),
       )
     } catch (error) {

src/build/functions/edge.ts

@@ -1,7 +1,7 @@
 import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 
-import type { Manifest, ManifestFunction } from '@netlify/edge-functions'
+import type { IntegrationsConfig, Manifest, ManifestFunction } from '@netlify/edge-functions'
 import { glob } from 'fast-glob'
 import type { EdgeFunctionDefinition as NextDefinition } from 'next/dist/build/webpack/plugins/middleware-plugin.js'
 import { pathToRegexp } from 'path-to-regexp'
@@ -53,7 +53,7 @@ const augmentMatchers = (
   })
 }
 
-const writeHandlerFile = async (ctx: PluginContext, { matchers, name }: NextDefinition) => {
+const writeHandlerFile = async (ctx: PluginContext, { matchers, name, page }: NextDefinition) => {
   const nextConfig = ctx.buildConfig
   const handlerName = getHandlerName({ name })
   const handlerDirectory = join(ctx.edgeFunctionsDir, handlerName)
@@ -63,12 +63,11 @@ const writeHandlerFile = async (ctx: PluginContext, { matchers, name }: NextDefi
   // Netlify Edge Functions and the Next.js edge runtime.
   await copyRuntime(ctx, handlerDirectory)
 
+  const augmentedMatchers = augmentMatchers(matchers, ctx)
+
   // Writing a file with the matchers that should trigger this function. We'll
   // read this file from the function at runtime.
-  await writeFile(
-    join(handlerRuntimeDirectory, 'matchers.json'),
-    JSON.stringify(augmentMatchers(matchers, ctx)),
-  )
+  await writeFile(join(handlerRuntimeDirectory, 'matchers.json'), JSON.stringify(augmentedMatchers))
 
   // The config is needed by the edge function to match and normalize URLs. To
   // avoid shipping and parsing a large file at runtime, let's strip it down to
@@ -85,6 +84,17 @@ const writeHandlerFile = async (ctx: PluginContext, { matchers, name }: NextDefi
     JSON.stringify(minimalNextConfig),
   )
 
+  const isc = ctx.useFrameworksAPI
+    ? `export const config = ${JSON.stringify({
+        name: name.endsWith('middleware')
+          ? 'Next.js Middleware Handler'
+          : `Next.js Edge Handler: ${page}`,
+        pattern: augmentedMatchers.map((matcher) => matcher.regexp),
+        cache: name.endsWith('middleware') ? undefined : 'manual',
+        generator: `${ctx.pluginName}@${ctx.pluginVersion}`,
+      } satisfies IntegrationsConfig)};`
+    : ``
+
   // Writing the function entry file. It wraps the middleware code with the
   // compatibility layer mentioned above.
   await writeFile(
@@ -93,7 +103,7 @@ const writeHandlerFile = async (ctx: PluginContext, { matchers, name }: NextDefi
     import {handleMiddleware} from './edge-runtime/middleware.ts';
     import handler from './server/${name}.js';
     export default (req, context) => handleMiddleware(req, context, handler);
-    `,
+    ${isc}`,
   )
 }
 
@@ -174,10 +184,12 @@ export const createEdgeHandlers = async (ctx: PluginContext) => {
   ]
   await Promise.all(nextDefinitions.map((def) => createEdgeHandler(ctx, def)))
 
-  const netlifyDefinitions = nextDefinitions.flatMap((def) => buildHandlerDefinition(ctx, def))
-  const netlifyManifest: Manifest = {
-    version: 1,
-    functions: netlifyDefinitions,
+  if (!ctx.useFrameworksAPI) {
+    const netlifyDefinitions = nextDefinitions.flatMap((def) => buildHandlerDefinition(ctx, def))
+    const netlifyManifest: Manifest = {
+      version: 1,
+      functions: netlifyDefinitions,
+    }
+    await writeEdgeManifest(ctx, netlifyManifest)
   }
-  await writeEdgeManifest(ctx, netlifyManifest)
 }

src/build/functions/server.ts

@@ -103,7 +103,9 @@ const getHandlerFile = async (ctx: PluginContext): Promise<string> => {
   const templatesDir = join(ctx.pluginDir, 'dist/build/templates')
 
   const templateVariables: Record<string, string> = {
-    '{{useRegionalBlobs}}': ctx.useRegionalBlobs.toString(),
+    '{{useRegionalBlobs}}': (ctx.blobsStrategy !== 'legacy').toString(),
+    '{{generator}}': `${ctx.pluginName}@${ctx.pluginVersion}`,
+    '{{serverHandlerRootDir}}': ctx.serverHandlerRootDir,
   }
   // In this case it is a monorepo and we need to use a own template for it
   // as we have to change the process working directory
@@ -141,7 +143,9 @@ export const createServerHandler = async (ctx: PluginContext) => {
     await copyNextServerCode(ctx)
     await copyNextDependencies(ctx)
     await copyHandlerDependencies(ctx)
-    await writeHandlerManifest(ctx)
+    if (!ctx.useFrameworksAPI) {
+      await writeHandlerManifest(ctx)
+    }
     await writePackageMetadata(ctx)
     await writeHandlerFile(ctx)
 

src/build/plugin-context.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
-import { join, relative, resolve } from 'node:path'
+import { dirname, join, relative, resolve } from 'node:path'
 import { join as posixJoin } from 'node:path/posix'
 import { fileURLToPath } from 'node:url'
 
@@ -15,6 +15,8 @@ import type { MiddlewareManifest } from 'next/dist/build/webpack/plugins/middlew
 import type { NextConfigComplete } from 'next/dist/server/config-shared.js'
 import { satisfies } from 'semver'
 
+import { encodeBlobKey } from '../shared/blobkey.js'
+
 const MODULE_DIR = fileURLToPath(new URL('.', import.meta.url))
 const PLUGIN_DIR = join(MODULE_DIR, '../..')
 const DEFAULT_PUBLISH_DIR = '.next'
@@ -137,36 +139,87 @@ export class PluginContext {
 
   /**
    * Absolute path of the directory that will be deployed to the blob store
+   * frameworks api: `.netlify/v1/blobs/deploy`
    * region aware: `.netlify/deploy/v1/blobs/deploy`
    * default: `.netlify/blobs/deploy`
    */
   get blobDir(): string {
-    if (this.useRegionalBlobs) {
-      return this.resolveFromPackagePath('.netlify/deploy/v1/blobs/deploy')
+    switch (this.blobsStrategy) {
+      case 'frameworks-api':
+        return this.resolveFromPackagePath('.netlify/v1/blobs/deploy')
+      case 'regional':
+        return this.resolveFromPackagePath('.netlify/deploy/v1/blobs/deploy')
+      case 'legacy':
+      default:
+        return this.resolveFromPackagePath('.netlify/blobs/deploy')
     }
+  }
 
-    return this.resolveFromPackagePath('.netlify/blobs/deploy')
+  async setBlob(key: string, value: string) {
+    switch (this.blobsStrategy) {
+      case 'frameworks-api': {
+        const path = join(this.blobDir, await encodeBlobKey(key), 'blob')
+        await mkdir(dirname(path), { recursive: true })
+        await writeFile(path, value, 'utf-8')
+        return
+      }
+      case 'regional':
+      case 'legacy':
+      default: {
+        const path = join(this.blobDir, await encodeBlobKey(key))
+        await writeFile(path, value, 'utf-8')
+      }
+    }
   }
 
   get buildVersion(): string {
     return this.constants.NETLIFY_BUILD_VERSION || 'v0.0.0'
   }
 
-  get useRegionalBlobs(): boolean {
-    if (!(this.featureFlags || {})['next-runtime-regional-blobs']) {
-      return false
+  // eslint-disable-next-line no-invalid-this
+  #useFrameworksAPI: typeof this.useFrameworksAPI | null = null
+  get useFrameworksAPI(): boolean {
+    if (this.#useFrameworksAPI === null) {
+      // Defining RegExp pattern in edge function inline config is only supported since 29.50.5
+      const REQUIRED_BUILD_VERSION = '>=29.50.5'
+      this.#useFrameworksAPI = satisfies(this.buildVersion, REQUIRED_BUILD_VERSION, {
+        includePrerelease: true,
+      })
+    }
+
+    return this.#useFrameworksAPI
+  }
+
+  // eslint-disable-next-line no-invalid-this
+  #blobsStrategy: typeof this.blobsStrategy | null = null
+  get blobsStrategy(): 'legacy' | 'regional' | 'frameworks-api' {
+    if (this.#blobsStrategy === null) {
+      if (this.useFrameworksAPI) {
+        this.#blobsStrategy = 'frameworks-api'
+      } else {
+        // Region-aware blobs are only available as of CLI v17.23.5 (i.e. Build v29.41.5)
+        const REQUIRED_BUILD_VERSION = '>=29.41.5'
+        this.#blobsStrategy = satisfies(this.buildVersion, REQUIRED_BUILD_VERSION, {
+          includePrerelease: true,
+        })
+          ? 'regional'
+          : 'legacy'
+      }
+      //
     }
 
-    // Region-aware blobs are only available as of CLI v17.23.5 (i.e. Build v29.41.5)
-    const REQUIRED_BUILD_VERSION = '>=29.41.5'
-    return satisfies(this.buildVersion, REQUIRED_BUILD_VERSION, { includePrerelease: true })
+    return this.#blobsStrategy
   }
 
   /**
    * Absolute path of the directory containing the files for the serverless lambda function
    * `.netlify/functions-internal`
    */
   get serverFunctionsDir(): string {
+    if (this.useFrameworksAPI) {
+      return this.resolveFromPackagePath('.netlify/v1/functions')
+    }
+
     return this.resolveFromPackagePath('.netlify/functions-internal')
   }
 
@@ -194,6 +247,10 @@ export class PluginContext {
    * `.netlify/edge-functions`
    */
   get edgeFunctionsDir(): string {
+    if (this.useFrameworksAPI) {
+      return this.resolveFromPackagePath('.netlify/v1/edge-functions')
+    }
+
     return this.resolveFromPackagePath('.netlify/edge-functions')
   }
 

src/build/templates/handler-monorepo.tmpl.js

@@ -53,4 +53,9 @@ export default async function (req, context) {
 export const config = {
   path: '/*',
   preferStatic: true,
+  name: 'Next.js Server Handler',
+  generator: '{{generator}}',
+  nodeBundler: 'none',
+  includedFiles: ['**'],
+  includedFilesBasePath: '{{serverHandlerRootDir}}',
 }

src/build/templates/handler.tmpl.js

@@ -46,4 +46,9 @@ export default async function handler(req, context) {
 export const config = {
   path: '/*',
   preferStatic: true,
+  name: 'Next.js Server Handler',
+  generator: '{{generator}}',
+  nodeBundler: 'none',
+  includedFiles: ['**'],
+  includedFilesBasePath: '{{serverHandlerRootDir}}',
 }

tests/utils/fixture.ts

@@ -184,7 +184,7 @@ export async function runPluginStep(
       // EDGE_FUNCTIONS_DIST: '.netlify/edge-functions-dist/',
       // CACHE_DIR: '.netlify/cache',
       // IS_LOCAL: true,
-      // NETLIFY_BUILD_VERSION: '29.23.4',
+      NETLIFY_BUILD_VERSION: '29.50.5',
       // INTERNAL_FUNCTIONS_SRC: '.netlify/functions-internal',
       // INTERNAL_EDGE_FUNCTIONS_SRC: '.netlify/edge-functions',
     },
@@ -298,28 +298,54 @@ export async function runPlugin(
     )
   }
 
-  await Promise.all([bundleEdgeFunctions(), bundleFunctions(), uploadBlobs(ctx, base.blobDir)])
+  await Promise.all([bundleEdgeFunctions(), bundleFunctions(), uploadBlobs(ctx, base)])
 
   return options
 }
 
-export async function uploadBlobs(ctx: FixtureTestContext, blobsDir: string) {
-  const files = await glob('**/*', {
-    dot: true,
-    cwd: blobsDir,
-  })
+export async function uploadBlobs(ctx: FixtureTestContext, pluginContext: PluginContext) {
+  if (pluginContext.blobsStrategy === 'frameworks-api') {
+    const files = await glob('**/blob', {
+      dot: true,
+      cwd: pluginContext.blobDir,
+    })
 
-  const keys = files.filter((file) => !basename(file).startsWith('$'))
-  await Promise.all(
-    keys.map(async (key) => {
-      const { dir, base } = parse(key)
-      const metaFile = join(blobsDir, dir, `$${base}.json`)
-      const metadata = await readFile(metaFile, 'utf-8')
-        .then((meta) => JSON.parse(meta))
-        .catch(() => ({}))
-      await ctx.blobStore.set(key, await readFile(join(blobsDir, key), 'utf-8'), { metadata })
-    }),
-  )
+    await Promise.all(
+      files.map(async (blobFilePath) => {
+        const { dir: key } = parse(blobFilePath)
+        const metaFile = join(pluginContext.blobDir, key, `blob.meta.json`)
+        const metadata = await readFile(metaFile, 'utf-8')
+          .then((meta) => JSON.parse(meta))
+          .catch(() => ({}))
+        await ctx.blobStore.set(
+          key,
+          await readFile(join(pluginContext.blobDir, blobFilePath), 'utf-8'),
+          {
+            metadata,
+          },
+        )
+      }),
+    )
+  } else {
+    const files = await glob('**/*', {
+      dot: true,
+      cwd: pluginContext.blobDir,
+    })
+
+    const keys = files.filter((file) => !basename(file).startsWith('$'))
+    await Promise.all(
+      keys.map(async (key) => {
+        const { dir, base } = parse(key)
+        const metaFile = join(pluginContext.blobDir, dir, `$${base}.json`)
+        const metadata = await readFile(metaFile, 'utf-8')
+          .then((meta) => JSON.parse(meta))
+          .catch(() => ({}))
+        await ctx.blobStore.set(key, await readFile(join(pluginContext.blobDir, key), 'utf-8'), {
+          metadata,
+        })
+      }),
+    )
+  }
 }
 
 const DEFAULT_FLAGS = {