<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:
## For Contributors
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide
### Fixing a bug
- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
### Adding a feature
- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
## For Maintainers
- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change
### What?
### Why?
### How?
Closes NEXT-
Fixes #
-->
### What?
Update config files in the `with-docker` example inside the
`.dockerignore`
### Why?
They are outdated
### How?
Add lines
cc @icyJoseph
---------
Co-authored-by: Joseph <sephxd1234@gmail.com>
- Remove BuildKit cache mount on `.next/cache` that trapped fetch cache
in a volume unreachable by the runner stage
- Restore `mkdir .next && chown` in runner stage for writable prerender
cache
- Add commented-out `COPY .next/cache` line as opt-in for persisting
build-time fetch cache
- Apply same fixes to `Dockerfile.bun` (only needed the `mkdir`/`chown`,
it never had the BuildKit mount)
Closes#90648
## What?
Modernizes the existing `with-docker` example and adds a new
`with-docker-export-output` example demonstrating different Next.js
deployment strategies with Docker best practices:
1. **`with-docker` (updated)** - Modernized to use App Router,
TypeScript, Tailwind CSS v4, and comprehensive Docker best practices.
Now includes both Node.js and Bun Dockerfile options, Docker Compose
with profiles, BuildKit cache mounts, and extensive documentation.
2. **`with-docker-export-output` (new)** - Demonstrates Next.js static
export mode deployment with Docker, offering two serving options:
**Nginx** (production-grade) and **serve** package (Node.js-based,
simpler setup). Includes optimized Nginx configuration, BuildKit cache
mounts, and comprehensive documentation.
Both examples include detailed documentation explaining Docker best
practices, implementation decisions, and deployment guidance.
## Why?
The existing `with-docker` example was using the Pages Router and
lacked:
- Modern Next.js patterns (App Router, TypeScript)
- Detailed documentation explaining Docker best practices and
implementation decisions
- BuildKit cache mounts for optimized build performance
- Bun runtime support as an alternative to Node.js
- Docker Compose configurations for easier local development
- Clear documentation about Node.js image variant choices (slim vs
Alpine)
- Examples demonstrating static export mode
These updates serve as comprehensive references for developers who want
to understand:
- How to Dockerize Next.js applications for different deployment
scenarios
- Why certain choices are made and how to optimize Docker setups for
production
- When to use standalone mode vs static export mode
- How to choose between Node.js and Bun runtimes
- How to choose between different web servers (Nginx vs serve) for
static sites
## How?
### `with-docker` example (updated)
- **Migrated to App Router** with TypeScript and Tailwind CSS v4
- **Multi-stage Dockerfile** with three stages: dependencies
installation, build, and runtime
- **Bun support** via `Dockerfile.bun` with optimized configuration
- **BuildKit cache mounts** for package manager stores (`npm`, `yarn`,
`pnpm`, `bun`) and Next.js build cache
- **Security best practices** with non-root user execution (built-in
`node` and `bun` users)
- **Docker Compose configuration** with profiles for Node.js (default)
and Bun
- **Comprehensive `.dockerignore`** to minimize build context size
- **Detailed README** explaining standalone mode benefits, Node.js image
choices, and deployment guidance
- **Deleted** `with-docker-standalone-output` (merged into this example)
### `with-docker-export-output` example (new)
- **Two Dockerfile options:**
- `Dockerfile` - Nginx-based serving with `nginxinc/nginx-unprivileged`
for security
- `Dockerfile.serve` - Node.js serve package-based serving for simpler
deployments
- **Multi-stage builds** for both options with separate dependency,
build, and runtime stages
- **BuildKit cache mounts** for package manager stores and Next.js build
cache
- **Production Nginx configuration** (`nginx.conf`) with gzip
compression, caching headers, and security best practices
- **Docker Compose configuration** supporting both serving options via
profiles
- **Comprehensive README** explaining static export mode, trade-offs
between Nginx and serve
### Docker best practices implemented (both examples)
| Practice | Description |
|----------|-------------|
| Multi-stage builds | Optimal image size reduction |
| Layer caching | Package files copied first |
| Minimal build context | Comprehensive `.dockerignore` files |
| BuildKit cache mounts | Faster subsequent builds |
| Security hardening | Non-root user execution |
| Corepack | yarn/pnpm version management |
| Package manager auto-detection | npm, yarn, pnpm support |
| Node.js 24.13.0-slim | Clear upgrade guidance |
## Breaking Changes
> **Warning**
> - `with-docker` now uses App Router instead of Pages Router
> - `with-docker-standalone-output` has been removed (merged into
`with-docker`)
---
**Note:** After this PR is approved and merged, I plan to open a
follow-up PR to update the Next.js documentation with proper links to
these Docker examples.
---------
Co-authored-by: Wyatt Johnson <accounts+github@wyattjoh.ca>
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Co-authored-by: kristiyan.velkov <kristiyan.velkov@ffw.com>
<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:
## For Contributors
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide
### Fixing a bug
- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
### Adding a feature
- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
## For Maintainers
- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change
-->
(sorry for my bad english)
### What?
Change `/examples/with-docker/Dockerfile.bun` to use group/useradd
instead of addgroup/user.
### Why?
Currently, the `docker build` command results in an error
`/bin/sh: 1: addgroup: not found`.
(related issue: oven-sh/bun#25441)
### How?
I changed the addgroup/user command to user/groupadd as a workaround.
[#](https://github.com/oven-sh/bun/issues/25441#issuecomment-3668036074)
fixes#87722.
---------
Co-authored-by: Joseph <sephxd1234@gmail.com>
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
### What?
Expanded the `with-docker` example for usage with `bun` and added build
instructions to the README.
### Why?
The existing example supports npm, yarn and pnpm, but not bun.
### How?
- Add a separate Dockerfile.bun placed next to the existing Dockerfile,
which is more sensible for the existing solution.
- Dockerfile.bun uses the official oven/bun base image (different
runtime/tooling than node:18-alpine), so a separate file should be
clearer.
- Existing Docker commands in the README remain unchanged, because
Docker still uses the existing Dockerfile by default.
- The bun example can be built with: `docker build -f Dockerfile.bun -t
nextjs-docker .`
Related to #78465, #82998
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-authored-by: Joseph <sephxd1234@gmail.com>
This PR updates all example Dockerfiles that were using `node:18-alpine`
to `node:20-alpine`
to align with current LTS and address known issues in Node 18 images.
- examples/with-docker/Dockerfile
- examples/with-docker-compose/next-app/prod.Dockerfile
- examples/with-docker-compose/next-app/dev.Dockerfile
- examples/with-docker-multi-env/docker/development/Dockerfile
- examples/with-docker-multi-env/docker/production/Dockerfile
- examples/with-docker-multi-env/docker/staging/Dockerfile
I verified local builds for each example. No behavior changes;
docs/examples only.
https://github.com/vercel/next.js/issues/78465
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
## What?
Update examples `.gitignore` files for parity with [Yarn's official
recommendations](https://v3.yarnpkg.com/getting-started/qa#which-files-should-be-gitignored),
accounting for Yarn's modern Plug-n-Play functionality.
## Why?
New projects initialized with `create-next-app` presently add various
extraneous files from the Yarn cache to the initial commit. This is most
notable in the case of the Next SWC binary, which may exceed 100M in
some environments (empirically, 64-bit Darwin and WSL2 Ubuntu, and very
probably other unix/linux environments), and prevent users from pushing
their new projects to free GitHub repositories without rewriting the
commit history to exclude the extraneous files, or unnecessarily setting
up Git LFS to include them.
## How?
I have errored on the side of exclusion to enable users to push their
CNA projects to GitHub as-is and for parity with other package managers,
while still providing the opportunity to opt in to additional
functionality provided by modern Yarn.
These changes follow the recommendations for
**non**-[Zero-Install](https://yarnpkg.com/features/caching#zero-installs)
configurations, as Zero-Install functionality is an extension on top of
the base package manager experience, and may necessitate additional
configuration and present additional complications for unsuspecting
users, so I think it's best left up to the user to opt-in. On account of
the majority of publicly available Next.js-based projects comprising
general consumer-facing websites, it is my belief that the majority of
Next projects would not benefit from Yarn's Zero-Install functionality,
and that explicitly facilitating it by default would break status quo
with all other non-Yarn CNA projects.
Contrary to the example `.gitignore`s provided by Yarn, I've excluded
the `.yarn/sdks` directory as it contains IDE-specific tooling; I feel
it would be presumptuous for an environmentally-agnostic tool to target
and provide package-manager-specific tooling for specific editors. This
too should be left to the user to opt-in to and provide for their
project if they deem necessary.
I have retained the current `.gitignore`'s exclusion of the `/.pnp`
directory for backwards compatibility with older versions of Yarn (the
files therein have since been reallocated to the `.yarn` directory
addressed by these changes, but I am not clear on when that delineation
occurred or the prevalence of Yarn installations which depend on the
former convention). Maintaining the exclusion here, in the worst case,
implies additional downloads (on an order of magnitude merely similar to
using npm from the outset) rather than failure.
CC: @samcx
### Adding or Updating Examples
- [x] The "examples guidelines" are followed from our contributing doc
https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md
- [x] Make sure the linting passes by running `pnpm build && pnpm lint`.
See
https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md
Co-authored-by: Sam Ko <sam@vercel.com>
### Description:
This PR updates the Dockerfile in the `examples/with-docker` folder to
include the `.npmrc` file in the dependency copy command.
### Original Command:
```dockerfile
# Install dependencies based on the preferred package manager
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
```
### Updated Command:
```dockerfile
# Install dependencies based on the preferred package manager
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc ./
```
### Reason for Change:
Including `.npmrc` allows for custom npm configurations, such as
`legacy-peer-deps=true`. Without this option, some installations can
fail due to unresolved peer dependencies, particularly for projects with
older dependencies.
This update ensures that any additional configurations specified in
`.npmrc` are applied during installation, improving Docker build
consistency and stability for projects with custom npm requirements.
### Diff:
```diff
- COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
+ COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc ./
```
---------
Co-authored-by: JJ Kasper <jj@jjsweb.site>
### What?
Update docker examples to correctly set HOSTNAME env variable for
standalone output
Related to PR:
https://github.com/vercel/next.js/pull/52804
### Why?
### TL;DR
The dockerfiile examples need to modified as that contains HOSTNAME
setting that apparently is not working as expected.
Related to Issue:
https://github.com/vercel/next.js/issues/58657
Affected examples:
https://github.com/vercel/next.js/tree/canary/examples/with-dockerhttps://github.com/vercel/next.js/tree/canary/examples/with-docker-multi-env
### Longer explanations
Based on [Docker
document](https://docs.docker.com/engine/reference/builder/#environment-replacement):
> You can also use environment variables with RUN, CMD, and ENTRYPOINT
instructions, but in those cases the variable substitution is handled by
the command shell, not the builder.
It means that when executing the last CMD ( `node server.js` ) in
Dockerfile samples, the HOSTNAME defined by prior `ENV` instruction is
simply ignored.
This causes problems typically when the host process sets HOSTNAME -
e.g. for instance when using AWS Fargate for deployment [we can't have
control over HOSTNAME](https://stackoverflow.com/a/52871552) set by the
host process. (also refer to the issue #58657 above)
### How?
Updated Dockerfilie samples, by setting HOSTNAME directly in CMD
instruction that launches nextjs server, not in the builder process.
Used this setting at my end (with AWS Fargate) to confirm that it fixes
the network problem.
Closes NEXT-
Fixes#58657
Co-authored-by: Sam Ko <sam@vercel.com>
<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:
## For Contributors
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide
### Adding or Updating Examples
- The "examples guidelines" are followed from our contributing doc
https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md
- Make sure the linting passes by running `pnpm build && pnpm lint`. See
https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md
### Fixing a bug
- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
### Adding a feature
- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
## For Maintainers
- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change
### What?
### Why?
### How?
Closes NEXT-
Fixes #
-->
### What
This pr addresses an issue in Docker where the cache and the creation of
its contents throw the following error:
```
[Error: EACCES: permission denied, mkdir '/app/.next/cache'] {
errno: -13,
code: 'EACCES',
syscall: 'mkdir',
path: '/app/.next/cache'
```
Co-authored-by: Sam Ko <sam@vercel.com>
### Adding or Updating Examples
- Example:
[with-docker](https://github.com/vercel/next.js/tree/canary/examples/with-docker)
- Update: The latest change introduced in #61466 on the building process
of NextJS when the package manager is PNPM is currently throwing an
error (it works for npm though).
**To replicate the error:**
1. Checkout on the **with-docker** example
2. Install with PNPM so that it generates the pnpm-lock.yaml
3. Build the Docker image -> This will fail on the _builder stage_ step
that runs `pnpm run build`.
**Possible Solution:**
- Run `corepack enable pnpm` before building with pnpm
## Description
This PR ensures that the default prettier config is used for examples
and templates.
This config is compatible with `prettier@3` as well (upgrading prettier
is bigger change that can be a future PR).
## Changes
- Updated `.prettierrc.json` in root with `"trailingComma": "es5"` (will
be needed upgrading to prettier@3)
- Added `examples/.prettierrc.json` with default config (this will
change every example)
- Added `packages/create-next-app/templates/.prettierrc.json` with
default config (this will change every template)
## Related
- Fixes#54402
- Closes#54409
### Reason for making this change
https://yarnpkg.com/getting-started/qa#:~:text=yarn%2Finstall%2Dstate.,your%20workspaces%20all%20over%20again.
In the official documentation of `yarn`, it is stated that `.yarn/install-state.gz` is an optimization file that developer shouldn't ever have to commit. However, currently, when running `create-next-app`, `.yarn/install-state.gz` is being commited.
### Remaining work
I apologize for only modifying one template initially to initiate the discussion first.
If this change is agreed upon, it should be synchronized with other `.gitignore` templates. Would it be possible to follow a similar approach as in https://github.com/vercel/next.js/pull/47241? I would appreciate any assistance in syncing this change.
It seems the app router attempts to write its cache to both `.next/cache` and `.next/server` in docker.
This fix should fix standalone output server's error `Failed to update prerender cache... [Error: EACCES: permission denied...` when deployed in a docker container with the example Dockerfile.
Related discussion: https://github.com/vercel/next.js/discussions/51164
When I try to deploy to Google Cloud Run it fails after some
investigation I saw this line in
.next/standalone/server.js
```javascript
const hostname = process.env.HOSTNAME || 'localhost'
```
This some how make this log when i run docker
```shell
- ready started server on 172.17.0.2:3000, url: http://172.17.0.2:3000
```
I don't know why it's logging this address even if the server running on
localhost.
So this my fix
Set hostname to 0.0.0.0 to avoid deployment failing on Google cloud run.
### What?
In the Dockerfile example:
* Moves the `USER` command above the `COPY`s
* Removes the `--chown` on the `COPY`s
> **Note**
> I don't know for 100% sure this won't have unintended side effects. Part of my motivation for opening this PR is to sense check whether we will be causing a regression by making this change in our own projects.
>
> Please let me know if there's any concerns with this!
### Why?
Sonar security scanner flags this Dockerfile as having "security hotspots" due to the use of `--chown`
https://rules.sonarsource.com/docker/RSPEC-6504/
### How?
Make the `--chown`s redundant by setting the current user before doing the `COPY` commands.
This PR updates the minimum version of React used by examples from 17.0.2 to 18.2.0.
Fixes#41975
## Bug
- [x] Related issues linked using `fixes #41975`
- [ ] Integration tests added
- [ ] Errors have a helpful link attached, see `contributing.md`
## Feature
- [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR.
- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [ ] Errors have a helpful link attached, see `contributing.md`
## Documentation / Examples
- [x] Make sure the linting passes by running `pnpm build && pnpm lint`
- [x] The "examples guidelines" are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md)
Let's open the deploy link in a new window so the link isn't blocked
when running an an iframe, such as Stackblitz.
Previously, this would print the following error:
> Refused to display 'https://vercel.com/' in a frame because it set
'X-Frame-Options' to 'deny'
<!--
Thanks for opening a PR! Your contribution is much appreciated.
In order to make sure your PR is handled as smoothly as possible we request that you follow the checklist sections below.
Choose the right checklist for the change that you're making:
-->
## Summary
- Added jsdoc typing for all examples using `next.config.js`
- Added jsdoc typing for all examples using `tailwind.config.js`
## Documentation / Examples
- [x] Make sure the linting passes by running `pnpm lint`
- [x] The examples guidelines are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing.md#adding-examples)
the directory `/app/.next/standalone` already contains a copy of the package.json so we can skip copying it before we copy the standalone dir
## Documentation / Examples
- [x] Make sure the linting passes by running `pnpm lint`
- [x] The examples guidelines are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing.md#adding-examples)
Co-authored-by: JJ Kasper <jj@jjsweb.site>
Joseph