nitro-graphql 2.0.0-beta.7 → 2.0.0-beta.72

package/dist/nitro/setup/extend-loader.mjs

@@ -0,0 +1,80 @@
+import { LOG_TAG } from "../../core/constants.mjs";
+import { generateDirectiveSchemas } from "../../core/utils/directive-parser.mjs";
+import { resolveExtendDirs as resolveExtendDirs$1, scanAllExtendSources } from "../../core/extend/loader.mjs";
+import consola from "consola";
+//#region src/nitro/setup/extend-loader.ts
+const logger = consola.withTag(LOG_TAG);
+/**
+* Resolve extend directories for file watching
+*/
+async function resolveExtendDirs(nitro) {
+	const extend = nitro.options.graphql?.extend;
+	return resolveExtendDirs$1(extend, nitro.options.rootDir);
+}
+/**
+* Resolve extend configuration and add files to Nitro scan results
+*/
+async function resolveExtendConfig(nitro, options = {}) {
+	const extend = nitro.options.graphql?.extend;
+	if (!extend || !Array.isArray(extend) || extend.length === 0) return;
+	const stats = applyExtendResult(nitro, await scanAllExtendSources(extend, nitro.options.rootDir));
+	if (stats.directives > 0) {
+		const directiveSchemas = await generateDirectiveSchemas(nitro.scanDirectives, nitro.graphql.buildDir);
+		nitro.graphql.directiveSchemas = directiveSchemas;
+	}
+	if (!options.silent && (stats.schemas > 0 || stats.resolvers > 0 || stats.directives > 0 || stats.documents > 0)) {
+		const parts = [];
+		if (stats.schemas > 0) parts.push(`${stats.schemas} schema(s)`);
+		if (stats.resolvers > 0) parts.push(`${stats.resolvers} resolver(s)`);
+		if (stats.directives > 0) parts.push(`${stats.directives} directive(s)`);
+		if (stats.documents > 0) parts.push(`${stats.documents} document(s)`);
+		if (stats.configs > 0) parts.push(`${stats.configs} config(s)`);
+		if (stats.programmaticSchemas > 0) parts.push(`${stats.programmaticSchemas} programmatic schema(s)`);
+		logger.info(`Extended with ${parts.join(", ")}`);
+	}
+}
+/**
+* Apply extend scan result to Nitro state
+*/
+function applyExtendResult(nitro, result) {
+	let schemasAdded = 0;
+	let resolversAdded = 0;
+	let directivesAdded = 0;
+	let documentsAdded = 0;
+	let configsAdded = 0;
+	let programmaticSchemasAdded = 0;
+	for (const schemaPath of result.schemas) if (!nitro.scanSchemas.includes(schemaPath)) {
+		nitro.scanSchemas.push(schemaPath);
+		schemasAdded++;
+	}
+	for (const resolver of result.resolvers) if (!nitro.scanResolvers.some((r) => r.specifier === resolver.specifier)) {
+		nitro.scanResolvers.push(resolver);
+		resolversAdded++;
+	}
+	for (const directive of result.directives) if (!nitro.scanDirectives.some((d) => d.specifier === directive.specifier)) {
+		nitro.scanDirectives.push(directive);
+		directivesAdded++;
+	}
+	for (const docPath of result.documents) if (!nitro.scanDocuments.includes(docPath)) {
+		nitro.scanDocuments.push(docPath);
+		documentsAdded++;
+	}
+	if (result.configPath && !nitro.graphql.extendConfigs.includes(result.configPath)) {
+		nitro.graphql.extendConfigs.push(result.configPath);
+		configsAdded++;
+	}
+	if (result.schemaPath && !nitro.graphql.extendSchemas.includes(result.schemaPath)) {
+		nitro.graphql.extendSchemas.push(result.schemaPath);
+		programmaticSchemasAdded++;
+	}
+	return {
+		schemas: schemasAdded,
+		resolvers: resolversAdded,
+		directives: directivesAdded,
+		documents: documentsAdded,
+		configs: configsAdded,
+		programmaticSchemas: programmaticSchemasAdded
+	};
+}
+//#endregion
+export { resolveExtendConfig, resolveExtendDirs };

