Option to exclude folder and/or route group from build

[Gerharddc]

Goals

1. Provide an option in NextConfig to exclude a folder and/or a route group during the build process

Non-Goals

No response

Background

I would like to use Payload CMS to build a website that has two flavours. One flavour is the "full app" including the Payload admin portal which requires a full Next.js server and is intended only for internal use. The other flavour is a statically built version of the website that does not include an admin portal and can be easily hosted with just a CDN. The problem is that this requires excluding everything Payload-related (i.e. everything under src/app/(payload)) during a static build.

I have managed to get this working at https://github.com/Gerharddc/payload-ssg-example using a custom build script that temporarily renames the (payload) folder to _(payload) during the build so that it gets ignored during static builds. Even though this technically works, it is obviously not a great solution.

Proposal

Currently my next.config.mjs looks like this:

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

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

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Conditionally add output export for static mode
  ...(isStaticMode && {
    output: "export",
    distDir: "dist",
  }),
};

export default withPayload(nextConfig);

It would be great if there were an option named something like "excludeRouteGroups" in NextConfig so that I could just add excludeRouteGroups: ["payload"] during static builds so that I don't have to do the silly folder rename step.

[icyJoseph]

You can use this method with pageExtensions, #51891 (comment), just make sure to get the pageExtensions correct, you'd need sometihng like home.page.tsx IIRC.

You need to tweak it a bit though, but it should work.

[Gerharddc]

You can use this method with pageExtensions, #51891 (comment), just make sure to get the pageExtensions correct, you'd need sometihng like home.page.tsx IIRC.

You need to tweak it a bit though, but it should work.

Thanks! I'll give this a try but it does unfortunately feel like an awkward solution compared to just being able to exclude a specific folder or route group given that all filenames would become longer. Another potential issue is that the Payload files are partially auto-generated. This implies something somewhere might have expectations about exact filenames which could cause something to blow up unexpectedly in the future.

[Gerharddc]

Ok I have now managed to get this working with

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");
}

export default withPayload(nextConfig);

and by appending "static" to the file extension of pages which should get included in the static site build.

Even though this works good enough, I think it would still be more elegant if it were possible to filter using directories or route groups.

[icyJoseph]

That's definitely good feedback. I know the "carving out sections of the application" concept was more of a hack intially.

I only ever used in Pages Router too, where route groups wasn't a thing, or a any file within pages could be a route. With App Router, there's definitely conventions in place that could make this more doable.

Idk if monorepo tools can handle this somehow though - like one source of packages, that includes even pages (atomic design to the extreme) and then a small set of apps in the workspace, that only define file system routing. Then you could do pnpm --filter=docs-app build - something like that. Of course that's also involves more tooling and complexity, that not all projects need/want.

[adrianoresende]

That's definitely good feedback. I know the "carving out sections of the application" concept was more of a hack intially.

I only ever used in Pages Router too, where route groups wasn't a thing, or a any file within pages could be a route. With App Router, there's definitely conventions in place that could make this more doable.

Idk if monorepo tools can handle this somehow though - like one source of packages, that includes even pages (atomic design to the extreme) and then a small set of apps in the workspace, that only define file system routing. Then you could do pnpm --filter=docs-app build - something like that. Of course that's also involves more tooling and complexity, that not all projects need/want.

@icyJoseph @Gerharddc

Nice!! Interesting feedbacks.

I'm changing the structure of the project with pnpm workspace for the first time. I think that it is the best way for those who are learning to manage a monorepo.

In a scenario involving two projects that reuse components and blocks of payloads, I thought this structure.
What did you think?

Note: I thought that it was better to separate dynamic and static because of maintenance

/monorepo
├── package.json
├── pnpm-workspace.yaml
├── tsconfig.base.json
├── /payload
│   ├── package.json ←@payload must be installed here?
│   └── tsconfig.json
├── /next-static
│   ├── package.json
│   └── tsconfig.json
└── /shared
    ├── package.json
    └── tsconfig.json

And the tsconfig (next-static and shared) with path must pull the payload?

"paths": {
  "@/*": ["./*"],
  "@payload-types": ["../payload/src/payload-types.ts"],
  "@payload-config": ["../payload/src/payload.config.ts"]
}