Next.js static HTML export with Payload

[bratvanov]

Is it possible to use static exports with Payload in the same Next.js app?

Setting output: 'export' in the Next.js configuration breaks the Payload admin panel. I'm unsure if it's possible to conditionally define multiple output values in a single config file—for example, output: 'standalone' for /src/app/(payload) and output: 'export' for /src/app/(frontend).

This issue was discussed on Discord, where the suggested workaround was to use two separate Next.js apps: one for Payload and another for the front-end. However, this approach has significant drawbacks:

• It requires using the REST API instead of the faster Local API.
• It’s less efficient than a single-app setup, which was highlighted as a key advantage of Next.js integration in Payload 3.0 (front-end and back-end under one application).

[bratvanov]

Thanks to a discussion in vercel/next.js#81242 – it turns out Next.js static HTML export with Payload is indeed possible. For this, you need to use custom Next.js page extensions, for example, appending .static to the end of ts and js files to indicate these files should be part of the static build.

next.config.mjs

import { withPayload } from "@payloadcms/next/withPayload";

const isStaticMode = process.env.BUILD_MODE === 'static';

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Static pages always get included in all build types
  pageExtensions: ["static.tsx", "static.ts", "static.jsx", "static.js"],
};

if (isStaticMode) {
  nextConfig.output = "export";
  nextConfig.distDir = "dist";
} else {
  // Dynamic pages only get included when we are not doing a static build
  nextConfig.pageExtensions.push("tsx", "ts", "jsx", "js");
}

function withStaticPayload(nextConfig) {
  if (isStaticMode) {
    return nextConfig;
  } else {
    return withPayload(nextConfig);
  }
}

export default withStaticPayload(nextConfig);

package.json

"scripts": {
    "build:static": "cross-env BUILD_MODE=static next build && touch next.config.mjs",
},

Gerharddc has been kind to create an example repo here: https://github.com/Gerharddc/payload-ssg-example