package/dist/nitro/setup/file-watcher.d.mts

@@ -0,0 +1,18 @@
+import { FSWatcher } from "chokidar";
+import { Nitro } from "nitro/types";
+
+//#region src/nitro/setup/file-watcher.d.ts
+/**
+ * Setup file watcher for GraphQL files (schemas, resolvers, directives, documents)
+ * Watches for changes and triggers type regeneration and dev server reload
+ *
+ * Uses core watcher module with Nitro-specific callbacks.
+ */
+declare function setupFileWatcher(nitro: Nitro, watchDirs: string[]): FSWatcher;
+/**
+ * Determine which directories to watch based on framework and configuration
+ * Note: Layer directories are now handled via extendDirs (passed from extend-loader)
+ */
+declare function getWatchDirectories(nitro: Nitro, extendDirs?: string[]): string[];
+//#endregion
+export { getWatchDirectories, setupFileWatcher };

package/dist/nitro/setup/file-watcher.mjs

@@ -0,0 +1,62 @@
+import { LOG_TAG } from "../../core/constants.mjs";
+import { generateClientTypes, generateServerTypes } from "../codegen.mjs";
+import { createCoreWatcher } from "../../core/watcher/index.mjs";
+import { performGraphQLScan, shouldScanLocalFiles } from "./scanner.mjs";
+import consola from "consola";
+import { join } from "pathe";
+//#region src/nitro/setup/file-watcher.ts
+const TRAILING_SLASH_RE = /\/$/;
+const logger = consola.withTag(LOG_TAG);
+/**
+* Setup file watcher for GraphQL files (schemas, resolvers, directives, documents)
+* Watches for changes and triggers type regeneration and dev server reload
+*
+* Uses core watcher module with Nitro-specific callbacks.
+*/
+function setupFileWatcher(nitro, watchDirs) {
+	return createCoreWatcher({
+		watchDirs,
+		serverDir: nitro.graphql.serverDir,
+		debounceMs: 150
+	}, {
+		onServerChange: async () => {
+			await performGraphQLScan(nitro, {
+				silent: true,
+				isRescan: true
+			});
+			await generateServerTypes(nitro, { silent: true });
+			await generateClientTypes(nitro, { silent: true });
+			logger.success("Types regenerated");
+			await nitro.hooks.callHook("dev:reload");
+		},
+		onClientChange: async () => {
+			await generateClientTypes(nitro, { silent: true });
+			logger.success("Client types regenerated");
+		},
+		onError: (error) => {
+			logger.error("Watcher error:", error);
+		}
+	});
+}
+/**
+* Determine which directories to watch based on framework and configuration
+* Note: Layer directories are now handled via extendDirs (passed from extend-loader)
+*/
+function getWatchDirectories(nitro, extendDirs = []) {
+	const watchDirs = [];
+	const scanLocal = shouldScanLocalFiles(nitro);
+	watchDirs.push(nitro.graphql.clientDir);
+	if (scanLocal) watchDirs.push(nitro.graphql.serverDir);
+	for (const dir of extendDirs) if (!watchDirs.includes(dir)) watchDirs.push(dir);
+	if (nitro.options.graphql?.externalServices?.length) {
+		for (const service of nitro.options.graphql.externalServices) if (service.documents?.length) for (const pattern of service.documents) {
+			if (!pattern) continue;
+			const baseDir = pattern.split("**")[0]?.replace(TRAILING_SLASH_RE, "") || ".";
+			const resolvedDir = join(nitro.options.rootDir, baseDir);
+			if (!watchDirs.includes(resolvedDir)) watchDirs.push(resolvedDir);
+		}
+	}
+	return watchDirs;
+}
+//#endregion
+export { getWatchDirectories, setupFileWatcher };

package/dist/nitro/setup/logging.d.mts

