Skip to content

Latest commit

 

History

History
270 lines (182 loc) · 12.1 KB

nextjs.md

File metadata and controls

270 lines (182 loc) · 12.1 KB

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

nextjs(name, srcs, next_js_binary, config, data, serve_data, kwargs)

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

nextjs_build(name, config, srcs, next_js_binary, data, kwargs)

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

nextjs_dev(name, config, srcs, data, next_js_binary, kwargs)

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

nextjs_standalone_build(name, config, srcs, next_js_binary, data, kwargs)

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

nextjs_standalone_server(name, app, pkg, data, kwargs)

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

nextjs_start(name, config, app, next_js_binary, data, kwargs)

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