Skip to main content
Documentation for @aspect_rules_js@v3.0.0 — View source
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",
)
There are two sets of macros for building Next.js applications: standard and standalone.

​
Standard Build

  • 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 Mode

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

​
Function: 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
unknown
required
the name of the build target
​
srcs
unknown
required
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.
​
next_js_binary
unknown
required
The next js_binary target to use for running Next.jsTypically 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.
​
config
unknown
default:"next.config.mjs"
the Next.js config file. Typically next.config.mjs.
​
data
unknown
default:"[]"
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
unknown
default:"[]"
Data files to include in devserver targets
​
kwargs
unknown
Other attributes passed to all targets such as tags.

​
Function: nextjs_build

Build the Next.js production artifact. See https://nextjs.org/docs/pages/api-reference/cli/next#build

​
Parameters

​
name
unknown
required
the name of the build target
​
config
unknown
required
the Next.js config file
​
srcs
unknown
required
the sources to include in the build, including any transitive deps
​
next_js_binary
unknown
required
The next js_binary target to use for running Next.jsTypically 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.
​
data
unknown
default:"[]"
the data files to include in the build
​
kwargs
unknown
Other attributes passed to all targets such as tags, env

​
Function: 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
unknown
required
the name of the build target
​
config
unknown
required
the Next.js config file
​
app
unknown
required
the pre-compiled Next.js application, typically the output of nextjs_build
​
next_js_binary
unknown
required
The next js_binary target to use for running Next.jsTypically 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.
​
data
unknown
default:"[]"
additional server data
​
kwargs
unknown
Other attributes passed to all targets such as tags, env

​
Function: nextjs_dev

Run the Next.js development server. See https://nextjs.org/docs/pages/api-reference/cli/next#next-dev-options

​
Parameters

​
name
unknown
required
the name of the build target
​
config
unknown
required
the Next.js config file
​
srcs
unknown
required
the sources to include in the build, including any transitive deps
​
data
unknown
required
additional devserver runtime data
​
next_js_binary
unknown
required
The next js_binary target to use for running Next.jsTypically 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.
​
kwargs
unknown
Other attributes passed to all targets such as tags, env

​
Function: 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:

​
Parameters

​
name
unknown
required
the name of the build target
​
config
unknown
required
the Next.js config file
​
srcs
unknown
required
the sources to include in the build, including any transitive deps
​
next_js_binary
unknown
required
the Next.js binary to use for building
​
data
unknown
default:"[]"
the data files to include in the build
​
kwargs
unknown
Other attributes passed to all targets such as tags, env

​
Function: 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
unknown
required
the name of the binary target
​
app
unknown
required
the standalone app directory, typically the output of nextjs_standalone_build
​
pkg
unknown
default:"None"
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)
​
data
unknown
default:"[]"
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
unknown
additional js_binary attributes