React and Next.js on Tor Hidden Service: 2026 Deployment Guide

Next.js supports three rendering modes relevant to .onion deployment. Static Generation (SSG): pages are pre-built at compile time. Benefits for .onion: extremely fast response times (serving pre-built HTML), no server-side computation on request, and resilience (pre-built files can be served from any web server). Best for: marketing pages, documentation, public content. App Router generateStaticParams enables static generation of dynamic routes. Server-Side Rendering (SSR): pages generated per-request. Benefits for .onion: personalized content, real-time data, authentication-gated pages. Requires a running Next.js server. Client-Side Rendering (CSR): initial HTML is empty, JavaScript populates the page. Problematic for Tor: JavaScript executes in Tor Browser where JavaScript may be restricted (Safest mode). Design pages to be functional without JavaScript where possible, or require users to use Standard security level for JavaScript-heavy features.

next.config.js settings for .onion: assetPrefix: '' (default, serves assets from the same .onion address - do not use absolute URLs or CDN asset prefixes), output: 'standalone' for self-contained deployment with a Node.js server, or output: 'export' for static HTML export (no server required, deploy to Nginx). For static export: next.config.js with output: 'export', then next build produces the out/ directory with static HTML. Serve out/ from Nginx using the static file configuration. Images: Next.js's Image Optimization requires a server (not compatible with static export). For static export, use standard tags or a lightweight image optimization build step. Absolute URLs: avoid hardcoding clearnet domains anywhere in the app. Use relative paths or the NEXT_PUBLIC_ environment variable for the .onion base URL.

Next.js App Router middleware for authentication: create middleware.ts at the project root to protect authenticated routes. The middleware intercepts requests before they reach page components. For .onion auth: use JWT stored in HTTPOnly cookies (set via next/headers in server actions or API routes). The cookie is automatically sent with every request. Middleware checks the cookie validity and redirects to login if invalid. CSRF protection: Next.js 14+ has built-in CSRF protection for server actions. For custom API routes, implement CSRF tokens. Session management: use iron-session or next-auth for server-side session management. next-auth supports multiple providers - for .onion services, use credentials provider (username/password) rather than OAuth providers (OAuth requires clearnet callback URLs). HTTP vs HTTPS cookie settings: if using HTTP .onion, set cookies with httpOnly: true but NOT secure: true (secure flag only sends cookies over HTTPS, which breaks HTTP .onion).

Next.js API routes (app/api/route.ts) run on the server and can access databases, external services, and secrets. For .onion deployment: API routes run on the Next.js server (not the client), so they can access your PostgreSQL database, Redis, and other backend services directly. Server Actions (Next.js 14+) allow calling server-side code directly from client components without explicit API route definition. For .onion: server actions work identically to clearnet deployments. The client submits the action over the Tor circuit; the server processes it on the backend. Rate limiting for API routes: use a Redis-backed rate limiter (API route checks Redis before processing). Per-user rate limiting via session ID. Respond with 429 and Retry-After header on limit exceeded.

Option 1: Node.js standalone server. next build with output: 'standalone' creates a .next/standalone directory with a minimal Node.js server. Run with node .next/standalone/server.js. Nginx proxies the .onion port to the Next.js server port. Option 2: Static export + Nginx. next build with output: 'export'. Serve the out/ directory from Nginx directly (no Node.js required, fastest possible response times). Limited to SSG and CSR (no SSR or API routes). Option 3: Docker container. Build a Docker image with Next.js standalone, expose to Nginx, and manage with Docker Compose. The Tor process in another container connects to Nginx. Option 4: PM2 process manager. Run the Next.js server via PM2 for automatic restart, logging, and process management. pm2 start server.js --name nextjs. All options connect to a Tor process via HiddenServicePort pointing to the local Next.js port (or Nginx port).