Implement Next.js + NGINX Runtime Configuration POC

[Copilot]

This PR implements the specification defined in specs/nextjs-nginx.md, creating a complete proof-of-concept for deploying Next.js applications with NGINX and runtime configuration injection.

Overview

The implementation demonstrates how to deploy a Next.js application where configuration can be changed at runtime without rebuilding the application. This is achieved through NGINX's sub_filter directive to inject configuration values into the HTML at serve time.

Key Features

• Latest Next.js (15.5.0) with App Router and static export
• Runtime Configuration Injection via NGINX without application rebuilds
• Type-safe Configuration utility with TypeScript
• Client-side Configuration Merging of build-time and runtime values
• Feature Toggles and environment-specific settings
• Multi-stage Docker Build for production deployment

Architecture

The system works by:

1. Build Time: Next.js app includes a placeholder script <script id="runtime-config">window.__RUNTIME_CONFIG__ = {};</script>
2. Runtime: NGINX uses sub_filter to replace the placeholder with actual configuration values from environment variables
3. Client Side: JavaScript merges default configuration with runtime overrides

Implementation Details

Configuration System

Created a centralized configuration utility (lib/config.ts) that:

• Reads environment variables during build for default values
• Merges runtime configuration from window.__RUNTIME_CONFIG__ on the client
• Provides type-safe access to configuration values
• Gracefully handles missing runtime configuration

Demo Application

Built a comprehensive demo application showcasing:

• Current configuration display
• Runtime vs build-time configuration indicators
• Feature toggles based on configuration
• Real-time configuration visualization

NGINX Integration

• Multi-stage Dockerfile with Node.js build and NGINX serve stages
• NGINX configuration template with environment variable substitution
• Docker entrypoint script for dynamic configuration injection
• Support for multiple configuration values (API_URL, FEATURE_X_ENABLED, APP_NAME)

Testing

Includes comprehensive testing:

• Automated test script validating the entire flow
• Browser testing demonstrating runtime configuration changes
• Verification that the same Docker image works across environments

Example test output:

✓ Runtime configuration successfully injected
✓ API_URL set to: https://api.production.com
✓ FEATURE_X_ENABLED set to: true
✓ APP_NAME set to: Production Demo App

Benefits

• Zero Downtime Configuration Changes: Update configuration without rebuilding or redeploying
• Environment Flexibility: Same Docker image works across development, staging, and production
• Performance: Static files served by NGINX with optimal caching
• Developer Experience: Type-safe configuration with clear fallbacks
• Operational Simplicity: Standard NGINX deployment with configuration injection

Files Added

• sites/demo-app/: Complete Next.js application with configuration demo
• Dockerfile: Multi-stage build for production deployment
• nginx.conf.template: NGINX configuration with runtime injection
• docker-compose.yml: Easy local testing setup
• test-runtime-config.sh: Automated testing script
• README.md: Comprehensive documentation and usage guide

This implementation successfully demonstrates that modern Next.js applications can be deployed with runtime configuration flexibility while maintaining optimal performance and developer experience.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• fonts.googleapis.com
  • Triggering command: /usr/local/bin/node /home/REDACTED/work/data-fetching-monorepo-poc/data-fetching-monorepo-poc/sites/demo-app/node_modules/.pnpm/next@15.5.0_react-dom@19.1.0_react@19.1.0__react@19.1.0/node_modules/next/dist/compiled/jest-worker/processChild.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.