Set up production-like local domains with Next.js and Payload CMS to test tenant routing, previews, and SEO locally.
In-depth Next.js guides covering App Router, RSC, ISR, and deployment. Get code examples, optimization checklists, and prompts to accelerate development.
No spam. Unsubscribe anytime.
Context: This guide is part of the Multi-Tenant Setup series.
This guide explains how to set up a local development environment that mimics production for multi-tenant applications using Payload CMS and Next.js.
When building multi-tenant applications, you need to test how different tenants (domains) behave in production. Instead of using subdirectories or query parameters, this setup allows you to:
tenant-a.local, tenant-b.local)/etc/hosts → add local domainshttp://tenant-a.local in browserFirst, map your production domains to local development domains using your system's hosts file.
sudo nano /etc/hosts
Add these entries to map local domains to localhost:
# Multi-tenant development domains
127.0.0.1 tenant-a.local
127.0.0.1 tenant-b.local
tenant-a.local and tenant-b.local to 127.0.0.1 (localhost)The middleware handles tenant routing based on the hostname. Here's a simplified version for development:
// Simplified middleware - for full production implementation, see:
// [Production-Ready Multi-Tenant Setup - Middleware Section](/blog/production-ready-multi-tenant-nextjs-payload#middleware-implementation)
const tenantMap = {
'tenant-a.local': 'tenant-a', // Maps local domain to tenant slug
'tenant-b.local': 'tenant-b',
};
// ... logic to rewrite request to /[tenant]/...
For the complete production-ready middleware with authentication, preview mode, and diverse domain handling, see the full implementation guide.
tenantMap object.local and production domainsCreate a utility to map production domains to development domains when running locally.
/**
* Map production domains to development domains for local testing
*/
export const getDevelopmentDomain = (domain: string): string => {
const devDomainMap: Record<string, string> = {
'tenant-a.vercel.app': 'tenant-a.local',
'tenant-b.vercel.app': 'tenant-b.local',
};
return devDomainMap[domain] || domain;
};
This utility is used in places where URLs need to be generated for the current environment. The getDevelopmentDomain() utility maps production domains to local test domains. See Development Environment Guide for implementation.
Example usage in SEO utilities:
// Example usage in SEO utilities
const isDevelopment = process.env.NODE_ENV === 'development';
const finalDomain = isDevelopment ? getDevelopmentDomain(tenant.domain) : tenant.domain;
const protocol = isDevelopment ? 'http' : 'https';
const baseUrl = `${protocol}://${finalDomain}`;
When starting your development server, make sure it's configured to handle the custom domains.
# Using pnpm (as per project conventions)
pnpm dev
The server typically starts on port 3000, but you can configure it in your package.json:
{
"scripts": {
"dev": "next dev -p 80"
}
}
http://tenant-a.local instead of http://tenant-a.local:3000Open these URLs in your browser:
http://tenant-a.local - Should show the Tenant Ahttp://tenant-b.local - Should show the Tenant Bhttp://localhost:3000 - Should work (fallback behavior)Look at the network requests in your browser dev tools:
http://tenant-a.local/http://localhost:3000/tenant-slugs/tenant-a/homeTest features that depend on tenant identification:
Issue: Browser shows "Server not found" or DNS error
Solution:
/etc/hosts entries are correct# On macOS
sudo dscacheutil -flushcache
# On Linux
sudo systemd-resolve --flush-caches
http://127.0.0.1 to ensure the server is runningIssue: Tenant routing not working, showing default content
Solution:
console.log('Middleware called with hostname:', hostname);
Issue: HTTPS resources on HTTP development domains
Solution:
getDevelopmentDomain utility for all URL generationIssue: Port 80 requires sudo or is already in use
Solution:
127.0.0.1 tenant-a.local:3000
127.0.0.1 tenant-b.local:3000
When deploying to production:
For comprehensive production setup including hardcoded tenant configuration, edge middleware optimization, and Payload CMS multi-tenant plugin configuration, see Production-Ready Multi-Tenant Setup.
Instead of domain-based routing, you could use subdirectories:
http://localhost:3000/tenant-a/...http://localhost:3000/tenant-b/...Pros: No hosts file modification needed Cons: Doesn't mimic production URL structure
Use query parameters to specify tenants:
http://localhost:3000/?tenant=tenant-ahttp://localhost:3000/?tenant=tenant-bPros: Simplest setup Cons: Very different from production, SEO issues
This development environment setup provides a production-like experience for multi-tenant applications without complex infrastructure. By using local domain mapping and intelligent middleware, you can:
The key insight is that by mapping local domains to localhost and using middleware to handle routing, you create a development environment that behaves identically to production while keeping the setup simple and maintainable.