@@ -0,0 +1,16 @@
+import { SecurityConfig } from "../types.mjs";
+import { Nitro } from "nitro/types";
+
+//#region src/nitro/setup/logging.d.ts
+/**
+ * Resolves security configuration with environment-aware defaults
+ * In production: introspection off, playground off, errors masked, suggestions disabled
+ * In development: introspection on, playground on, errors shown, suggestions enabled
+ */
+declare function resolveSecurityConfig(config?: SecurityConfig): Required<SecurityConfig>;
+/**
+ * Log startup information
+ */
+declare function logStartupInfo(nitro: Nitro, serverEnabled: boolean): void;
+//#endregion
+export { logStartupInfo, resolveSecurityConfig };

package/dist/nitro/setup/logging.mjs

@@ -0,0 +1,64 @@
+import consola from "consola";
+//#region src/nitro/setup/logging.ts
+/**
+* Resolves security configuration with environment-aware defaults
+* In production: introspection off, playground off, errors masked, suggestions disabled
+* In development: introspection on, playground on, errors shown, suggestions enabled
+*/
+function resolveSecurityConfig(config) {
+	const isProd = process.env.NODE_ENV === "production";
+	return {
+		introspection: config?.introspection ?? !isProd,
+		playground: config?.playground ?? !isProd,
+		maskErrors: config?.maskErrors ?? isProd,
+		disableSuggestions: config?.disableSuggestions ?? isProd
+	};
+}
+/**
+* Log startup information
+*/
+function logStartupInfo(nitro, serverEnabled) {
+	const externalServicesCount = nitro.options.graphql?.externalServices?.length || 0;
+	const docs = nitro.scanDocuments || [];
+	const isProd = process.env.NODE_ENV === "production";
+	if (serverEnabled) {
+		const securityConfig = resolveSecurityConfig(nitro.options.graphql?.security);
+		const framework = nitro.options.graphql?.framework || "unknown";
+		const schemas = nitro.scanSchemas?.length || 0;
+		const resolvers = nitro.scanResolvers?.length || 0;
+		consola.box({
+			title: "Nitro GraphQL",
+			message: [
+				`Framework: ${framework}`,
+				`Environment: ${isProd ? "production" : "development"}`,
+				`Schemas: ${schemas}`,
+				`Resolvers: ${resolvers}`,
+				externalServicesCount > 0 ? `External Services: ${externalServicesCount}` : "",
+				docs.length > 0 ? `Documents: ${docs.length}` : "",
+				"",
+				"Security:",
+				`├─ Introspection: ${securityConfig.introspection ? "enabled" : "disabled"}`,
+				`├─ Playground: ${securityConfig.playground ? "enabled" : "disabled"}`,
+				`├─ Error Masking: ${securityConfig.maskErrors ? "enabled" : "disabled"}`,
+				`└─ Field Suggestions: ${securityConfig.disableSuggestions ? "disabled" : "enabled"}`
+			].filter(Boolean).join("\n"),
+			style: {
+				borderColor: isProd ? "yellow" : "cyan",
+				borderStyle: "rounded"
+			}
+		});
+	} else consola.box({
+		title: "Nitro GraphQL (Client Only)",
+		message: [
+			"Server mode: disabled",
+			`External Services: ${externalServicesCount}`,
+			`Documents: ${docs.length}`
+		].join("\n"),
+		style: {
+			borderColor: "blue",
+			borderStyle: "rounded"
+		}
+	});
+}
+//#endregion
+export { logStartupInfo, resolveSecurityConfig };

package/dist/nitro/setup/rollup-integration.d.mts

@@ -0,0 +1,24 @@
+import { Nitro } from "nitro/types";
+
+//#region src/nitro/setup/rollup-integration.d.ts
+/**
+ * Configure noExternals to ensure nitro-graphql route handlers are bundled
+ * This is critical for Nuxt integration where node_modules are externalized by default.
+ * Without this, the #nitro-graphql/* virtual imports in handlers would fail at runtime.
+ */
+declare function setupNoExternals(nitro: Nitro): void;
+/**
+ * Setup Rollup/Rolldown chunking configuration for GraphQL files
+ * Creates separate chunks for schemas and resolvers to optimize bundle size
+ *
+ * Note: For Rolldown, we only use manualChunks (not advancedChunks) to avoid
+ * interfering with Nitro's node_modules chunking which uses advancedChunks.
+ */
+declare function setupRollupChunking(nitro: Nitro): void;
+/**
+ * Configure external dependencies for Rollup
+ * Marks codegen and federation packages as external
+ */
+declare function setupRollupExternals(nitro: Nitro): void;
+//#endregion
+export { setupNoExternals, setupRollupChunking, setupRollupExternals };

