Merge pull request #207 from mi-examples/feat/next-build-parity

feat: warn when a wrapped Next.js app builds via plain `next build`

Author: sergak01

README.md

@@ -371,6 +371,11 @@ ZIP archive. `pp-dev next-build` runs `next build` and then applies the same pos
 2. Writes `VERSION-*.json` + `BUILD-MANIFEST.json` into the export directory (`build.versionFile`)
 3. Zips the export directory into `dist-zip/<name>.zip` (`build.zip`)
 
+If a project using `withPPDev()` still runs plain `next build` (e.g. directly, or via a `build`
+script nobody updated), `withPPDev()` prints a console warning during the production build phase
+suggesting `pp-dev next-build` instead. The warning is suppressed automatically when the build was
+started by `pp-dev next-build` itself.
+
 Use it in place of `next build` in your `package.json`:
 
 ```json

src/cli.ts

@@ -33,6 +33,7 @@ import {
   PATH_PAGE_PREFIX,
   PATH_TEMPLATE_PREFIX,
   PATH_TEMPLATE_LOCAL_PREFIX,
+  PP_DEV_NEXT_BUILD_ENV_VAR,
 } from './constants.js';
 import { normalizePPDevConfig, validatePPDevConfig } from './plugin.js';
 import { RequestStore } from './lib/request-store.js';
@@ -1149,6 +1150,10 @@ cli
           let exportDistDir: string | undefined = config?.distDir;
 
           try {
+            // Not a real `next build` — just peeking at the prod config for distDir. Suppress
+            // withPPDev()'s "use pp-dev next-build" nudge for this internal lookup.
+            process.env[PP_DEV_NEXT_BUILD_ENV_VAR] = '1';
+
             const prodConfig = await loadConfig(constants.PHASE_PRODUCTION_BUILD, projectRoot);
 
             exportDistDir = prodConfig?.distDir ?? exportDistDir;
@@ -1564,6 +1569,10 @@ cli
       const projectRoot = root ? path.resolve(process.cwd(), root) : process.cwd();
       const cliOverrides = resolveBuildCliOverrides(options);
 
+      // Also covers the `loadConfig()` call below, which evaluates the Next.js config (and thus
+      // `withPPDev()`) in this process before `runNextBuildProcess()` spawns the actual `next build`.
+      process.env[PP_DEV_NEXT_BUILD_ENV_VAR] = '1';
+
       try {
         const { constants } = await safeNextImport();
 

src/constants.ts

@@ -36,6 +36,14 @@ export const PATH_PAGE_PREFIX = '/p';
 export const PATH_TEMPLATE_PREFIX = '/pt';
 export const PATH_TEMPLATE_LOCAL_PREFIX = '/pl';
 
+/**
+ * Set (to '1') in the child `next build` process spawned by `pp-dev next-build` (and the
+ * WS-triggered sync build in DistService). `withPPDev()` checks this during the production
+ * build phase to tell a wrapped `next build` apart from a bare one, so it can nudge users
+ * running `next build` directly toward `pp-dev next-build` (VERSION/BUILD-MANIFEST/zip parity).
+ */
+export const PP_DEV_NEXT_BUILD_ENV_VAR = 'PP_DEV_NEXT_BUILD';
+
 export const PP_DEV_CONFIG_NAMES = [
   '.pp-dev.config.js',
   '.pp-dev.config.cjs',

src/index.ts

@@ -8,8 +8,14 @@ import type { NextConfig } from 'next';
 import { safeNextImport } from './lib/next-import.js';
 import { getConfig, getPkg } from './config.js';
 import type { PPDevConfig } from './plugin.js';
-import { PATH_PAGE_PREFIX, PATH_TEMPLATE_PREFIX, PATH_TEMPLATE_LOCAL_PREFIX } from './constants.js';
+import {
+  PATH_PAGE_PREFIX,
+  PATH_TEMPLATE_PREFIX,
+  PATH_TEMPLATE_LOCAL_PREFIX,
+  PP_DEV_NEXT_BUILD_ENV_VAR,
+} from './constants.js';
 import { createLogger } from './lib/logger.js';
+import { colors } from './lib/helpers/color.helper.js';
 import { applyDistZipOverride, applyVersionManifestOverride, ResolvedBuildCliOverrides } from './lib/build-cli-overrides.js';
 
 export type { ResolvedBuildCliOverrides } from './lib/build-cli-overrides.js';
@@ -323,7 +329,15 @@ export function withPPDev(
   return async (phase: string, nextConfig: { defaultConfig?: any } = {}): Promise<NextConfig> => {
     try {
       const { constants } = await safeNextImport();
-      const { PHASE_DEVELOPMENT_SERVER } = constants;
+      const { PHASE_DEVELOPMENT_SERVER, PHASE_PRODUCTION_BUILD } = constants;
+
+      if (phase === PHASE_PRODUCTION_BUILD && !process.env[PP_DEV_NEXT_BUILD_ENV_VAR]) {
+        createLogger().warn(
+          colors.yellow(
+            '⚠ Building with plain `next build`. Use `pp-dev next-build` instead to get VERSION/BUILD-MANIFEST/zip build output in the same format as `pp-dev build` (see the "Next.js Build" section in the pp-dev README).',
+          ),
+        );
+      }
 
       const config = await getConfig();
       const pkg = getPkg();

src/lib/next-build-runner.ts

@@ -2,6 +2,7 @@ import * as path from 'path';
 import * as child_process from 'child_process';
 import * as process from 'process';
 import { createRequire } from 'module';
+import { PP_DEV_NEXT_BUILD_ENV_VAR } from '../constants.js';
 
 /** Run `next build` in `projectRoot`, resolving the `next` binary from the app itself. */
 export function runNextBuildProcess(projectRoot: string): Promise<void> {
@@ -21,7 +22,7 @@ export function runNextBuildProcess(projectRoot: string): Promise<void> {
 
     const proc = child_process.spawn(process.execPath, [nextBin, 'build'], {
       cwd: projectRoot,
-      env: Object.assign({}, process.env, { NODE_ENV: 'production' }),
+      env: Object.assign({}, process.env, { NODE_ENV: 'production', [PP_DEV_NEXT_BUILD_ENV_VAR]: '1' }),
       stdio: 'inherit',
     });