Using Custom Domains and Multiple Localhost Ports for Applications

To use custom domains for multiple applications on localhost, you must map specific hostnames to the loopback address in your system’s local hosts file. This allows your browser to resolve names like app1.local or app2.local to 127.0.0.1, while a local reverse proxy routes traffic to the correct port based on the Host header. When developing locally, browsers often restrict accessing resources across different ports due to same-origin policies. Running multiple services on distinct ports (e.g., React on 3000, API on 8080) makes it difficult to test integration seamlessly. By assigning each service a unique subdomain under a fake TLD like .local or .test, you create distinct origins that behave like real production environments. This approach eliminates CORS issues during development and simplifies debugging by providing clear, memorable URLs instead of cryptic port numbers. The core mechanism relies on two components: local DNS resolution via the hosts file and an HTTP reverse proxy that inspects incoming requests.

Configuring Local DNS Resolution

The first step is ensuring your operating system resolves your chosen domain names to the local machine. You do not need a real DNS server for this; the local hosts file serves as a static DNS override. This file maps hostnames directly to IP addresses before any network query occurs. On Windows, the file is located at C:\Windows\System32\drivers\etc\hosts. On macOS and Linux, it resides at /etc/hosts. You will need administrator or root privileges to edit this file. Open the file with a text editor such as Notepad++, Visual Studio Code, or nano. Add entries for each application you wish to access. For example, if you have a frontend running on port 3000 and a backend on 8080, add the following lines:

127.0.0.1 app1.local
127.0.0.1 app2.local
127.0.0.1 api.app1.local

Each line maps the hostname to the IPv4 loopback address. You can also use IPv6 (::1) if your stack supports it, but IPv4 is universally compatible. After saving the file, your OS will immediately recognize these new mappings. If you encounter stale resolutions, you may need to restart your browser or flush the DNS cache depending on your OS, but modern systems typically handle this dynamically. Avoid using complex commands that might vary by distribution; simply editing the file is the standard, reliable method.

Setting Up a Reverse Proxy

While the hosts file directs traffic to your machine, it does not know which port to use. A reverse proxy solves this by listening on standard ports (80 and 443) and forwarding requests to the appropriate local ports based on the requested hostname. Nginx is a robust, widely used choice for this task. Install Nginx via your package manager (apt install nginx on Ubuntu, brew install nginx on macOS). Create a configuration file for your local domains. In Nginx, site configurations are typically stored in /etc/nginx/sites-available/ or /etc/nginx/conf.d/. Create a file named local-dev.conf with the following structure:

server {
    listen 80;
    server_name app1.local;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

server {
    listen 80;
    server_name api.app1.local;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

This configuration tells Nginx to listen for requests to app1.local and forward them to port 3000. Similarly, requests to api.app1.local go to port 8080. The proxy_set_header directives ensure that the backend applications receive the original hostname and client IP, which is crucial for logging and security headers. Enable the configuration by creating a symbolic link to the sites-enabled directory or including it in the main Nginx config. Restart Nginx to apply changes.

Handling TLS and Certificates

In production, HTTPS is mandatory, and browsers enforce strict security policies against mixed content. Testing with plain HTTP works for basic functionality, but many modern APIs and features require secure contexts. Generating valid SSL certificates for local domains is challenging because public Certificate Authorities do not issue certs for arbitrary local names. Instead, you can use mkcert, a tool designed specifically for local development. Install mkcert and create a local trust authority. Run mkcert -install to generate a CA certificate and add it to your system’s trusted store. Then, generate certificates for your domains: mkcert app1.local api.app1.local. This creates app1.local.pem and app1.local-key.pem. Update your Nginx configuration to listen on port 443 and include these certificate files. Ensure your hosts file still points to 127.0.0.1 so the DNS resolution remains local. This setup provides a fully functional HTTPS environment without triggering browser security warnings. For more details on handling TLS connections with unknown CAs, see our guide on establishing secure connections when certificates are not recognized by default stores. This is particularly relevant when testing mobile devices on the same network, as they may not trust the local mkcert CA unless explicitly installed.

Verifying Your Setup

Once configured, open your browser and navigate to http://app1.local. You should see the application served from port 3000. Navigate to http://api.app1.local to verify the backend is accessible. Check the browser console for any CORS errors; since both subdomains share the same base name and origin scheme, they are treated as same-origin by most browsers, eliminating cross-origin restrictions. If you experience connectivity issues, verify that Nginx is running and that no other service is blocking ports 80 or 443. Use curl -I http://app1.local to inspect response headers and confirm the proxy is working correctly.

Frequently Asked Questions

Why not just use 127.0.0.1:3000 and 127.0.0.1:8080?

Using direct port access prevents testing cross-domain scenarios and triggers browser security warnings for APIs called from different origins. Custom domains allow you to simulate production-like conditions where cookies, storage, and authentication tokens are scoped to specific domains.

Do I need to restart my computer after editing the hosts file?

No, restarting your computer is unnecessary. Modern operating systems reload the hosts file instantly upon save. However, you may need to restart your web browser or clear its DNS cache to see the changes immediately, especially if you previously visited those URLs.

Can I use this method on a mobile device connected to the same Wi-Fi?

Yes, but you must configure your router or use a tool like ngrok to expose your local Nginx instance. Additionally, the mobile device must trust the local CA certificate generated by mkcert. Without trusting the CA, the browser will block HTTPS connections due to invalid certificates.

What happens if I want to add another application later?

Simply add a new entry to your hosts file and a new server block in your Nginx configuration. There is no limit to the number of domains you can define, provided your machine has enough memory and CPU to handle the concurrent processes.

Is it safe to use .local as a TLD?

Using .local is generally safe for local development, but be aware that mDNS (Multicast DNS) uses the .local namespace. On some networks, this can cause conflicts if multicast DNS is enabled. Using .test or .dev is recommended as these are reserved for documentation and testing by IANA, ensuring no conflict with real internet domains.