Utilities for building Next.js applications with Bazel and rules_js.

All invocations of Next.js are done through a next_js_binary target passed into the macros. This is normally generated once alongside the package.json containing the next dependency:

load("@npm//:next/package_json.bzl", next_bin = "bin")

next_bin.next_binary(
    name = "next_js_binary",
    visibility = ["//visibility:public"],
)

The next binary is then passed into the macros, for example:

nextjs_build(
    name = "next",
    config = "next.config.mjs",
    srcs = glob(["src/**"]),
    next_js_binary = "//:next_js_binary",
)

Macros

There are two sets of macros for building Next.js applications: standard and standalone.

Standard

• nextjs(): wrap the build+dev+start targets
• nextjs_build(): the Next.js build command
• nextjs_dev(): the Next.js dev command
• nextjs_start(): the Next.js start command, accepting a Next.js build artifact to start

Standalone

For standalone applications:

• nextjs_standalone_build(): the Next.js build command, configured for a standalone application within bazel
• nextjs_standalone_server(): constructs a standalone Next.js server js_binary following the standalone directory structure guidelines

nextjs

Generates Next.js build, dev & start targets.

{name} - a Next.js production bundle {name}.dev - a Next.js devserver {name}.start - a Next.js prodserver

Use this macro in the BUILD file at the root of a next app where the next.config.mjs file is located.

For example, a target such as //app:next in app/BUILD.bazel

next(
    name = "next",
    config = "next.config.mjs",
    srcs = glob(["src/**"]),
    data = [
        "//:node_modules/next",
        "//:node_modules/react-dom",
        "//:node_modules/react",
        "package.json",
    ],
    next_js_binary = "//:next_js_binary",
)

will create the targets:

//app:next
//app:next.dev
//app:next.start

To build the above next app, equivalent to running next build outside Bazel:

bazel build //app:next

To run the development server in watch mode with ibazel, equivalent to running next dev outside Bazel:

ibazel run //app:next.dev

To run the production server in watch mode with ibazel, equivalent to running next start outside Bazel:

ibazel run //app:next.start

PARAMETERS

Name	Description	Default Value
name	the name of the build target	none
srcs	Source files to include in build & dev targets. Typically these are source files or transpiled source files in Next.js source folders such as pages, public & styles.	none
next_js_binary	The next js_binary target to use for running Next.js Typically this is a js_binary target created using bin loaded from the package_json.bzl file of the npm package. See main docstring above for example usage.	none
config	the Next.js config file. Typically next.config.mjs.	"next.config.mjs"
data	Data files to include in all targets. These are typically npm packages required for the build & configuration files such as package.json and next.config.js.	[]
serve_data	Data files to include in devserver targets	[]
kwargs	Other attributes passed to all targets such as tags.	none

nextjs_build

Build the Next.js production artifact.

See https://nextjs.org/docs/pages/api-reference/cli/next#build

PARAMETERS

Name	Description	Default Value
name	the name of the build target	none
config	the Next.js config file	none
srcs	the sources to include in the build, including any transitive deps	none
next_js_binary	The next js_binary target to use for running Next.js Typically this is a js_binary target created using bin loaded from the package_json.bzl file of the npm package. See main docstring above for example usage.	none
data	the data files to include in the build	[]
kwargs	Other attributes passed to all targets such as tags, env	none

nextjs_dev

Run the Next.js development server.

See https://nextjs.org/docs/pages/api-reference/cli/next#next-dev-options

PARAMETERS

Name	Description	Default Value
name	the name of the build target	none
config	the Next.js config file	none
srcs	the sources to include in the build, including any transitive deps	none
data	additional devserver runtime data	none
next_js_binary	The next js_binary target to use for running Next.js Typically this is a js_binary target created using bin loaded from the package_json.bzl file of the npm package. See main docstring above for example usage.	none
kwargs	Other attributes passed to all targets such as tags, env	none

nextjs_standalone_build

Compile a standalone Next.js application.

See https://nextjs.org/docs/app/api-reference/config/next-config-js/output#automatically-copying-traced-files

NOTE: a next.config.mjs is generated, wrapping the passed config, to overcome Next.js limitation with bazel, rules_js and pnpm (with hoist=false, as required by rules_js).

Due to the generated next.config.mjs file the nextjs_standalone_build(config) must have a unique name or file path that does not conflict with standard Next.js config files.

Issues worked around by the generated config include:

• https://github.com/vercel/next.js/issues/48017
• https://github.com/aspect-build/rules_js/issues/714

PARAMETERS

Name	Description	Default Value
name	the name of the build target	none
config	the Next.js config file	none
srcs	the sources to include in the build, including any transitive deps	none
next_js_binary	the Next.js binary to use for building	none
data	the data files to include in the build	[]
kwargs	Other attributes passed to all targets such as tags, env	none

nextjs_standalone_server

Configures the output of a standalone Next.js application to be a standalone server binary.

See the Next.js standalone server documentation for details on the standalone server directory structure.

This function is normally used in conjunction with nextjs_standalone_build to create a standalone Next.js application. The standalone server is a js_binary target that can be run with bazel run or deployed in a container image etc.

PARAMETERS

Name	Description	Default Value
name	the name of the binary target	none
app	the standalone app directory, typically the output of nextjs_standalone_build	none
pkg	the directory server.js is in within the standalone/ directory. This is normally the application path relative to the pnpm-lock.yaml. Default: native.package_name() (for a pnpm-lock.yaml in the root of the workspace)	None
data	runtime data required to run the standalone server. Normally requires [":node_modules/next", ":node_modules/react"] which are not included in the Next.js standalone output.	[]
kwargs	additional js_binary attributes	none

nextjs_start

Run the Next.js production server for an app.

See https://nextjs.org/docs/pages/api-reference/cli/next#next-start-options

PARAMETERS

Name	Description	Default Value
name	the name of the build target	none
config	the Next.js config file	none
app	the pre-compiled Next.js application, typically the output of nextjs_build	none
next_js_binary	The next js_binary target to use for running Next.js Typically this is a js_binary target created using bin loaded from the package_json.bzl file of the npm package. See main docstring above for example usage.	none
data	additional server data	[]
kwargs	Other attributes passed to all targets such as tags, env	none