Next.js Serverless Build Tool

3.0.1 · active · verified Sun Apr 19

ns-build is a CLI utility designed to simplify the build process for Next.js applications intended for serverless deployment on AWS using Terraform. It primarily functions as a bash script, automating the steps required to prepare a Next.js project (specifically those configured with `output: 'standalone'`) for deployment. The current stable version is 3.1.1. It maintains a consistent release cadence with updates to support newer Next.js versions (e.g., v15, v16) and Node.js runtimes (e.g., Node 22, Node 24) on AWS Lambda. Its key differentiator is its tight integration with the `nextjs-serverless` Terraform module, providing a streamlined workflow from build to infrastructure deployment without requiring manual asset compilation or environment setup for AWS Lambda and CloudFront distributions.

Common errors

```
Cannot find module 'next/dist/server/next-server'
```
cause This error typically indicates a mismatch between the `ns-build` tool's expected Next.js version and the one installed in your project, or an incorrect `output` configuration.

fix Verify that your `next` peer dependency is satisfied (e.g., `^16.0.0` for `ns-build` v3) and that `output: 'standalone'` is correctly configured in your `next.config.js`.
```
Error: Command failed with exit code 1
```
cause A generic error indicating that the underlying build process invoked by the bash script failed. This could be due to issues within your Next.js project build itself.

fix Inspect the detailed output preceding this error for specific Next.js build failures (e.g., linting errors, missing dependencies, incorrect configurations). Try running `next build` directly to isolate the issue.

Warnings

breaking Version 3.x of ns-build requires Next.js v16+ and upgrades the AWS Lambda runtime to Node.js 24.
Fix: Ensure your Next.js project is compatible with Next.js v16 or later and update your AWS Lambda configuration to use Node.js 24. For earlier Next.js versions, use ns-build v2.x or earlier.
breaking Version 2.x of ns-build required Next.js v15+ and switched the AWS Lambda runtime to Node.js 22.
Fix: Update your Next.js project to v15 or later and ensure your AWS environment supports Node.js 22 for Lambda functions. Consider upgrading to ns-build v3.x and Node.js 24 for the latest support.
gotcha The `next.config.js` file MUST include `output: 'standalone'` for `ns-build` to correctly prepare your Next.js application for serverless deployment.
Fix: Add `output: 'standalone'` to your `next.config.js` configuration file to ensure the build output is in the expected format for the tool.
gotcha This package is a CLI tool (a bash script) and does not expose JavaScript/TypeScript modules for programmatic import. Its primary interaction is via the command line, typically through `npm run build` or `npx ns-build build`.
Fix: Do not attempt to `import` or `require` symbols from `ns-build` in your JavaScript or TypeScript code. Interact with it solely as a command-line utility.

Install

npm install ns-build npm
yarn add ns-build yarn
pnpm add ns-build pnpm

Quickstart

Demonstrates the package.json setup and `next.config.js` configuration for using `ns-build` with a Next.js project, followed by the build command.

{
  "name": "my-nextjs-app",
  "version": "0.1.0",
  "scripts": {
    "build": "ns-build build"
  },
  "dependencies": {
    "next": "^16.0.0",
    "react": "^18",
    "react-dom": "^18"
  },
  "devDependencies": {
    "ns-build": "^3.0.1"
  }
}
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
};
module.exports = nextConfig;

// Run the build command
// npm install
// npm run build

// The output will be in ./.ns-build and is intended to be used by the
// 'nextjs-serverless' Terraform module for deployment to AWS.

view raw JSON →