How to Host Next.js in a Subdirectory with Nginx

Configuring a Reverse Proxy for Next.js applications is standard practice, but hosting that application in a subdirectory (e.g., example.com/dashboard instead of a subdomain) introduces complex routing challenges. A single missing trailing slash or incorrect proxy_pass header can break your static assets (CSS, JS) or cause infinite redirects.

This Nginx Config Generator builds a production-ready location block tailored for Next.js 13/14+ App Router and Pages Router deployments. It handles the critical WebSocket upgrades (for HMR) and correct header forwarding.

Why use a Subdirectory instead of a Subdomain?

From an SEO perspective, subdirectories are often superior to subdomains. Here is why developers choose this architecture:

• Domain Authority Consolidation: Backlinks pointing to example.com/blog strengthen the root domain (example.com). Subdomains (blog.example.com) are often treated by Google as separate entities.
• Unified Cookie Management: Sharing authentication cookies between your main app and your Next.js micro-frontend is significantly easier on the same domain.
• Clean Architecture: Perfect for monorepos where you want to serve different frameworks (e.g., WordPress on Root, Next.js on /app) under one umbrella.

Common Nginx & Next.js Errors (Troubleshooting)

If you are manually writing your config, you likely encountered one of these errors. Our tool fixes them automatically.

1. The “Whitelabel” 404 Error

Symptom: You load the page, the HTML loads, but there is no styling, and the console is full of 404s for _next/static files.

Cause: Nginx is looking for the static assets in the root directory instead of the subdirectory. Our generator adds the specific alias or correct `proxy_pass` logic to resolve asset paths.

2. WebSocket Connection Failed

Symptom: In development mode, you see constant “WebSocket connection failed” errors in the browser console, and Hot Module Replacement (HMR) stops working.

Fix: This requires the Upgrade and Connection headers to be explicitly passed. This tool includes these headers by default.

Advanced Use Cases for Next.js in Subdirectories

While the standard setup is great for a blog or a simple dashboard, many enterprise architectures require more robust implementations. Here is how this generator fits into advanced routing strategies.

1. The “Micro-Frontend” Monorepo Strategy

Large organizations often split their massive web platform into smaller, manageable “Micro-Frontends”. Using Nginx as a Reverse Proxy Gateway allows you to stitch these together seamlessly.

Imagine a structure like this:

• example.com/ -> Served by a Marketing Site (WordPress or Astro)
• example.com/shop/ -> Served by a Shopify Headless instance
• example.com/app/ -> Served by your Next.js Application

This generator essentially builds the “Glue Code” for that /app/ route. By repeating this process for different ports, you can host 5+ different frameworks on a single domain, all sharing the same SSL certificate and top-level domain cookies.

2. Implementing with Docker & Kubernetes

If you are containerizing your Next.js application, this location block is still vital. In a Kubernetes Ingress setup (like Nginx Ingress Controller), the syntax is slightly different (using annotations), but if you are running a Sidecar Nginx Container or a rigid Nginx Pod in front of your Node.js pods, this config is 100% compatible.

Ensure your Dockerfile exposes the correct port (default 3000) and that your Nginx container can talk to the Next.js container via the internal Docker network hostname (e.g., proxy_pass http://nextjs_container:3000; instead of localhost).

Performance & SEO Considerations

When you host Next.js in a subdirectory, you must be vigilant about “Asset Bloat” and “Canonical Confusion”.

Avoiding the “Double Download” Penalty

A common misconfiguration causes the browser to download your CSS twice—once from the root path and once from the subdirectory. This hurts your Core Web Vitals (specifically LCP). Our generated config uses the alias method (when “Strip Subdirectory” is enabled) or precise proxy passing to ensure assets are served strictly once, caching them efficiently.

Linking to Other Infrastructure Tools

If you are building a full-stack infrastructure, you might need configurations for more than just Next.js subdirectories. If you are looking for a standard, root-level server block configuration for PHP, Python, or standard static sites, check out our general Nginx Config Generator. It covers the broader spectrum of server setup, including Gzip compression and security headers.

Frequently Asked Questions