Docs for custom build command

Author: fwang

README.md

@@ -44,7 +44,7 @@ When calling `open-next build`, OpenNext **runs `next build`** to build the Next
 
 #### Building the Next.js app
 
-OpenNext runs the `build` script in your `package.json` file. Depending on the lock file found in the app, the corresponding packager manager will be used. Either `npm run build`, `yarn build`, or `pnpm build` will be run.
+OpenNext runs the `build` script in your `package.json` file. Depending on the lock file found in the app, the corresponding packager manager will be used. Either `npm run build`, `yarn build`, or `pnpm build` will be run. For more on customizing the build command, see [overriding the build command](#custom-build-command).
 
 #### Transforming the build output
 
@@ -430,44 +430,62 @@ Vercel link: https://open-next.vercel.app
 
 ## Advanced usage
 
-#### OPEN_NEXT_MINIFY
+#### Custom build command
 
-Enabling this option will minimize all `.js` and `.json` files in the server function bundle using the [node-minify](https://github.com/srod/node-minify) library. This can reduce the size of the server function bundle by about 40%, depending on the size of your app. To enable it, simply run:
+OpenNext runs the `build` script in your `package.json` by default. However, you can specify a custom build command if required.
 
 ```bash
-OPEN_NEXT_MINIFY=true open-next build
+# CLI
+open-next build --build-command "pnpm custom:build"
 ```
 
-Enabling this option can significantly help to reduce the cold start time of the server function. However, it's an **experimental feature**, and you need to opt-in to use it. Once this option is thoroughly tested and found to be stable, it will be enabled by default.
+```ts
+// JS
+import { build } from "open-next/build.js";
 
-## Debugging
+await build({
+  buildCommand: "pnpm custom:build",
+});
+```
 
-#### Function logs
+#### Minify server function
 
-To find the **server, image optimization, and warmer log**, go to the AWS CloudWatch console in the **region you deployed to**.
+Enabling this option will minimize all `.js` and `.json` files in the server function bundle using the [node-minify](https://github.com/srod/node-minify) library. This can reduce the size of the server function bundle by about 40%, depending on the size of your app.
 
-If the server function is **deployed to Lambda@Edge**, the logs will appear in the **region you are physically close to**. For example, if you deployed your app to `us-east-1` and you are visiting the app from in London, the logs are likely to be in `eu-west-2`.
-
-#### Warmer function logs
+```bash
+# CLI
+open-next build --minify
+```
 
-The logs from the warmer function provide insights into the results of the warming process.
+```ts
+// JS
+import { build } from "open-next/build.js";
 
-```
-{ event: 'warmer result', sent: 2, success: 2, uniqueServersWarmed: 2 }
+await build({
+  minify: true,
+});
 ```
 
-- `sent` — The number of times the warmer invoked the server function using the Lambda SDK. This value should correspond to the `CONCURRENCY` set in the warmer function.
-- `success` — The number of SDK calls that returned a 200 status code, indicating successful invocations.
-- `uniqueServersWarmed` — This helps track any instances that responded unusually quickly and served multiple warming requests. As all SDK calls are made concurrently using `await Promise.all()`, this metric is useful for monitoring the number of unique warmed instances.
+This feature is currently **experimental** and needs to be opted into. It can significantly decrease the server function's cold start time. Once it is thoroughly tested and its stability is confirmed, it will be enabled by default.
 
 #### Debug mode
 
-You can run OpenNext in debug mode by setting the `OPEN_NEXT_DEBUG` environment variable:
+OpenNext can be executed in debug mode for bug tracking purposes.
 
 ```bash
+# CLI
 OPEN_NEXT_DEBUG=true npx open-next@latest build
 ```
 
+```ts
+// JS
+import { build } from "open-next/build.js";
+
+await build({
+  debug: true,
+});
+```
+
 This does a few things:
 
 1. Lambda handler functions in the build output will not be minified.
@@ -479,6 +497,26 @@ It is recommended to **turn off debug mode when building for production** becaus
 1. Un-minified function code is 2-3X larger than minified code. This will result in longer Lambda cold start times.
 1. Logging the event object on each request can result in a lot of logs being written to AWS CloudWatch. This will result in increased AWS costs.
 
+## Debugging
+
+#### Function logs
+
+To find the **server, image optimization, and warmer log**, go to the AWS CloudWatch console in the **region you deployed to**.
+
+If the server function is **deployed to Lambda@Edge**, the logs will appear in the **region you are physically close to**. For example, if you deployed your app to `us-east-1` and you are visiting the app from in London, the logs are likely to be in `eu-west-2`.
+
+#### Warmer function logs
+
+The logs from the warmer function provide insights into the results of the warming process.
+
+```
+{ event: 'warmer result', sent: 2, success: 2, uniqueServersWarmed: 2 }
+```
+
+- `sent` — The number of times the warmer invoked the server function using the Lambda SDK. This value should correspond to the `CONCURRENCY` set in the warmer function.
+- `success` — The number of SDK calls that returned a 200 status code, indicating successful invocations.
+- `uniqueServersWarmed` — This helps track any instances that responded unusually quickly and served multiple warming requests. As all SDK calls are made concurrently using `await Promise.all()`, this metric is useful for monitoring the number of unique warmed instances.
+
 #### Opening an issue
 
 To help diagnose issues, it's always helpful to provide a reproducible setup when opening an issue. One easy way to do this is to create a pull request (PR) and add a new page to the [benchmark app](#example) located in the `example` folder, which reproduces the issue. The PR will automatically deploy the app to AWS.

packages/open-next/src/build.ts

@@ -7,9 +7,26 @@ import { buildSync, BuildOptions as ESBuildOptions } from "esbuild";
 import { createRequire as topLevelCreateRequire } from "node:module";
 
 interface BuildOptions {
+  /**
+   * Minify the server bundle.
+   * @default false
+   */
   minify?: boolean;
+  /**
+   * Print debug information.
+   * @default false
+   */
   debug?: boolean;
-  appPath?: string;
+  /**
+   * The command to build the Next.js app.
+   * @default `npm run build`, `yarn build`, or `pnpm build` based on the lock file found in the app's directory or any of its parent directories.
+   * @example
+   * ```ts
+   * build({
+   *   buildCommand: "pnpm custom:build",
+   * });
+   * ```
+   */
   buildCommand?: string;
 }
 
@@ -49,7 +66,7 @@ export async function build(opts: BuildOptions = {}) {
 }
 
 function normalizeOptions(opts: BuildOptions) {
-  const appPath = opts.appPath ?? process.cwd();
+  const appPath = process.cwd();
   const outputDir = ".open-next";
   return {
     appPath,

packages/open-next/src/index.ts

@@ -10,6 +10,7 @@ if (Object.keys(args).includes("--help")) printHelp();
 
 build({
   buildCommand: args["--build-command"],
+  minify: Object.keys(args).includes("--minify"),
 });
 
 function parseArgs() {