Next.js

Map your domain

hatch add myapp.test 3000 --https

Allow the proxy origin

Next.js 14.2+ blocks requests from origins that don't match the dev server's hostname. Add your Hatch domain to the allowed list in next.config.ts:

// next.config.ts
const nextConfig = {
  allowedDevOrigins: ['myapp.test'],
};

export default nextConfig;

Without this, you'll see a Invalid Host/Origin header error in the console and HMR won't connect.

Environment variables

If your app references its own URL (for OAuth callbacks, API calls, or metadata), update your .env.local:

# .env.local
NEXT_PUBLIC_APP_URL=https://myapp.test
NEXTAUTH_URL=https://myapp.test

API routes

Next.js API routes (both pages/api and App Router route.ts handlers) work automatically through the proxy — they're served on the same port as your frontend, so no extra configuration is needed.

Server Actions

Server Actions use the same origin as the page, so they work through Hatch with no changes. If you're using serverActions.allowedOrigins in your Next.js config, add your Hatch domain:

// next.config.ts
const nextConfig = {
  allowedDevOrigins: ['myapp.test'],
  experimental: {
    serverActions: {
      allowedOrigins: ['myapp.test'],
    },
  },
};

export default nextConfig;

Project config

Add a .hatch.yaml to your project root so the mapping is saved with your repo:

# .hatch.yaml
domains:
  - domain: myapp.test
    port: 3000
    https: true

Common issues