Alias nextjs api entry to esm version for app router (#59852)

## What

When users specify `"type": "module"` in Next.js app, especially with
`create-next-app`, `Image` component is not working. An error
`Unsupported Server Component type: {...}` is thrown.

## Why

`next/image` API is mixing with a client component as default export and
a named export as server component. But the entry file of the API is
still CJS file, which will import the module as the object. So you'll
get `{ default, unstable_getImageProps }` when you do `import Image from
'next/image'` instead of `Image` component itself, where the CJS module
load all the exports as an object. This is expected behavior for ESM but
breaks the usage.

It only errors when you're using js extensions, if you're using
typescript, it still works. If you're using turbopack, it works in dev
mode.

This is also because webpack can't analyze the exports from CJS module
of that `next/image` entry file. Usually we can assign the default
export to the module itself, then attach other named exports onto it, so
the default export equals the `module.exports` itself. But for
`next/image` since the default export is an client component, doing that
will error with React as you cannot modify the react client reference.
Turbopack doesn't use the same way to analyze the default export, so it
doesn't have this problem.

## How

We create few ESM version of entry files of nextjs APIs, then pick up
them to let app router for bundling, instead of using the `next/<api
name>.js` CJS files. Those ESM entries still point to the `next/dist/..`
CJS files. In this way webpack and directly gets the exports from the
`next/dist/...` files and be aware of the module exports. No more CJS
module wrapping the ESM module, the default and named exports can
preserve correctly.

Fixes #54777
Closes NEXT-1774
Closes NEXT-1879
Closes NEXT-1923

packages/next/src/api/app-dynamic.ts

@@ -0,0 +1,2 @@
+export * from '../shared/lib/app-dynamic'
+export { default } from '../shared/lib/app-dynamic'

packages/next/src/api/app.tsx

@@ -0,0 +1,2 @@
+export * from '../pages/_app'
+export { default } from '../pages/_app'

packages/next/src/api/constants.ts

@@ -0,0 +1 @@
+export * from '../shared/lib/constants'

packages/next/src/api/document.tsx

@@ -0,0 +1,2 @@
+export * from '../pages/_document'
+export { default } from '../pages/_document'

packages/next/src/api/dynamic.ts

@@ -0,0 +1,2 @@
+export { default } from '../shared/lib/dynamic'
+export * from '../shared/lib/dynamic'

packages/next/src/api/head.ts

@@ -0,0 +1,2 @@
+export { default } from '../shared/lib/head'
+export * from '../shared/lib/head'

packages/next/src/api/headers.ts

@@ -0,0 +1 @@
+export * from '../client/components/headers'

packages/next/src/api/image.ts

@@ -0,0 +1,2 @@
+export { default } from '../shared/lib/image-external'
+export * from '../shared/lib/image-external'

packages/next/src/api/link.ts

@@ -0,0 +1,2 @@
+export { default } from '../client/link'
+export * from '../client/link'

packages/next/src/api/navigation.ts

@@ -0,0 +1 @@
+export * from '../client/components/navigation'

packages/next/src/api/og.ts

@@ -0,0 +1 @@
+export * from '../server/og/image-response'

packages/next/src/api/router.ts

@@ -0,0 +1,2 @@
+export { default } from '../client/router'
+export * from '../client/router'

packages/next/src/api/script.ts

@@ -0,0 +1,2 @@
+export { default } from '../client/script'
+export * from '../client/script'

packages/next/src/api/server.ts

@@ -0,0 +1 @@
+export * from '../server/web/exports/index'

packages/next/src/build/create-compiler-aliases.ts

@@ -12,11 +12,7 @@ import {
 } from '../lib/constants'
 import type { NextConfigComplete } from '../server/config-shared'
 import { defaultOverrides } from '../server/require-hook'
-import {
- NEXT_PROJECT_ROOT,
- NEXT_PROJECT_ROOT_DIST,
- hasExternalOtelApiPackage,
-} from './webpack-config'
+import { NEXT_PROJECT_ROOT, hasExternalOtelApiPackage } from './webpack-config'
 import { WEBPACK_LAYERS } from '../lib/constants'
 
 interface CompilerAliases {
@@ -96,51 +92,15 @@ export function createWebpackAliases({
  // let this alias hit before `next` alias.
  ...(isEdgeServer
  ? {
+ 'next/dist/api': 'next/dist/esm/api',
  'next/dist/build': 'next/dist/esm/build',
  'next/dist/client': 'next/dist/esm/client',
  'next/dist/shared': 'next/dist/esm/shared',
  'next/dist/pages': 'next/dist/esm/pages',
  'next/dist/lib': 'next/dist/esm/lib',
  'next/dist/server': 'next/dist/esm/server',
 
- // Alias the usage of next public APIs
- [path.join(NEXT_PROJECT_ROOT, 'server')]:
- 'next/dist/esm/server/web/exports/index',
- [path.join(NEXT_PROJECT_ROOT, 'og')]:
- 'next/dist/esm/server/og/image-response',
- [path.join(NEXT_PROJECT_ROOT_DIST, 'client', 'link')]:
- 'next/dist/esm/client/link',
- [path.join(
- NEXT_PROJECT_ROOT,
- 'dist',
- 'shared',
- 'lib',
- 'image-external'
- )]: 'next/dist/esm/shared/lib/image-external',
- [path.join(NEXT_PROJECT_ROOT_DIST, 'client', 'script')]:
- 'next/dist/esm/client/script',
- [path.join(NEXT_PROJECT_ROOT_DIST, 'client', 'router')]:
- 'next/dist/esm/client/router',
- [path.join(NEXT_PROJECT_ROOT_DIST, 'shared', 'lib', 'head')]:
- 'next/dist/esm/shared/lib/head',
- [path.join(NEXT_PROJECT_ROOT_DIST, 'shared', 'lib', 'dynamic')]:
- 'next/dist/esm/shared/lib/dynamic',
- [path.join(NEXT_PROJECT_ROOT_DIST, 'pages', '_document')]:
- 'next/dist/esm/pages/_document',
- [path.join(NEXT_PROJECT_ROOT_DIST, 'pages', '_app')]:
- 'next/dist/esm/pages/_app',
- [path.join(
- NEXT_PROJECT_ROOT_DIST,
- 'client',
- 'components',
- 'navigation'
- )]: 'next/dist/esm/client/components/navigation',
- [path.join(
- NEXT_PROJECT_ROOT_DIST,
- 'client',
- 'components',
- 'headers'
- )]: 'next/dist/esm/client/components/headers',
+ ...createNextApiEsmAliases(),
  }
  : undefined),
 
@@ -233,6 +193,46 @@ export function createServerOnlyClientOnlyAliases(
  }
 }
 
+export function createNextApiEsmAliases() {
+ const mapping = {
+ head: 'next/dist/api/head',
+ image: 'next/dist/api/image',
+ constants: 'next/dist/api/constants',
+ router: 'next/dist/api/router',
+ dynamic: 'next/dist/api/dynamic',
+ script: 'next/dist/api/script',
+ link: 'next/dist/api/link',
+ navigation: 'next/dist/api/navigation',
+ headers: 'next/dist/api/headers',
+ og: 'next/dist/api/og',
+ // pages api
+ document: 'next/dist/api/document',
+ app: 'next/dist/api/app',
+ }
+ const aliasMap: Record<string, string> = {}
+ // Handle fully specified imports like `next/image.js`
+ for (const [key, value] of Object.entries(mapping)) {
+ const nextApiFilePath = path.join(NEXT_PROJECT_ROOT, key)
+ aliasMap[nextApiFilePath + '.js'] = value
+ }
+
+ return aliasMap
+}
+
+export function createAppRouterApiAliases() {
+ const mapping = {
+ head: 'next/dist/client/components/noop-head',
+ dynamic: 'next/dist/api/app-dynamic',
+ }
+
+ const aliasMap: Record<string, string> = {}
+ for (const [key, value] of Object.entries(mapping)) {
+ const nextApiFilePath = path.join(NEXT_PROJECT_ROOT, key)
+ aliasMap[nextApiFilePath + '.js'] = value
+ }
+ return aliasMap
+}
+
 export function createRSCAliases(
  bundledReactChannel: string,
  {
@@ -371,14 +371,3 @@ function getReactProfilingInProduction(): CompilerAliases {
  'react-dom$': 'react-dom/profiling',
  }
 }
-export function createServerComponentsNoopAliases(): CompilerAliases {
- return {
- [require.resolve('next/head')]: require.resolve(
- 'next/dist/client/components/noop-head'
- ),
- // Alias next/dynamic
- [require.resolve('next/dynamic')]: require.resolve(
- 'next/dist/shared/lib/app-dynamic'
- ),
- }
-}

packages/next/src/build/webpack-config.ts

@@ -9,7 +9,11 @@ import semver from 'next/dist/compiled/semver'
 import { escapeStringRegexp } from '../shared/lib/escape-regexp'
 import { WEBPACK_LAYERS, WEBPACK_RESOURCE_QUERIES } from '../lib/constants'
 import type { WebpackLayerName } from '../lib/constants'
-import { isWebpackDefaultLayer, isWebpackServerLayer } from './utils'
+import {
+ isWebpackAppLayer,
+ isWebpackDefaultLayer,
+ isWebpackServerLayer,
+} from './utils'
 import type { CustomRoutes } from '../lib/load-custom-routes.js'
 import {
  CLIENT_STATIC_FILES_RUNTIME_AMP,
@@ -71,10 +75,13 @@ import {
  edgeConditionNames,
 } from './webpack-config-rules/resolve'
 import { OptionalPeerDependencyResolverPlugin } from './webpack/plugins/optional-peer-dependency-resolve-plugin'
-import { createWebpackAliases } from './create-compiler-aliases'
-import { createServerOnlyClientOnlyAliases } from './create-compiler-aliases'
-import { createRSCAliases } from './create-compiler-aliases'
-import { createServerComponentsNoopAliases } from './create-compiler-aliases'
+import {
+ createWebpackAliases,
+ createServerOnlyClientOnlyAliases,
+ createRSCAliases,
+ createNextApiEsmAliases,
+ createAppRouterApiAliases,
+} from './create-compiler-aliases'
 import { hasCustomExportOutput } from '../export/utils'
 
 type ExcludesFalse = <T>(x: T | false) => x is T
@@ -1263,18 +1270,12 @@ export default async function getBaseWebpackConfig(
  test: /next[\\/]dist[\\/](esm[\\/])?server[\\/]future[\\/]route-modules[\\/]app-page[\\/]module/,
  },
  {
- // All app dir layers need to use this configured resolution logic
- issuerLayer: {
- or: [
- WEBPACK_LAYERS.reactServerComponents,
- WEBPACK_LAYERS.serverSideRendering,
- WEBPACK_LAYERS.appPagesBrowser,
- WEBPACK_LAYERS.actionBrowser,
- WEBPACK_LAYERS.shared,
- ],
- },
+ issuerLayer: isWebpackAppLayer,
  resolve: {
- alias: createServerComponentsNoopAliases(),
+ alias: {
+ ...createNextApiEsmAliases(),
+ ...createAppRouterApiAliases(),
+ },
  },
  },
  ]

packages/next/src/lib/constants.ts

@@ -171,6 +171,7 @@ const WEBPACK_LAYERS = {
  WEBPACK_LAYERS_NAMES.appRouteHandler,
  WEBPACK_LAYERS_NAMES.serverSideRendering,
  WEBPACK_LAYERS_NAMES.appPagesBrowser,
+ WEBPACK_LAYERS_NAMES.shared,
  ],
  },
 }

packages/next/taskfile.js

@@ -2367,6 +2367,7 @@ export async function next_compile(task, opts) {
  'bin',
  'server',
  'server_esm',
+ 'api_esm',
  'nextbuild',
  'nextbuildjest',
  'nextbuildstatic',
@@ -2452,6 +2453,16 @@ export async function server_esm(task, opts) {
  .target('dist/esm/server')
 }
 
+// Provide ESM entry files for Next.js apis,
+// Remain in ESM both for dist/ and dist/esm
+export async function api_esm(task, opts) {
+ await task
+ .source('src/api/**/*.+(js|mts|ts|tsx)')
+ .swc('server', { dev: opts.dev, esm: true })
+ .target('dist/api')
+ .target('dist/esm/api')
+}
+
 export async function nextbuild(task, opts) {
  await task
  .source('src/build/**/*.+(js|ts|tsx)', {
@@ -2639,6 +2650,7 @@ export default async function (task) {
  await task.watch('src/bin', 'bin', opts)
  await task.watch('src/pages', 'pages', opts)
  await task.watch('src/server', ['server', 'server_esm', 'server_wasm'], opts)
+ await task.watch('src/api', 'api_esm', opts)
  await task.watch(
  'src/build',
  ['nextbuild', 'nextbuild_esm', 'nextbuildjest'],

test/e2e/app-dir/app-alias/app-alias.test.ts

@@ -4,9 +4,6 @@ createNextDescribe(
  'app-dir alias',
  {
  files: __dirname,
- packageJson: {
- type: 'module',
- },
  skipDeployment: true,
  },
  ({ next, isNextStart }) => {

test/e2e/app-dir/app-esm-js/app/app/client-hooks-ext.js

@@ -0,0 +1,8 @@
+'use client'
+
+import { useRouter } from 'next/navigation.js'
+
+export function ClientHooks() {
+ useRouter()
+ return null
+}

test/e2e/app-dir/app-esm-js/app/app/client-hooks.js

@@ -0,0 +1,8 @@
+'use client'
+
+import { useRouter } from 'next/navigation'
+
+export function ClientHooks() {
+ useRouter()
+ return null
+}

test/e2e/app-dir/app-esm-js/app/app/components-ext.js

@@ -0,0 +1,18 @@
+import NextImage, { unstable_getImgProps } from 'next/image.js'
+import Link from 'next/link.js'
+import Script from 'next/script.js'
+
+import src from '../../public/test.jpg'
+
+export function Components() {
+ return (
+ <>
+ <NextImage className="img" src={src} />
+ <p className="unstable_getImgProps">{typeof unstable_getImgProps}</p>
+ <Link className="link" href="/client">
+ link
+ </Link>
+ <Script className="script" src="/test-ext.js" />
+ </>
+ )
+}

test/e2e/app-dir/app-esm-js/app/app/components.js

@@ -0,0 +1,18 @@
+import NextImage, { unstable_getImgProps } from 'next/image'
+import Link from 'next/link'
+import Script from 'next/script'
+
+import src from '../../public/test.jpg'
+
+export function Components() {
+ return (
+ <>
+ <NextImage className="img" src={src} />
+ <p className="unstable_getImgProps">{typeof unstable_getImgProps}</p>
+ <Link className="link" href="/client">
+ link
+ </Link>
+ <Script className="script" src="/test.js" />
+ </>
+ )
+}

test/e2e/app-dir/app-esm-js/app/app/hooks-ext.js

@@ -0,0 +1,8 @@
+import { ClientHooks } from './client-hooks-ext'
+import { headers, cookies } from 'next/headers.js'
+
+export function useHooks() {
+ headers()
+ cookies()
+ return <ClientHooks />
+}

test/e2e/app-dir/app-esm-js/app/app/hooks.js

@@ -0,0 +1,8 @@
+import { ClientHooks } from './client-hooks'
+import { headers, cookies } from 'next/headers'
+
+export function useHooks() {
+ headers()
+ cookies()
+ return <ClientHooks />
+}

test/e2e/app-dir/app-esm-js/app/app/page.js

@@ -0,0 +1,20 @@
+import { useHooks } from './hooks'
+import { useHooks as useHooks2 } from './hooks-ext'
+import { Components } from './components'
+import { Components as Components2 } from './components-ext'
+
+export default function Page() {
+ useHooks()
+ useHooks2()
+
+ return (
+ <>
+ <div id="without-ext">
+ <Components />
+ </div>
+ <div id="with-ext">
+ <Components2 />
+ </div>
+ </>
+ )
+}

test/e2e/app-dir/app-esm-js/app/layout.js

@@ -0,0 +1,12 @@
+export const metadata = {
+ title: 'Next.js',
+ description: 'Generated by Next.js',
+}
+
+export default function RootLayout({ children }) {
+ return (
+ <html lang="en">
+ <body>{children}</body>
+ </html>
+ )
+}