package/dist/nitro/setup/rollup-integration.mjs

@@ -0,0 +1,64 @@
+//#region src/nitro/setup/rollup-integration.ts
+const NITRO_GRAPHQL_ROUTES_RE = /nitro-graphql[/\\]dist[/\\]nitro[/\\]routes/;
+const NITRO_GRAPHQL_SCHEMA_RE = /nitro-graphql[/\\]dist[/\\]core[/\\]schema/;
+/**
+* Configure noExternals to ensure nitro-graphql route handlers are bundled
+* This is critical for Nuxt integration where node_modules are externalized by default.
+* Without this, the #nitro-graphql/* virtual imports in handlers would fail at runtime.
+*/
+function setupNoExternals(nitro) {
+	const routePatterns = [NITRO_GRAPHQL_ROUTES_RE, NITRO_GRAPHQL_SCHEMA_RE];
+	if (nitro.options.noExternals === true) return;
+	if (!Array.isArray(nitro.options.noExternals)) nitro.options.noExternals = [];
+	nitro.options.noExternals.push(...routePatterns);
+}
+/**
+* Setup Rollup/Rolldown chunking configuration for GraphQL files
+* Creates separate chunks for schemas and resolvers to optimize bundle size
+*
+* Note: For Rolldown, we only use manualChunks (not advancedChunks) to avoid
+* interfering with Nitro's node_modules chunking which uses advancedChunks.
+*/
+function setupRollupChunking(nitro) {
+	nitro.hooks.hook("rollup:before", (_, rollupConfig) => {});
+}
+/**
+* Configure external dependencies for Rollup
+* Marks codegen and federation packages as external
+*/
+function setupRollupExternals(nitro) {
+	nitro.hooks.hook("rollup:before", (_, rollupConfig) => {
+		rollupConfig.external = rollupConfig.external || [];
+		const allExternals = [...[
+			"oxc-parser",
+			"@oxc-parser",
+			"nitro-graphql/native",
+			"nitro-graphql-darwin-arm64",
+			"nitro-graphql-darwin-x64",
+			"nitro-graphql-darwin-universal",
+			"nitro-graphql-linux-x64-gnu",
+			"nitro-graphql-linux-x64-musl",
+			"nitro-graphql-linux-arm64-gnu",
+			"nitro-graphql-linux-arm64-musl",
+			"nitro-graphql-win32-x64-msvc",
+			"nitro-graphql-win32-x64-gnu",
+			"nitro-graphql-win32-arm64-msvc",
+			"nitro-graphql-win32-ia32-msvc"
+		]];
+		if (!nitro.options.graphql?.federation?.enabled) allExternals.push(...[
+			"@apollo/subgraph",
+			"@apollo/federation-internals",
+			"@apollo/cache-control-types"
+		]);
+		if (Array.isArray(rollupConfig.external)) rollupConfig.external.push(...allExternals);
+		else if (typeof rollupConfig.external === "function") {
+			const originalExternal = rollupConfig.external;
+			rollupConfig.external = (id, parent, isResolved) => {
+				if (allExternals.some((external) => id.includes(external))) return true;
+				return originalExternal(id, parent, isResolved);
+			};
+		}
+	});
+}
+//#endregion
+export { setupNoExternals, setupRollupChunking, setupRollupExternals };

package/dist/nitro/setup/routes.d.mts

