feat(graphql-codegen): add localhost DNS resolution for *.localhost endpoints during introspection

This fixes DNS resolution issues on macOS where subdomains like api.localhost
don't resolve automatically to 127.0.0.1 (unlike browsers which handle *.localhost).

Uses undici Agent with custom DNS lookup to resolve *.localhost to 127.0.0.1
at codegen time only. The generated client code remains browser-compatible.

Author: pyramation

graphql/codegen/package.json

@@ -44,10 +44,10 @@
     "fmt:check": "prettier --check .",
     "test": "jest --passWithNoTests",
     "test:watch": "jest --watch",
-        "example:codegen:sdk": "tsx src/cli/index.ts generate --config examples/multi-target.config.ts --reactquery",
-        "example:codegen:orm": "tsx src/cli/index.ts generate --config examples/multi-target.config.ts --orm",
-        "example:codegen:sdk:schema": "node dist/cli/index.js generate --schema examples/example.schema.graphql --output examples/output/generated-sdk-schema --reactquery",
-        "example:codegen:orm:schema": "node dist/cli/index.js generate --schema examples/example.schema.graphql --output examples/output/generated-orm-schema --orm",
+    "example:codegen:sdk": "tsx src/cli/index.ts generate --config examples/multi-target.config.ts --reactquery",
+    "example:codegen:orm": "tsx src/cli/index.ts generate --config examples/multi-target.config.ts --orm",
+    "example:codegen:sdk:schema": "node dist/cli/index.js generate --schema examples/example.schema.graphql --output examples/output/generated-sdk-schema --reactquery",
+    "example:codegen:orm:schema": "node dist/cli/index.js generate --schema examples/example.schema.graphql --output examples/output/generated-orm-schema --orm",
     "example:sdk": "tsx examples/react-hooks-sdk-test.tsx",
     "example:orm": "tsx examples/orm-sdk-test.ts",
     "example:sdk:typecheck": "tsc --noEmit --jsx react --esModuleInterop --skipLibCheck --moduleResolution node examples/react-hooks-sdk-test.tsx"
@@ -72,7 +72,8 @@
     "pg-env": "workspace:^",
     "pgsql-client": "workspace:^",
     "pgsql-seed": "workspace:^",
-    "prettier": "^3.7.4"
+    "prettier": "^3.7.4",
+    "undici": "^7.19.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.0.0",

graphql/codegen/src/core/introspect/fetch-schema.ts

@@ -1,9 +1,46 @@
 /**
  * Fetch GraphQL schema introspection from an endpoint
  */
+import dns from 'node:dns';
+import { Agent } from 'undici';
 import { SCHEMA_INTROSPECTION_QUERY } from './schema-query';
 import type { IntrospectionQueryResponse } from '../../types/introspection';
 
+/**
+ * Check if a hostname is localhost or a localhost subdomain
+ */
+function isLocalhostHostname(hostname: string): boolean {
+  return hostname === 'localhost' || hostname.endsWith('.localhost');
+}
+
+/**
+ * Create an undici Agent that resolves *.localhost to 127.0.0.1
+ * This fixes DNS resolution issues on macOS where subdomains like api.localhost
+ * don't resolve automatically (unlike browsers which handle *.localhost).
+ */
+function createLocalhostAgent(): Agent {
+  return new Agent({
+    connect: {
+      lookup(hostname, opts, cb) {
+        if (isLocalhostHostname(hostname)) {
+          cb(null, '127.0.0.1', 4);
+          return;
+        }
+        dns.lookup(hostname, opts, cb);
+      },
+    },
+  });
+}
+
+let localhostAgent: Agent | null = null;
+
+function getLocalhostAgent(): Agent {
+  if (!localhostAgent) {
+    localhostAgent = createLocalhostAgent();
+  }
+  return localhostAgent;
+}
+
 export interface FetchSchemaOptions {
   /** GraphQL endpoint URL */
   endpoint: string;
@@ -30,13 +67,22 @@ export async function fetchSchema(
 ): Promise<FetchSchemaResult> {
   const { endpoint, authorization, headers = {}, timeout = 30000 } = options;
 
+  // Parse the endpoint URL to check for localhost
+  const url = new URL(endpoint);
+  const useLocalhostAgent = isLocalhostHostname(url.hostname);
+
   // Build headers
   const requestHeaders: Record<string, string> = {
     'Content-Type': 'application/json',
     Accept: 'application/json',
     ...headers,
   };
 
+  // Set Host header for localhost subdomains to preserve routing
+  if (useLocalhostAgent && url.hostname !== 'localhost') {
+    requestHeaders['Host'] = url.hostname;
+  }
+
   if (authorization) {
     requestHeaders['Authorization'] = authorization;
   }
@@ -45,16 +91,24 @@ export async function fetchSchema(
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), timeout);
 
+  // Build fetch options
+  const fetchOptions: RequestInit & { dispatcher?: Agent } = {
+    method: 'POST',
+    headers: requestHeaders,
+    body: JSON.stringify({
+      query: SCHEMA_INTROSPECTION_QUERY,
+      variables: {},
+    }),
+    signal: controller.signal,
+  };
+
+  // Use custom agent for localhost to fix DNS resolution on macOS
+  if (useLocalhostAgent) {
+    fetchOptions.dispatcher = getLocalhostAgent();
+  }
+
   try {
-    const response = await fetch(endpoint, {
-      method: 'POST',
-      headers: requestHeaders,
-      body: JSON.stringify({
-        query: SCHEMA_INTROSPECTION_QUERY,
-        variables: {},
-      }),
-      signal: controller.signal,
-    });
+    const response = await fetch(endpoint, fetchOptions);
 
     clearTimeout(timeoutId);