Skip to content

1-setup-local.md

Latest commit

 

History

History
162 lines (112 loc) · 4.9 KB

1-setup-local.md

File metadata and controls

162 lines (112 loc) · 4.9 KB

README > NextJS Deploy > Setup Local

Environment Variables →

Setup Local

Prerequisites

On macOS:

brew install postgresql@17
curl -fsSL https://bun.sh/install | bash
brew install --cask orbstack # Docker Desktop alternative for macOS

On Linux (Ubuntu/Debian):

# Node.js via NodeSource
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs make postgresql-client

# Bun
curl -fsSL https://bun.sh/install | bash

# Docker
sudo apt install -y docker.io docker-compose-plugin
sudo usermod -aG docker $USER

make dev — Development

Best option for daily work. Next.js runs locally (fast hot-reload), Postgres in Docker.

make dev

First run: if env/env.config.mjs doesn't exist, the command creates it and stops. Configure your variables in the generated file, then re-run make dev. See Environment Variables for details.

Further runs: installs deps, generates .env files, starts Postgres, sets up DB, loads fixtures and starts Next.js.

Stop with Ctrl+C — shuts down both Next.js and Postgres.

make start — Production Test

Same as make dev but builds and serves the production bundle. Use to verify everything works before deploying.

make start

Stop with Ctrl+C — shuts down both Next.js and Postgres.

make docker — Docker Build

Builds the Next.js Docker image with database access (for generateStaticParams), then runs it. Postgres runs separately via compose.postgres.yml — the build accesses it through the host network.

make docker
make docker-stop    # Stop Next.js container + Postgres
make docker-clear   # Stop all + delete volumes

make postgres — Postgres Only

Keep Postgres running independently and restart Next.js freely without the overhead of make dev / make start (no reinstall, no DB reset, no fixtures reload). Ideal when you need to run bun run dev or bun run build frequently.

make postgres        # Start Postgres only (port 5433)

Then start Next.js in another terminal, with one of the following commands:

# Dev mode
bun run dev             # Start Next.js dev server
bun run auto            # Install deps, setup DB, load fixtures and start Next.js

# Build mode
bun run build && bun run start  # Test production build
bun run auto:start              # Install deps, setup DB, load fixtures and start production build

Ctrl+C only stops Next.js — Postgres keeps running. Stop it when done:

make postgres-stop   # Stop container
make postgres-clear  # Stop + delete volume

Ngrok Tunnel

Expose localhost:3000 through a public URL. Useful for mobile testing or sharing.

  1. Create an account at ngrok.com

  2. Setup your authtoken from the dashboard

  3. Get a free static domain at Domains

  4. Set your static domain in env/env.config.mjs in the tunnelling section. See Environment Variables for details.

    tunnelling: {
    NGROK_URL: commented("your-static-domain.ngrok-free.app"), // Change here
    NEXT_PUBLIC_BASE_URL: commented(template("https://{{NGROK_URL}}")), // Do not change this one
},

  5. Run make setup-env to regenerate env files

  6. In the generated .env at root, comment NEXT_PUBLIC_BASE_URL=http://localhost:3000 and uncomment the ngrok block:

    # Next.js configuration
NEXTJS_STANDALONE=false
# NEXT_PUBLIC_BASE_URL=http://localhost:3000 // Comment this line
...
# Ngrok tunnelling (optional)
NGROK_URL=your-static-domain.ngrok-free.app                    // Uncomment this line
NEXT_PUBLIC_BASE_URL=https://your-static-domain.ngrok-free.app // Uncomment this line

  7. Start in two terminals:

    # Terminal 1
make dev

# Terminal 2
make ngrok

Database Dump

Export the database schema to prisma/dump.sql. Requires an active Postgres container (make dev or make postgres).

make dump

Cleanup

Remove all generated files and folders:

make clear

Deletes: .husky/_, .next, node_modules, prisma/client, next-env.d.ts, tsconfig.tsbuildinfo, .env, env/.env.docker, env/.env.experiment, env/.env.preview, env/.env.production.

Environment Variables →

README > NextJS Deploy > Setup Local