@@ -0,0 +1,13 @@
+import { Nitro } from "nitro/types";
+
+//#region src/nitro/setup/routes.d.ts
+/**
+ * Register GraphQL route handlers
+ *
+ * Uses import.meta.resolve() to convert module specifiers to absolute paths.
+ * This ensures handlers are resolved correctly both in local development
+ * (monorepo symlink) and in CI/production (installed from npm).
+ */
+declare function registerRouteHandlers(nitro: Nitro): void;
+//#endregion
+export { registerRouteHandlers };

package/dist/nitro/setup/routes.mjs

@@ -0,0 +1,69 @@
+import { ENDPOINT_DEBUG, GRAPHQL_HTTP_METHODS } from "../../core/constants.mjs";
+import { fileURLToPath } from "node:url";
+//#region src/nitro/setup/routes.ts
+/**
+* Resolve a module specifier to an absolute filesystem path.
+* Uses import.meta.resolve() to handle both:
+* - Local development (monorepo symlinks resolve to local source)
+* - CI/Production (npm install resolves to node_modules)
+*/
+function resolveHandler(specifier) {
+	return fileURLToPath(import.meta.resolve(specifier));
+}
+/**
+* Register GraphQL route handlers
+*
+* Uses import.meta.resolve() to convert module specifiers to absolute paths.
+* This ensures handlers are resolved correctly both in local development
+* (monorepo symlink) and in CI/production (installed from npm).
+*/
+function registerRouteHandlers(nitro) {
+	const framework = nitro.options.graphql?.framework;
+	const subscriptions = nitro.options.graphql?.subscriptions;
+	const endpoint = nitro.options.runtimeConfig.graphql?.endpoint?.graphql || "/api/graphql";
+	if (framework === "graphql-yoga") {
+		for (const method of GRAPHQL_HTTP_METHODS) nitro.options.handlers.push({
+			route: endpoint,
+			handler: resolveHandler("nitro-graphql/nitro/routes/graphql-yoga"),
+			method
+		});
+		nitro.options.handlers.push({
+			route: `${endpoint}/sandbox.js`,
+			handler: resolveHandler("nitro-graphql/nitro/routes/apollo-sandbox-script"),
+			method: "GET"
+		});
+		if (subscriptions?.enabled && subscriptions.websocket?.enabled !== false) {
+			const wsPath = subscriptions.websocket?.path || `${endpoint}/ws`;
+			nitro.options.handlers.push({
+				route: wsPath,
+				handler: resolveHandler("nitro-graphql/nitro/routes/graphql-yoga-ws")
+			});
+		}
+	}
+	if (framework === "apollo-server") {
+		for (const method of GRAPHQL_HTTP_METHODS) nitro.options.handlers.push({
+			route: endpoint,
+			handler: resolveHandler("nitro-graphql/nitro/routes/apollo-server"),
+			method
+		});
+		if (subscriptions?.enabled && subscriptions.websocket?.enabled !== false) {
+			const wsPath = subscriptions.websocket?.path || `${endpoint}/ws`;
+			nitro.options.handlers.push({
+				route: wsPath,
+				handler: resolveHandler("nitro-graphql/nitro/routes/apollo-server-ws")
+			});
+		}
+	}
+	nitro.options.handlers.push({
+		route: nitro.options.runtimeConfig.graphql?.endpoint?.healthCheck || "/api/graphql/health",
+		handler: resolveHandler("nitro-graphql/nitro/routes/health"),
+		method: "GET"
+	});
+	if (nitro.options.dev) nitro.options.handlers.push({
+		route: ENDPOINT_DEBUG,
+		handler: resolveHandler("nitro-graphql/nitro/routes/debug"),
+		method: "GET"
+	});
+}
+//#endregion
+export { registerRouteHandlers };

package/dist/nitro/setup/scanner.d.mts

