Local Domain for Local Development: A Guide
Yes, setting a local domain for local development is a practical and common practice that makes web development easier and more realistic. Instead of typing localhost:3000 or 127.0.0.1:8080, you can use a domain like myproject.test or myproject.local to access your local site. This guide explains what a local domain is, why you might want one, and how to set it up on different operating systems.
What Is a Local Domain?
A local domain is a custom hostname that you map to your own computer’s loopback address (usually 127.0.0.1 or ::1). It is used only on your machine and is not registered in the public Domain Name System (DNS). This means that myproject.test will resolve to your local web server, but nobody else on the internet can access it using that name.
You create this mapping by editing the hosts file on your computer. This file is checked by your operating system before it queries a DNS server, so entries in it take precedence. When you type myproject.test in your browser, your computer looks at the hosts file, finds the mapping to 127.0.0.1, and sends the request to your local web server.
Why Use a Local Domain?
Using a local domain offers several benefits over using localhost or an IP address:
- Realistic URLs: It lets you use clean, production-like URLs (e.g.,
https://myproject.test) instead ofhttp://localhost:3000. - Cookie and Session Handling: Browsers treat cookies by domain, not by port. If you work on multiple projects on different ports, cookies can interfere. A unique domain per project prevents this.
- OAuth and External Services: Many APIs and authentication services (like Google or Facebook) require a registered redirect URI. You can register
http://myproject.test/callbackand it will work locally, whereashttp://localhost:3000/callbackmight be blocked or require special handling. - Subdomains: You can create subdomains like
api.myproject.testoradmin.myproject.testto mirror your production setup, making it easier to test multi-subdomain applications. - HTTPS Testing: Tools like
mkcertcan generate trusted certificates for local domains, allowing you to test HTTPS locally without browser warnings.
How to Set Up a Local Domain
Setting up a local domain involves two steps: editing the hosts file and configuring your web server to respond to that domain. Here is how to do it on common operating systems.
1. Edit the Hosts File
The hosts file is a plain text file. You need administrator privileges to edit it. The location varies by OS:
- Windows:
C:\Windows\System32\drivers\etc\hosts - macOS / Linux:
/etc/hosts
Add a line like this (using spaces or tabs):
127.0.0.1 myproject.test
If you want a subdomain, add another line:
127.0.0.1 api.myproject.test
Save the file. On Windows, you may need to run Notepad as Administrator. On macOS/Linux, use sudo with a text editor.
2. Configure Your Web Server
Your web server (Apache, Nginx, Caddy, or a development server like php -S) must be set up to serve your project when it receives a request for that domain. Here are examples:
- Apache: Create a VirtualHost with
ServerName myproject.testandDocumentRoot /path/to/project. - Nginx: Create a server block with
server_name myproject.test;androot /path/to/project;. - Built-in PHP server: Use
php -S myproject.test:80(but you must be root to bind to port 80 on Unix-like systems).
If you use a tool like Laravel Valet or Symfony CLI, they handle this automatically for you.
Choosing a Domain Extension
You can use any extension you like, but some are more common than others. The most popular are .test, .localhost, and .local. Here is why:
- .test: Reserved by the Internet Assigned Numbers Authority (IANA) for testing purposes. It is guaranteed not to be a real top-level domain, so there is no conflict.
- .localhost: Also reserved by IANA. It is often used for localhost itself, but can be used for subdomains like
myproject.localhost. - .local: Used by Avahi and Bonjour for local network services. It can conflict with mDNS if you are on a network that uses it. Avoid it if you want to be safe.
Avoid using .com, .net, or other real extensions, because your browser might try to resolve them via DNS, and you could accidentally hit a real site if you ever disconnect from the internet or the hosts entry is missing.
Common Problems and Fixes
You might encounter a few issues when setting up a local domain. Here are the most common ones and how to solve them:
- Browser redirects to HTTPS: Chrome and Firefox have a feature called HSTS (HTTP Strict Transport Security) that forces HTTPS for certain domains. If you previously visited
myproject.testover HTTPS, the browser might remember it. Clear the site data or use a fresh browser profile. - Hosts file not working: Make sure you have the correct IP address (use
127.0.0.1for IPv4 or::1for IPv6). Also, check that the file has no extra spaces or invalid characters. On Windows, runipconfig /flushdnsto clear the DNS cache. - Port conflicts: If your web server runs on port 80, make sure no other process is using it. On macOS, AirPlay Receiver uses port 5000, which can conflict with development servers. You can use a different port, but then your URL must include the port (e.g.,
http://myproject.test:3000). - Wildcard subdomains: If you want all subdomains to work, you can use a wildcard entry:
127.0.0.1 *.myproject.test. However, this is not supported on all systems; you may need to add each subdomain individually.
Alternatives to Editing the Hosts File
Editing the hosts file is simple, but it has limitations: you must do it manually for each project, and it affects the whole system. There are alternatives:
- Local DNS servers: Tools like
dnsmasqcan resolve all.testdomains to127.0.0.1without editing the hosts file. This is useful if you have many projects. - Development environment tools: Laravel Valet (macOS), Laragon (Windows), and Herd (macOS/Linux) automatically create local domains and configure your web server. They are great if you use PHP.
- Browser extensions: Some extensions can rewrite URLs in the browser, but they do not affect the actual DNS resolution, so they are less reliable.
- Docker: If you use Docker for development, you can map ports and use container names as hostnames, but that is a different setup.
Is It Safe?
Yes, using a local domain is safe as long as you follow a few rules:
- Do not use a real domain that you do not own. If you use
example.comlocally, you could accidentally access the real site if your hosts file is deleted. - Keep your hosts file clean to avoid confusion. Remove entries when you no longer need them.
- Be careful with wildcard entries if you are on a network that uses mDNS, as they could cause unexpected behavior.
- Use HTTPS locally with a tool like
mkcertto avoid mixed content warnings when your local site makes requests to external HTTPS resources.
There is no security risk in mapping a domain to 127.0.0.1; it only affects your own machine. The only risk is if you accidentally map a domain to a different IP address, which could redirect you to a malicious site.
Frequently Asked Questions
Can I use a local domain on a shared computer?
Yes, but the hosts file is global to the operating system. If you share a computer, your local domain will affect all users. You can use a different port or a different domain for each user, but that can get messy. A better approach is to use a virtual machine or a container that has its own hosts file.
Why does my browser still show localhost?
If you type myproject.test and the browser shows localhost, it might be because your web server is configured to redirect to localhost or because your project’s base URL is hardcoded. Check your project’s configuration files (like .env in Laravel) for the APP_URL setting.
Do I need to set up a local domain for every project?
No, it is optional. Many developers use localhost for simple projects. But if you work on multiple projects or need to test features that depend on the domain (like cookies or OAuth), a local domain is very helpful.
Can I use HTTPS with a local domain?
Yes, you can. The easiest way is to use mkcert, which creates a local Certificate Authority (CA) and issues certificates for your local domains. Install the CA once, generate a certificate for myproject.test, and configure your web server to use it. Browsers will trust the certificate, and you will not see security warnings.
What is the difference between .test and .local?
.test is reserved by IANA for testing and is guaranteed not to be used in the public DNS. .local is used by mDNS (Bonjour/Avahi) for local network services. If your network uses mDNS, .local names might be resolved by your system automatically, which can cause conflicts. It is safer to use .test.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.