> ## Documentation Index
> Fetch the complete documentation index at: https://site.aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# @aspect_rules_js//contrib/nextjs:defs.bzl

> Bazel rules_js contrib API for Next.js: macros to build, dev, start, and export Next.js JavaScript applications using a next_js_binary target.

<Callout icon="book">
  Documentation for [@aspect\_rules\_js@v3.0.3](https://registry.bazel.build/modules/aspect_rules_js/3.0.3) -- <Icon icon="github" iconType="brands" /> [View source](https://github.com/aspect-build/rules_js/blob/v3.0.3/contrib/nextjs/defs.bzl)
</Callout>

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](https://nextjs.org/docs/app/building-your-application/deploying#production-builds) command
* `nextjs_dev()`: the Next.js [dev](https://nextjs.org/docs/app/getting-started/installation#run-the-development-server) command
* `nextjs_start()`: the Next.js [start](https://nextjs.org/docs/app/building-your-application/deploying#nodejs-server) command,
  accepting a Next.js build artifact to start

### Standalone Mode

For [standalone applications](https://nextjs.org/docs/app/api-reference/config/next-config-js/output#automatically-copying-traced-files):

* `nextjs_standalone_build()`: the Next.js [build](https://nextjs.org/docs/app/building-your-application/deploying#production-builds) 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](https://nextjs.org/docs/app/api-reference/config/next-config-js/output#automatically-copying-traced-files)

## 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](https://github.com/bazelbuild/bazel-watcher), equivalent to running
`next dev` outside Bazel:

```
ibazel run //app:next.dev
```

To run the production server in watch mode with
[ibazel](https://github.com/bazelbuild/bazel-watcher), equivalent to running
`next start` outside Bazel:

```
ibazel run //app:next.start
```

### Parameters

<ParamField body="name" type="unknown" required>
  the name of the build target
</ParamField>

<ParamField body="srcs" type="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`.
</ParamField>

<ParamField body="next_js_binary" type="unknown" required>
  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.
</ParamField>

<ParamField body="config" type="unknown" default={`next.config.mjs`}>
  the Next.js config file. Typically `next.config.mjs`.
</ParamField>

<ParamField body="data" type="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.
</ParamField>

<ParamField body="serve_data" type="unknown" default={`[]`}>
  Data files to include in devserver targets
</ParamField>

<ParamField body="kwargs" type="unknown">
  Other attributes passed to all targets such as `tags`.
</ParamField>

## Function: `nextjs_build`

Build the Next.js production artifact.

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

### Parameters

<ParamField body="name" type="unknown" required>
  the name of the build target
</ParamField>

<ParamField body="config" type="unknown" required>
  the Next.js config file
</ParamField>

<ParamField body="srcs" type="unknown" required>
  the sources to include in the build, including any transitive deps
</ParamField>

<ParamField body="next_js_binary" type="unknown" required>
  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.
</ParamField>

<ParamField body="data" type="unknown" default={`[]`}>
  the data files to include in the build
</ParamField>

<ParamField body="kwargs" type="unknown">
  Other attributes passed to all targets such as `tags`, env
</ParamField>

## 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](https://nextjs.org/docs/pages/api-reference/cli/next#next-start-options)

### Parameters

<ParamField body="name" type="unknown" required>
  the name of the build target
</ParamField>

<ParamField body="config" type="unknown" required>
  the Next.js config file
</ParamField>

<ParamField body="app" type="unknown" required>
  the pre-compiled Next.js application, typically the output of `nextjs_build`
</ParamField>

<ParamField body="next_js_binary" type="unknown" required>
  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.
</ParamField>

<ParamField body="data" type="unknown" default={`[]`}>
  additional server data
</ParamField>

<ParamField body="kwargs" type="unknown">
  Other attributes passed to all targets such as `tags`, env
</ParamField>

## Function: `nextjs_dev`

Run the Next.js development server.

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

### Parameters

<ParamField body="name" type="unknown" required>
  the name of the build target
</ParamField>

<ParamField body="config" type="unknown" required>
  the Next.js config file
</ParamField>

<ParamField body="srcs" type="unknown" required>
  the sources to include in the build, including any transitive deps
</ParamField>

<ParamField body="data" type="unknown" required>
  additional devserver runtime data
</ParamField>

<ParamField body="next_js_binary" type="unknown" required>
  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.
</ParamField>

<ParamField body="kwargs" type="unknown">
  Other attributes passed to all targets such as `tags`, env
</ParamField>

## 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](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/vercel/next.js/issues/48017)
* [https://github.com/aspect-build/rules\_js/issues/714](https://github.com/aspect-build/rules_js/issues/714)

### Parameters

<ParamField body="name" type="unknown" required>
  the name of the build target
</ParamField>

<ParamField body="config" type="unknown" required>
  the Next.js config file
</ParamField>

<ParamField body="srcs" type="unknown" required>
  the sources to include in the build, including any transitive deps
</ParamField>

<ParamField body="next_js_binary" type="unknown" required>
  the Next.js binary to use for building
</ParamField>

<ParamField body="data" type="unknown" default={`[]`}>
  the data files to include in the build
</ParamField>

<ParamField body="kwargs" type="unknown">
  Other attributes passed to all targets such as `tags`, env
</ParamField>

## 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](https://nextjs.org/docs/app/api-reference/config/next-config-js/output#automatically-copying-traced-files)
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

<ParamField body="name" type="unknown" required>
  the name of the binary target
</ParamField>

<ParamField body="app" type="unknown" required>
  the standalone app directory, typically the output of `nextjs_standalone_build`
</ParamField>

<ParamField body="pkg" type="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)
</ParamField>

<ParamField body="data" type="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.
</ParamField>

<ParamField body="kwargs" type="unknown">
  additional `js_binary` attributes
</ParamField>