@@ -0,0 +1,59 @@
+import { ExtendSource } from "../types.mjs";
+import { Nitro } from "nitro/types";
+
+//#region src/nitro/setup/scanner.d.ts
+interface ScanOptions {
+  /** Silent mode - suppress logging */
+  silent?: boolean;
+  /** Is this a rescan (dev mode hot reload) */
+  isRescan?: boolean;
+}
+interface ScanResult {
+  schemas: number;
+  resolvers: number;
+  directives: number;
+  documents: number;
+}
+/**
+ * Check if local file scanning should be performed
+ * Centralized helper to avoid scattered skipLocalScan checks
+ */
+declare function shouldScanLocalFiles(nitro: Nitro): boolean;
+/**
+ * Check if server-side GraphQL is enabled
+ */
+declare function isServerEnabled(nitro: Nitro): boolean;
+/**
+ * Get extend sources from config
+ */
+declare function getExtendSources(nitro: Nitro): ExtendSource[] | undefined;
+/**
+ * Scan local GraphQL files (schemas, resolvers, directives, documents)
+ * This is the low-level scan function - use performGraphQLScan for full workflow
+ */
+declare function scanLocalFiles(nitro: Nitro): Promise<ScanResult>;
+/**
+ * Scan only client documents (for external services or client-only mode)
+ */
+declare function scanDocumentsOnly(nitro: Nitro): Promise<number>;
+/**
+ * Initialize empty scan results (for skipLocalScan mode)
+ */
+declare function initializeEmptyScanResults(nitro: Nitro): void;
+/**
+ * Perform complete GraphQL scan workflow
+ * This is the main entry point for both initial setup and dev mode rescan
+ *
+ * Workflow:
+ * 1. Check skipLocalScan flag
+ * 2. Scan local files if enabled
+ * 3. Resolve extend config (append to results)
+ * 4. Log diagnostics if needed
+ */
+declare function performGraphQLScan(nitro: Nitro, options?: ScanOptions): Promise<void>;
+/**
+ * Log resolver diagnostics for development
+ */
+declare function logResolverDiagnostics(nitro: Nitro): void;
+//#endregion
+export { ScanOptions, ScanResult, getExtendSources, initializeEmptyScanResults, isServerEnabled, logResolverDiagnostics, performGraphQLScan, scanDocumentsOnly, scanLocalFiles, shouldScanLocalFiles };

package/dist/nitro/setup/scanner.mjs

