Next.js

This guide walks you through building and deploying a Next.js application to Magic Containers with GitHub Container Registry. You’ll need:

A GitHub account for source code and container registry

Don’t have a bunny.net account yet? Sign up and enable Magic Containers to get started.

Create the Next.js app

Create a new Next.js project:

npx create-next-app@latest app-nextjs
cd app-nextjs

Configure standalone output

Update your next.config.ts to enable standalone output mode for Docker:

next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "standalone",
};

export default nextConfig;

Create an API route

Create a simple API route to test the deployment:

app/api/route.ts

import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ message: "Hello from Bunny 🐰" });
}

Run locally

Start the development server:

npm run dev

Visit http://localhost:3000 in your browser, or test the API route:

curl http://localhost:3000/api

Create the Dockerfile

Dockerfile

FROM node:22-alpine AS base

FROM base AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM base AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
RUN if [ -d "/app/public" ]; then cp -r /app/public ./public; fi

ENV PORT=80
EXPOSE 80

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

Pass build-time variables

next build inlines NEXT_PUBLIC_ variables and bakes in anything next.config.ts reads, and docker build doesn’t read your shell’s environment. Declare each one as an ARG in the builder stage, or the build runs without it:

Dockerfile

FROM base AS builder
WORKDIR /app
ARG NEXT_PUBLIC_CDN_URL
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

Pass the value with docker build --build-arg NEXT_PUBLIC_CDN_URL=https://myapp.b-cdn.net, or with build-args in docker/build-push-action.

Build and push to GitHub Container Registry

GitHub Actions
Docker CLI

Create .github/workflows/build.yml to automatically build and push on every commit to main:

.github/workflows/build.yml

name: Build and Push

on:
  push:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

      - name: Log in to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}

      - name: Update container image on Magic Containers
        uses: BunnyWay/actions/container-update-image@main
        with:
          app_id: ${{ vars.APP_ID }}
          api_key: ${{ secrets.BUNNYNET_API_KEY }}
          container: app
          image_tag: "${{ github.sha }}"

Push your code to trigger the workflow:

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/YOUR_USERNAME/app-nextjs.git
git push -u origin main

Build and push manually from your local machine.

Create a Personal Access Token

Go to GitHub Settings > Developer settings > Personal access tokens and create a token with write:packages scope.

export CR_PAT=your_personal_access_token
echo $CR_PAT | docker login ghcr.io -u YOUR_USERNAME --password-stdin

Build the image

docker build --platform linux/amd64 -t ghcr.io/YOUR_USERNAME/app-nextjs:latest .

Magic Containers only supports images built for the linux/amd64 architecture. The --platform flag ensures compatibility regardless of your local machine’s architecture.

Push to registry

docker push ghcr.io/YOUR_USERNAME/app-nextjs:latest

If your package is private, set the visibility to Public in GitHub or configure Magic Containers with registry credentials.

Deploy to Magic Containers

Create a new app

In the bunny.net dashboard, go to Magic Containers and click Add App. Enter a name and select your deployment option.

Add a container

Click Add Container, then configure:

Field	Value
Registry	GitHub Container Registry
Image	`YOUR_USERNAME/{imageName}`
Tag	`latest` for Docker CLI, or the commit SHA from your GitHub Actions workflow

Add an endpoint

Go to the Endpoints tab, click Add New Endpoint, and set the container port to 80.

Deploy

Click Add Container, then Next Step, and Confirm and Create.

For more details, see the quickstart guide.

Test your app

Visit your container URL in the browser to see your Next.js site, or test the API route:

curl https://mc-xxx.bunny.run/api

Response

{ "message": "Hello from Bunny 🐰" }

You can add a custom hostname from the Endpoints section in your app settings.

Add Optimizer

Your CDN endpoint is already a pull zone in front of the app. Turn on Bunny Optimizer there, and next/image resizes images at the edge.

Configure the endpoint's pull zone

Open the pull zone that serves your CDN endpoint under CDN → Pull Zones. Turn on URL Query String vary, since endpoint pull zones ignore query strings by default and ?width=1080 would come back as the cached ?width=640 image.Enable Optimizer, then turn on the Dynamic Image API and automatic WebP under Optimizer → Settings. Next.js already minifies CSS and JavaScript, so turn Optimizer’s minification off.

Add the image loader

The loader turns each next/image width into an Optimizer URL. With NEXT_PUBLIC_CDN_URL unset, it returns relative URLs that go through the same pull zone.

lib/bunny-loader.ts

"use client";

import type { ImageLoaderProps } from "next/image";

const cdn = process.env.NEXT_PUBLIC_CDN_URL;

export default function bunnyLoader({ src, width, quality }: ImageLoaderProps) {
  const url = new URL(src, cdn || "http://localhost");
  const params = url.searchParams;

  if (!params.has("width")) params.set("width", String(width));

  if (!params.has("quality")) params.set("quality", String(quality ?? 75));

  const absolute = cdn || /^https?:\/\//.test(src);
  return absolute ? url.href : url.pathname + url.search;
}

Point Next.js at the loader

next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "standalone",
  images: {
    loader: "custom",
    loaderFile: "./lib/bunny-loader.ts",
  },
};

export default nextConfig;

Rebuild and push the image. Smart Cache is on for endpoint pull zones, so the edge skips HTML and deploys need no purge.

To put a pull zone in front of Next.js on another host, see Serve Next.js from Bunny CDN.

Connect a database

You can connect your app to Bunny Database directly from the dashboard:

Go to Database > [Your Database] > Access
Click Generate Tokens
Click Add Secrets to Magic Container App
Select your app

The BUNNY_DATABASE_URL and BUNNY_DATABASE_AUTH_TOKEN environment variables are now available in your app:

app/api/users/route.ts

import { NextResponse } from "next/server";
import { createClient } from "@libsql/client/web";

const client = createClient({
  url: process.env.BUNNY_DATABASE_URL!,
  authToken: process.env.BUNNY_DATABASE_AUTH_TOKEN!,
});

export async function GET() {
  const result = await client.execute("SELECT * FROM users");

  return NextResponse.json(result.rows);
}

See the TypeScript SDK documentation for more details.

Documentation

Deployment

Managing Apps

Observability

Platform

Reference

Guides

Create the Next.js app

Configure standalone output

Create an API route

Run locally

Create the Dockerfile

Pass build-time variables

Build and push to GitHub Container Registry

Deploy to Magic Containers

Test your app

Add Optimizer

Connect a database

Next steps

​Create the Next.js app

​Configure standalone output

​Create an API route

​Run locally

​Create the Dockerfile

​Pass build-time variables

​Build and push to GitHub Container Registry

​Deploy to Magic Containers

​Test your app

​Add Optimizer

​Connect a database

​Next steps

Create the Next.js app

Configure standalone output

Create an API route

Run locally

Create the Dockerfile

Pass build-time variables

Build and push to GitHub Container Registry

Deploy to Magic Containers

Test your app

Add Optimizer

Connect a database

Next steps