Handling basePath Dynamically in a Docker Deployment

[cfeltz-isia]

Goals

Be able to generate a docker image allowing to deploy a NextJs application working both with a pathPrefix (bastPath) and without.

Non-Goals

No response

Background

When deploying a Next.js application in a Docker container, the basePath and NEXT_PUBLIC_BASE_URL must be known at build time, which complicates deployments across multiple environments.

A common workaround is:
Defining constants at build time (basePath, NEXT_PUBLIC_BASE_URL, etc.).
Using an entrypoint.sh script with sed to replace these constants at runtime.

However, this approach has a major limitation:
If no basePath is set at build time, Next.js defaults to "/", which causes issues (routes not found, broken redirects, etc.).
This makes it impossible to create a single Docker image that works both with and without a basePath.

When basePath is not explicitly defined, Next.js treats it as "/", which is problematic because:
Routes are not resolved correctly.
Redirects do not work as expected.
It prevents an image from being reused in different environments dynamically.

The common workaround example with limitations:

.env.production

URL_PREFIX=___ENV_URL_PREFIX___
URL_PATH_PREFIX=___ENV_URL_PATH_PREFIX___
NEXT_PUBLIC_BASE_URL=___ENV_NEXT_PUBLIC_BASE_URL___
RUNTIME_MODE=prod

next.config.js

/** @type {import('next').NextConfig} */
const path = require("path");

const getBasepath = () => {
  if (
    process.env.URL_PATH_PREFIX &&
    process.env.URL_PATH_PREFIX.trim() !== ""
  ) {
    return "/" + process.env.URL_PATH_PREFIX;
  } else {
    /* 
    NextJs configuration is executed at compile time, we never enter here because 
    URL_PATH_PREFIX = "___ENV_URL_PATH_PREFIX___".
    This implies that basePath will be equal to "/" if the pathPrefix environment variable is empty
    */
    return "";
  }
}

const nextConfig = {
  webpack(config) {
  basePath: getBasepath(),
  output: getOutput(),
};

module.exports = nextConfig;

DockerFile

FROM node:20-alpine as base

FROM base as build
WORKDIR /app
COPY Frontends/package.json /app/package.json
COPY Frontends/package-lock.json /app/package-lock.json
# install dependencies
RUN npm install --frozen-lockfile
COPY Frontends/. .

# list package versions
RUN npm list --depth=0 

# build
ENV NEXTJS_STANDALONE 1
RUN npm run build
# remove dev dependencies
RUN npm prune --production

FROM base AS runner
WORKDIR /app
ENV NODE_ENV production

# copy from build image
COPY --from=build /app/public ./public
COPY --from=build /app/.next/standalone ./
COPY --from=build /app/.next/static ./.next/static

ENV NEXTJS_STANDALONE 1
COPY --from=build /app/entrypoint.sh ./entrypoint.sh
RUN sed -i 's/\r//' /app/entrypoint.sh
RUN chmod +x /app/entrypoint.sh
ENTRYPOINT ["/app/entrypoint.sh"]

EXPOSE 3000

CMD ["node", "server.js"]

entrypoint.sh

#!/bin/sh
rule="s#___ENV_URL_PREFIX___#$URL_PREFIX#g; \
      s#___ENV_URL_PATH_PREFIX___#$URL_PATH_PREFIX#g; \
      s#___ENV_NEXT_PUBLIC_BASE_URL___#$NEXT_PUBLIC_BASE_URL#g;"

if [ "$NEXTJS_STANDALONE" == 1 ]
then
    echo "Apply sed rule on /app/.next folder and /app/server.js ($rule)"
    find /app/.next \( -type d -name .git -prune \) -o -type f -print0 | xargs -0 sed -i "${rule}"
    sed -i "${rule}" /app/server.js
else
    echo "Apply sed rule on /app/.next folder ($rule)"
    find /app/.next \( -type d -name .git -prune \) -o -type f -print0 | xargs -0 sed -i "${rule}"
fi

echo "Starting Nextjs"
exec "$@"

Workaround
There is a workaround that consists of adding a compilation argument to the docker build command that specifies whether the generated image is made for deployment with or without a path prefix. But this requires compiling two separate images.

const getBasepath = () => {
  let returnValue = '';
  if(process.env.WITH_PATHPREFIX == 1) {
    returnValue =  '/' + process.env.URL_PATH_PREFIX;
  }
  return returnValue;
}

Proposal

Would it be possible for Next.js to:

1. Treat nextConfig.basePath = "/" as if it were empty ("").
2. More generally, ignore any trailing "/" in the basePath
   This would significantly improve flexibility when deploying in Docker and avoid the need for environment-specific images.