Next.js Setup - Upstash Documentation

This guide walks you through scaffolding a Next.js app inside an Upstash Box and opening it in your browser through a public URL, without using an agent.

The box gives you a full Linux environment with Node.js already installed, so you can create the app, run the dev server, and share it, all through the SDK.

1. Create a Box

Create a box with the node runtime. You don't need to configure an agent for this. See the quickstart if you haven't created one before.

box.ts

import { Box } from "@upstash/box"const box = await Box.create({ runtime: "node" })

box.py

from upstash_box import Boxbox = Box.create(runtime="node")

2. Scaffold the App

Run create-next-app inside the box. The --yes flag accepts the default options so the setup runs without prompts, installing all dependencies.

box.ts

await box.exec.command("npx --yes create-next-app@latest my-next-app --yes")

box.py

box.exec.command("npx --yes create-next-app@latest my-next-app --yes")

3. Start the Dev Server

Start the development server in the background so the command returns while Next.js keeps running on port 3000. Commands run from the box's home directory (/workspace/home), where the app was created.

box.ts

await box.exec.command("cd my-next-app && nohup npm run dev > dev.log 2>&1 &")

box.py

box.exec.command("cd my-next-app && nohup npm run dev > dev.log 2>&1 &")

4. Create a Public URL

Expose port 3000 with a public URL to view the app in your browser. Creating a public URL for a running server returns its address.

box.ts

const publicUrl = await box.getPublicURL(3000)console.log(publicUrl.url)// → https://<box-id>-3000.preview.box.upstash.com

box.py

public_url = box.get_public_url(3000)print(public_url.url)# -> https://<box-id>-3000.preview.box.upstash.com

Open the URL in your browser and your Next.js app loads. See Public URLs for authentication and other options.

Next.js blocks cross-origin dev resources by default, so hot reloading won't work over the public URL until you add the host to allowedDevOrigins in next.config.ts:

next.config.ts

const nextConfig: NextConfig = {  allowedDevOrigins: ["<box-id>-3000.preview.box.upstash.com"],}