[Breaking] Disable automatic static generation for route handlers (#6…

…5825)

## Background

Currently route handlers will be attempted to statically generate the
same as normal pages in app router. If a route handler accessed dynamic
data such as `cookies()`, `headers()`, `req.url`, or similar we would
bail from this static generation but this didn't handle the case where
you would do data fetching via a non-fetch based library e.g. `redis` or
even using `Date.now()` or `Math.random()` so users would expect these
to be run every request like normal API endpoints but they would be
static so wouldn't be executed again after a build.


## New Behavior

As discussed this disable the default static generation handling for
route handlers as we've seen this confuse our users since in most cases
when creating a route handler you are handling dynamic workloads. This
doesn't remove the ability to static generate route handlers though as
you can still manually specify:

If you specify `export const revalidate = 1` we will still bail if
dynamic data is accessed to prevent accidental `revalidate` configuring
but this can be avoided via `force-static` being used as well.
 
```js
export const dynamic = 'force-static'
// or
export const dynamic = 'error'
// or
export const revalidate = false
// or
export const revalidate = 1 // value great than 0
// or 
export const generateStaticParams() {}
```

---------

Co-authored-by: Zack Tanner <1939140+ztanner@users.noreply.github.com>

docs/02-app/01-building-your-application/01-routing/13-route-handlers.mdx

@@ -49,9 +49,14 @@ In addition to supporting native [Request](https://developer.mozilla.org/docs/We
 
 ### Caching
 
-Route Handlers are cached by default when using the `GET` method with the `Response` object.
+Route Handlers are dynamic by default as of Next.js v15. To opt-in to caching for GET requests in route handlers you can specify via the following config:
 
 ```ts filename="app/items/route.ts" switcher
+// opt in to caching the route handler
+export const dynamic = 'force-static' // or 'error'
+// or
+export const revalidate = false // or a value > 0
+
 export async function GET() {
   const res = await fetch('https://data.mongodb-api.com/...', {
     headers: {

packages/next/src/export/routes/app-route.ts

@@ -23,6 +23,7 @@ import type {
 import { isDynamicUsageError } from '../helpers/is-dynamic-usage-error'
 import { SERVER_DIRECTORY } from '../../shared/lib/constants'
 import { hasNextSupport } from '../../telemetry/ci-info'
+import { isStaticGenEnabled } from '../../server/future/route-modules/app-route/helpers/is-static-gen-enabled'
 import type { ExperimentalConfig } from '../../server/config-shared'
 
 export const enum ExportedAppRouteFiles {
@@ -87,6 +88,12 @@ export async function exportAppRoute(
   try {
     // Route module loading and handling.
     const module = await RouteModuleLoader.load<AppRouteRouteModule>(filename)
+    const userland = module.userland
+
+    if (!isStaticGenEnabled(userland)) {
+      return { revalidate: 0 }
+    }
+
     const response = await module.handle(request, context)
 
     const isValidStatus = response.status < 400 || response.status === 404

packages/next/src/server/future/route-modules/app-route/helpers/is-static-gen-enabled.ts

@@ -0,0 +1,20 @@
+import type { AppRouteModule } from '../module.compiled'
+
+// route handlers are only statically optimized if they define
+// one of these top-level configs manually
+//   - dynamic = 'force-static'
+//   - dynamic = 'error'
+//   - revalidate > 0
+//   - revalidate = false
+//   - generateStaticParams
+export function isStaticGenEnabled(
+  mod: AppRouteModule['routeModule']['userland']
+) {
+  return (
+    mod.dynamic === 'force-static' ||
+    mod.dynamic === 'error' ||
+    mod.revalidate === false ||
+    (mod.revalidate !== undefined && mod.revalidate > 0) ||
+    typeof mod.generateStaticParams == 'function'
+  )
+}

packages/next/src/server/future/route-modules/app-route/module.ts

@@ -50,6 +50,7 @@ import { getIsServerAction } from '../../../lib/server-action-request-meta'
 import { RequestCookies } from 'next/dist/compiled/@edge-runtime/cookies'
 import { cleanURL } from './helpers/clean-url'
 import { StaticGenBailoutError } from '../../../../client/components/static-generation-bailout'
+import { isStaticGenEnabled } from './helpers/is-static-gen-enabled'
 
 /**
  * The AppRouteModule is the type of the module exported by the bundled App
@@ -178,12 +179,16 @@ export class AppRouteRouteModule extends RouteModule<
     // Get the dynamic property from the userland module.
     this.dynamic = this.userland.dynamic
     if (this.nextConfigOutput === 'export') {
-      if (!this.dynamic || this.dynamic === 'auto') {
-        this.dynamic = 'error'
-      } else if (this.dynamic === 'force-dynamic') {
+      if (this.dynamic === 'force-dynamic') {
         throw new Error(
           `export const dynamic = "force-dynamic" on page "${definition.pathname}" cannot be used with "output: export". See more info here: https://nextjs.org/docs/advanced-features/static-html-export`
         )