@@ -0,0 +1,118 @@
+import { LOG_TAG } from "../../core/constants.mjs";
+import { generateDirectiveSchemas } from "../../core/utils/directive-parser.mjs";
+import { NitroAdapter } from "../adapter.mjs";
+import { resolveExtendConfig } from "./extend-loader.mjs";
+import consola from "consola";
+//#region src/nitro/setup/scanner.ts
+const logger = consola.withTag(LOG_TAG);
+/**
+* Check if local file scanning should be performed
+* Centralized helper to avoid scattered skipLocalScan checks
+*/
+function shouldScanLocalFiles(nitro) {
+	return nitro.options.graphql?.skipLocalScan !== true;
+}
+/**
+* Check if server-side GraphQL is enabled
+*/
+function isServerEnabled(nitro) {
+	return nitro.options.graphql?.server !== false;
+}
+/**
+* Get extend sources from config
+*/
+function getExtendSources(nitro) {
+	const extend = nitro.options.graphql?.extend;
+	return Array.isArray(extend) ? extend : void 0;
+}
+/**
+* Scan local GraphQL files (schemas, resolvers, directives, documents)
+* This is the low-level scan function - use performGraphQLScan for full workflow
+*/
+async function scanLocalFiles(nitro) {
+	const directivesResult = await NitroAdapter.scanDirectives(nitro);
+	nitro.scanDirectives = directivesResult.items;
+	const directiveSchemas = await generateDirectiveSchemas(directivesResult.items, nitro.graphql.buildDir);
+	nitro.graphql.directiveSchemas = directiveSchemas;
+	const schemasResult = await NitroAdapter.scanSchemas(nitro);
+	nitro.scanSchemas = schemasResult.items;
+	const docsResult = await NitroAdapter.scanDocuments(nitro);
+	nitro.scanDocuments = docsResult.items;
+	const resolversResult = await NitroAdapter.scanResolvers(nitro);
+	nitro.scanResolvers = resolversResult.items;
+	return {
+		schemas: schemasResult.items.length,
+		resolvers: resolversResult.items.length,
+		directives: directivesResult.items.length,
+		documents: docsResult.items.length
+	};
+}
+/**
+* Scan only client documents (for external services or client-only mode)
+*/
+async function scanDocumentsOnly(nitro) {
+	const result = await NitroAdapter.scanDocuments(nitro);
+	nitro.scanDocuments = result.items;
+	return result.items.length;
+}
+/**
+* Initialize empty scan results (for skipLocalScan mode)
+*/
+function initializeEmptyScanResults(nitro) {
+	nitro.scanSchemas = [];
+	nitro.scanResolvers = [];
+	nitro.scanDirectives = [];
+}
+/**
+* Perform complete GraphQL scan workflow
+* This is the main entry point for both initial setup and dev mode rescan
+*
+* Workflow:
+* 1. Check skipLocalScan flag
+* 2. Scan local files if enabled
+* 3. Resolve extend config (append to results)
+* 4. Log diagnostics if needed
+*/
+async function performGraphQLScan(nitro, options = {}) {
+	const { silent = false, isRescan = false } = options;
+	const serverEnabled = isServerEnabled(nitro);
+	const scanLocal = shouldScanLocalFiles(nitro);
+	const extendSources = getExtendSources(nitro);
+	if (isRescan && !scanLocal && extendSources?.length) return;
+	if (!scanLocal) {
+		if (!isRescan && !silent) if (extendSources?.length) logger.info(`Using ${extendSources.length} extend source(s), skipping local scanning`);
+		else logger.info("Skipping local scanning (skipLocalScan: true)");
+		initializeEmptyScanResults(nitro);
+		await scanDocumentsOnly(nitro);
+	} else if (serverEnabled) await scanLocalFiles(nitro);
+	else await scanDocumentsOnly(nitro);
+	await resolveExtendConfig(nitro, { silent: silent || isRescan });
+}
+/**
+* Log resolver diagnostics for development
+*/
+function logResolverDiagnostics(nitro) {
+	const resolvers = nitro.scanResolvers || [];
+	if (resolvers.length > 0) {
+		const totalExports = resolvers.reduce((sum, r) => sum + r.imports.length, 0);
+		const typeCount = {
+			query: 0,
+			mutation: 0,
+			resolver: 0,
+			type: 0,
+			subscription: 0,
+			directive: 0
+		};
+		for (const resolver of resolvers) for (const imp of resolver.imports) if (imp.type in typeCount) typeCount[imp.type]++;
+		const breakdown = [];
+		if (typeCount.query > 0) breakdown.push(`${typeCount.query} query`);
+		if (typeCount.mutation > 0) breakdown.push(`${typeCount.mutation} mutation`);
+		if (typeCount.resolver > 0) breakdown.push(`${typeCount.resolver} resolver`);
+		if (typeCount.type > 0) breakdown.push(`${typeCount.type} type`);
+		if (typeCount.subscription > 0) breakdown.push(`${typeCount.subscription} subscription`);
+		if (typeCount.directive > 0) breakdown.push(`${typeCount.directive} directive`);
+		if (breakdown.length > 0) logger.success(`${totalExports} resolver export(s): ${breakdown.join(", ")}`);
+	} else logger.warn("No resolvers found. Check /_nitro/graphql/debug for details.");
+}
+//#endregion
+export { getExtendSources, initializeEmptyScanResults, isServerEnabled, logResolverDiagnostics, performGraphQLScan, scanDocumentsOnly, scanLocalFiles, shouldScanLocalFiles };

package/dist/nitro/setup/ts-config.d.mts

@@ -0,0 +1,10 @@
+import { Nitro, NitroTypes } from "nitro/types";
+
+//#region src/nitro/setup/ts-config.d.ts
+/**
+ * Setup TypeScript path aliases for GraphQL types
+ * Called via nitro:config hook to extend tsconfig.json
+ */
+declare function setupTypeScriptPaths(nitro: Nitro, types: NitroTypes): void;
+//#endregion
+export { setupTypeScriptPaths };

package/dist/nitro/setup/ts-config.mjs