+      } else if (!isStaticGenEnabled(this.userland) && this.userland['GET']) {
+        throw new Error(
+          `export const dynamic = "force-static"/export const revalidate not configured on route "${definition.pathname}" with "output: export". See more info here: https://nextjs.org/docs/advanced-features/static-html-export`
+        )
+      } else {
+        this.dynamic = 'error'
       }
     }
 

test/e2e/app-dir/actions/app/handler/route.js

@@ -1,5 +1,7 @@
 import { cookies } from 'next/headers'
 
+export const revalidate = 1
+
 export const GET = async () => {
   cookies().set('foo', 'foo1')
   cookies().set('bar', 'bar1')

test/e2e/app-dir/app-routes/app/api/hello.json/route.ts

@@ -1,5 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server'
 
+export const revalidate = 1
+
 export const GET = (req: NextRequest) => {
   return NextResponse.json({
     pathname: req.nextUrl.pathname,

test/e2e/app-dir/app-static/app/api/large-data/route.js

@@ -1,5 +1,7 @@
 import { NextResponse } from 'next/server'
 
+export const revalidate = false
+
 export async function GET() {
   console.log('Load data')
   return NextResponse.json({

test/e2e/app-dir/app-static/app/api/revalidate-path-node/route.ts

@@ -1,6 +1,8 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { revalidatePath } from 'next/cache'
 
+export const revalidate = 1
+
 export async function GET(req: NextRequest) {
   const path = req.nextUrl.searchParams.get('path') || '/'
   try {

test/e2e/app-dir/app-static/app/route-handler/revalidate-360-isr/route.js

@@ -1,5 +1,7 @@
 import { NextResponse } from 'next/server'
 
+export const revalidate = 10
+
 export async function GET() {
   const data360 = await fetch(
     'https://next-data-api-endpoint.vercel.app/api/random',

test/e2e/app-dir/app-static/app/route-handler/static-cookies/route.js

@@ -1,5 +1,7 @@
 import { NextResponse } from 'next/server'
 
+export const revalidate = false
+
 export function GET() {
   const res = new NextResponse()
   res.cookies.set('theme', 'light')

test/e2e/app-dir/dynamic-data/fixtures/main/app/routes/next-url/route.js

@@ -1,3 +1,5 @@
+export const revalidate = 1
+
 export const GET = async (request) => {
   try {
     const body = JSON.stringify({ pathname: request.nextUrl.toString() })

test/e2e/app-dir/dynamic-data/fixtures/main/app/routes/url/route.js

@@ -1,3 +1,5 @@
+export const revalidate = 1
+
 export const GET = async (request) => {
   try {
     const body = JSON.stringify({ url: request.url })

test/integration/app-dir-export/app/api/txt/route.js

@@ -1,3 +1,5 @@
+export const revalidate = false
+
 export async function GET() {
   return new Response('this is plain text')
 }

test/integration/app-dir-export/test/dynamicapiroute-dev.test.ts

@@ -5,7 +5,11 @@ describe('app dir - with output export - dynamic api route dev', () => {
     'development mode',
     () => {
       it.each([
-        { dynamicApiRoute: 'undefined' },
+        {
+          dynamicApiRoute: 'undefined',
+          expectedErrMsg:
+            'export const dynamic = "force-static"/export const revalidate not configured on route',
+        },
         { dynamicApiRoute: "'error'" },
         { dynamicApiRoute: "'force-static'" },
         {

test/integration/app-dir-export/test/dynamicapiroute-prod.test.ts

@@ -5,7 +5,11 @@ describe('app dir - with output export - dynamic api route prod', () => {
     'production mode',
     () => {
       it.each([
-        { dynamicApiRoute: 'undefined' },
+        {
+          dynamicApiRoute: 'undefined',
+          expectedErrMsg:
+            'export const dynamic = "force-static"/export const revalidate not configured on route',
+        },
         { dynamicApiRoute: "'error'" },
         { dynamicApiRoute: "'force-static'" },
         {