@@ -0,0 +1,67 @@
+import { relativeWithDot } from "../../core/utils/imports.mjs";
+import { getDefaultPaths, getTypesConfig, resolveFilePath } from "../paths.mjs";
+import { dirname, join, resolve } from "pathe";
+//#region src/nitro/setup/ts-config.ts
+/**
+* Setup TypeScript path aliases for GraphQL types
+* Called via nitro:config hook to extend tsconfig.json
+*/
+function setupTypeScriptPaths(nitro, types) {
+	const tsconfigDir = dirname(resolve(nitro.options.buildDir, nitro.options.typescript.tsconfigPath ?? "tsconfig.json"));
+	types.tsConfig ||= {};
+	types.tsConfig.compilerOptions ??= {};
+	types.tsConfig.compilerOptions.paths ??= {};
+	types.tsConfig.include = types.tsConfig.include || [];
+	const placeholders = getDefaultPaths(nitro);
+	const typesConfig = getTypesConfig(nitro);
+	setupServerTypesPath(nitro, types, tsconfigDir, placeholders, typesConfig);
+	setupClientTypesPath(nitro, types, tsconfigDir, placeholders, typesConfig);
+	setupSchemaPath(nitro, types, tsconfigDir);
+	setupExternalServicePaths(nitro, types, tsconfigDir, placeholders, typesConfig);
+	types.tsConfig.include.push(relativeWithDot(tsconfigDir, join(placeholders.typesDir, "graphql.d.ts")));
+}
+/**
+* Setup #graphql/server path alias
+*/
+function setupServerTypesPath(nitro, types, tsconfigDir, placeholders, typesConfig) {
+	const serverTypesPath = resolveFilePath(typesConfig.server, typesConfig.enabled, true, "{typesDir}/nitro-graphql-server.d.ts", placeholders);
+	if (serverTypesPath) {
+		types.tsConfig.compilerOptions.paths["#graphql/server"] = [relativeWithDot(tsconfigDir, serverTypesPath)];
+		types.tsConfig.include.push(relativeWithDot(tsconfigDir, serverTypesPath));
+	}
+}
+/**
+* Setup #graphql/client path alias
+*/
+function setupClientTypesPath(nitro, types, tsconfigDir, placeholders, typesConfig) {
+	const clientTypesPath = resolveFilePath(typesConfig.client, typesConfig.enabled, true, "{typesDir}/nitro-graphql-client.d.ts", placeholders);
+	if (clientTypesPath) {
+		types.tsConfig.compilerOptions.paths["#graphql/client"] = [relativeWithDot(tsconfigDir, clientTypesPath)];
+		types.tsConfig.include.push(relativeWithDot(tsconfigDir, clientTypesPath));
+	}
+}
+/**
+* Setup #graphql/schema path alias
+*/
+function setupSchemaPath(nitro, types, tsconfigDir) {
+	types.tsConfig.compilerOptions.paths["#graphql/schema"] = [relativeWithDot(tsconfigDir, join(nitro.graphql.serverDir, "schema.ts"))];
+}
+/**
+* Setup #graphql/client/{serviceName} path aliases for external services
+*/
+function setupExternalServicePaths(nitro, types, tsconfigDir, placeholders, typesConfig) {
+	if (!nitro.options.graphql?.externalServices?.length) return;
+	for (const service of nitro.options.graphql.externalServices) {
+		const servicePlaceholders = {
+			...placeholders,
+			serviceName: service.name
+		};
+		const externalTypesPath = resolveFilePath(service.paths?.types ?? typesConfig.external, typesConfig.enabled, true, "{typesDir}/nitro-graphql-client-{serviceName}.d.ts", servicePlaceholders);
+		if (externalTypesPath) {
+			types.tsConfig.compilerOptions.paths[`#graphql/client/${service.name}`] = [relativeWithDot(tsconfigDir, externalTypesPath)];
+			types.tsConfig.include.push(relativeWithDot(tsconfigDir, externalTypesPath));
+		}
+	}
+}
+//#endregion
+export { setupTypeScriptPaths };