nitro-graphql 2.0.0-beta.36 → 2.0.0-beta.37

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import { NitroGraphQLOptions } from "./types/index.mjs";
+import { resolveSecurityConfig } from "./setup.mjs";
 import { NitroModule } from "nitro/types";
 import { Plugin } from "vite";
 
@@ -40,4 +41,4 @@ declare function graphqlModule(options?: NitroGraphQLOptions): Plugin & {
   nitro?: NitroModule;
 };
 //#endregion
-export { graphqlModule as default };
+export { graphqlModule as default, resolveSecurityConfig };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { setupNitroGraphQL } from "./setup.mjs";
+import { resolveSecurityConfig, setupNitroGraphQL } from "./setup.mjs";
 import { readFile } from "node:fs/promises";
 import defu from "defu";
 
@@ -60,4 +60,4 @@ function graphqlModule(options) {
 var src_default = graphqlModule;
 
 //#endregion
-export { src_default as default };
+export { src_default as default, resolveSecurityConfig };

package/dist/routes/apollo-server.mjs

@@ -6,6 +6,7 @@ import { directives } from "#nitro-graphql/server-directives";
 import { resolvers } from "#nitro-graphql/server-resolvers";
 import { schemas } from "#nitro-graphql/server-schemas";
 import { ApolloServer } from "@apollo/server";
+import { ApolloServerPluginLandingPageDisabled } from "@apollo/server/plugin/disabled";
 import { ApolloServerPluginLandingPageLocalDefault } from "@apollo/server/plugin/landingPage/default";
 import { startServerAndCreateH3Handler } from "nitro-graphql/utils/apollo";
 import { defineEventHandler } from "nitro/h3";
@@ -15,15 +16,40 @@ let apolloServer = null;
 let serverStarted = false;
 async function createApolloServer() {
 	if (!apolloServer) {
-		apolloServer = new ApolloServer(defu({
-			schema: await createMergedSchema({
-				schemas,
-				resolvers,
-				directives,
-				moduleConfig
-			}),
+		const schema = await createMergedSchema({
+			schemas,
+			resolvers,
+			directives,
+			moduleConfig
+		});
+		const securityConfig = moduleConfig.security || {
 			introspection: true,
-			plugins: [ApolloServerPluginLandingPageLocalDefault({ embed: true })]
+			playground: true,
+			maskErrors: false,
+			disableSuggestions: false
+		};
+		const plugins = [];
+		if (securityConfig.playground) plugins.push(ApolloServerPluginLandingPageLocalDefault({ embed: true }));
+		else plugins.push(ApolloServerPluginLandingPageDisabled());
+		const userFacingCodes = [
+			"BAD_USER_INPUT",
+			"GRAPHQL_VALIDATION_FAILED",
+			"UNAUTHENTICATED",
+			"FORBIDDEN",
+			"BAD_REQUEST"
+		];
+		apolloServer = new ApolloServer(defu({
+			schema,
+			introspection: securityConfig.introspection,
+			plugins,
+			formatError: securityConfig.maskErrors ? (formattedError, _error) => {
+				const code = formattedError?.extensions?.code;
+				if (code && userFacingCodes.includes(code)) return formattedError;
+				return {
+					message: "Internal server error",
+					extensions: { code: "INTERNAL_SERVER_ERROR" }
+				};
+			} : void 0
 		}, importedConfig));
 		if (!serverStarted) {
 			await apolloServer.start();

package/dist/routes/graphql-yoga.d.mts

@@ -1,6 +1,6 @@
-import * as nitro_deps_h35 from "nitro/deps/h3";
+import * as nitro_deps_h33 from "nitro/deps/h3";
 
 //#region src/routes/graphql-yoga.d.ts
-declare const _default: nitro_deps_h35.EventHandlerWithFetch<nitro_deps_h35.EventHandlerRequest, Promise<Response>>;
+declare const _default: nitro_deps_h33.EventHandlerWithFetch<nitro_deps_h33.EventHandlerRequest, Promise<Response>>;
 //#endregion
 export { _default as default };

package/dist/routes/graphql-yoga.mjs

@@ -28,17 +28,28 @@ new window.EmbeddedSandbox({
 </html>`;
 let yoga;
 var graphql_yoga_default = defineEventHandler(async (event) => {
-	if (!yoga) yoga = createYoga(defu({
-		schema: await createMergedSchema({
+	if (!yoga) {
+		const schema = await createMergedSchema({
 			schemas,
 			resolvers,
 			directives,
 			moduleConfig
-		}),
-		graphqlEndpoint: "/api/graphql",
-		landingPage: false,
-		renderGraphiQL: () => apolloSandboxHtml
-	}, importedConfig));
+		});
+		const securityConfig = moduleConfig.security || {
+			introspection: true,
+			playground: true,
+			maskErrors: false,
+			disableSuggestions: false
+		};
+		yoga = createYoga(defu({
+			schema,
+			graphqlEndpoint: "/api/graphql",
+			landingPage: securityConfig.playground,
+			graphiql: securityConfig.playground ? { defaultQuery: "# Welcome to GraphQL\n#\n# Try running a query!\n" } : false,
+			renderGraphiQL: securityConfig.playground ? () => apolloSandboxHtml : void 0,
+			maskedErrors: securityConfig.maskErrors
+		}, importedConfig));
+	}
 	const response = await yoga.handleRequest(event.req, event);
 	if (event.res.status && event.res.status !== 200) return new Response(response.body, {
 		...response,

package/dist/routes/health.d.mts

@@ -1,7 +1,7 @@
-import * as nitro_deps_h33 from "nitro/deps/h3";
+import * as nitro_deps_h35 from "nitro/deps/h3";
 
 //#region src/routes/health.d.ts
-declare const _default: nitro_deps_h33.EventHandlerWithFetch<nitro_deps_h33.EventHandlerRequest, Promise<{
+declare const _default: nitro_deps_h35.EventHandlerWithFetch<nitro_deps_h35.EventHandlerRequest, Promise<{
   status: string;
   message: string;
   timestamp: string;

package/dist/setup.d.mts

@@ -1,11 +1,18 @@
+import { SecurityConfig } from "./types/index.mjs";
 import { Nitro } from "nitro/types";
 
 //#region src/setup.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>;
 /**
  * Main setup function for nitro-graphql
  * Coordinates all initialization steps for the module
  */
 declare function setupNitroGraphQL(nitro: Nitro): Promise<void>;
 //#endregion
-export { setupNitroGraphQL };
+export { resolveSecurityConfig, setupNitroGraphQL };

package/dist/setup.mjs

@@ -18,34 +18,52 @@ import { join, relative, resolve } from "pathe";
 //#region src/setup.ts
 const logger = consola.withTag(LOG_TAG);
 /**
+* 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
+	};
+}
+/**
 * Main setup function for nitro-graphql
 * Coordinates all initialization steps for the module
 */
 async function setupNitroGraphQL(nitro) {
-	initializeConfiguration(nitro);
+	const serverEnabled = nitro.options.graphql?.server !== false;
+	initializeConfiguration(nitro, serverEnabled);
 	validateConfiguration(nitro);
 	setupBuildDirectories(nitro);
-	setupRollupExternals(nitro);
-	setupRollupChunking(nitro);
+	if (serverEnabled) {
+		setupRollupExternals(nitro);
+		setupRollupChunking(nitro);
+	}
 	initializeRuntimeConfig(nitro);
-	setupFileWatching(nitro);
-	await scanGraphQLFiles(nitro);
-	setupDevHooks(nitro);
-	await rollupConfig(nitro);
-	await generateTypes(nitro);
-	setupCloseHooks(nitro);
-	registerRouteHandlers(nitro);
+	setupFileWatching(nitro, serverEnabled);
+	await scanGraphQLFiles(nitro, serverEnabled);
+	if (serverEnabled) setupDevHooks(nitro);
+	if (serverEnabled) await rollupConfig(nitro);
+	await generateTypes(nitro, serverEnabled);
+	setupCloseHooks(nitro, serverEnabled);
+	if (serverEnabled) registerRouteHandlers(nitro);
 	setupTypeScriptConfiguration(nitro);
 	setupNuxtIntegration(nitro);
-	generateScaffoldFiles(nitro);
+	if (serverEnabled) generateScaffoldFiles(nitro);
+	logStartupInfo(nitro, serverEnabled);
 }
 /**
 * Initialize default configuration values
 */
-function initializeConfiguration(nitro) {
+function initializeConfiguration(nitro, serverEnabled) {
 	nitro.options.graphql ||= {};
 	nitro.options.graphql.types = defu(nitro.options.graphql.types, DEFAULT_TYPES_CONFIG);
-	if (!nitro.options.graphql?.framework) logger.warn("No GraphQL framework specified. Please set graphql.framework to \"graphql-yoga\" or \"apollo-server\".");
+	if (serverEnabled && !nitro.options.graphql?.framework) logger.warn("No GraphQL framework specified. Please set graphql.framework to \"graphql-yoga\" or \"apollo-server\".");
 	const defaultPaths = getDefaultPaths(nitro);
 	nitro.graphql ||= {
 		buildDir: "",
@@ -58,6 +76,10 @@ function initializeConfiguration(nitro) {
 			server: "server"
 		}
 	};
+	nitro.scanSchemas ||= [];
+	nitro.scanResolvers ||= [];
+	nitro.scanDirectives ||= [];
+	nitro.scanDocuments ||= [];
 }
 /**
 * Validate external services configuration
@@ -96,13 +118,17 @@ function setupBuildDirectories(nitro) {
 * Initialize runtime configuration
 */
 function initializeRuntimeConfig(nitro) {
-	nitro.options.runtimeConfig.graphql = defu(nitro.options.runtimeConfig.graphql || {}, DEFAULT_RUNTIME_CONFIG);
+	const securityConfig = resolveSecurityConfig(nitro.options.graphql?.security);
+	nitro.options.runtimeConfig.graphql = defu(nitro.options.runtimeConfig.graphql || {}, {
+		...DEFAULT_RUNTIME_CONFIG,
+		security: securityConfig
+	});
 }
 /**
 * Setup file watching for development mode
 */
-function setupFileWatching(nitro) {
-	const watchDirs = getWatchDirectories(nitro);
+function setupFileWatching(nitro, serverEnabled) {
+	const watchDirs = serverEnabled ? getWatchDirectories(nitro) : [nitro.graphql.clientDir].filter(Boolean);
 	nitro.graphql.watchDirs = watchDirs;
 	const watcher = setupFileWatcher(nitro, watchDirs);
 	nitro.hooks.hook("close", () => {
@@ -112,8 +138,12 @@ function setupFileWatching(nitro) {
 /**
 * Scan all GraphQL files (schemas, resolvers, directives, documents)
 */
-async function scanGraphQLFiles(nitro) {
-	await scanAllGraphQLFiles(nitro);
+async function scanGraphQLFiles(nitro, serverEnabled) {
+	if (serverEnabled) await scanAllGraphQLFiles(nitro);
+	else {
+		const { scanDocuments } = await import("./utils/index.mjs");
+		nitro.scanDocuments = await scanDocuments(nitro);
+	}
 }
 /**
 * Setup dev mode hooks for rescanning files
@@ -157,16 +187,18 @@ function logResolverDiagnostics(nitro) {
 /**
 * Generate server and client types
 */
-async function generateTypes(nitro) {
-	await generateServerTypes(nitro);
-	await generateClientTypes(nitro, { isInitial: true });
+async function generateTypes(nitro, serverEnabled) {
+	if (serverEnabled) {
+		await generateServerTypes(nitro);
+		await generateClientTypes(nitro, { isInitial: true });
+	} else await generateClientTypes(nitro, { isInitial: true });
 }
 /**
 * Setup close hooks for final type generation
 */
-function setupCloseHooks(nitro) {
+function setupCloseHooks(nitro, serverEnabled) {
 	nitro.hooks.hook("close", async () => {
-		await generateServerTypes(nitro, { silent: true });
+		if (serverEnabled) await generateServerTypes(nitro, { silent: true });
 		await generateClientTypes(nitro, { silent: true });
 	});
 }
@@ -215,6 +247,52 @@ function setupNuxtIntegration(nitro) {
 		if (nuxtOptions) nuxtOptions.nitroGraphqlExternalServices = nitro.options.graphql?.externalServices || [];
 	});
 }
+/**
+* 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 { setupNitroGraphQL };
+export { resolveSecurityConfig, setupNitroGraphQL };

package/dist/types/index.d.mts

@@ -16,6 +16,13 @@ type GenericSdkConfig = Omit<Parameters<typeof plugin$1>[2], 'documentMode'> & {
 };
 type CodegenClientConfig = TypeScriptPluginConfig & TypeScriptDocumentsPluginConfig & {
   endpoint?: string;
+  /**
+   * Generate TypedDocumentNode exports for urql/Apollo Client compatibility.
+   * When enabled, generates typed document constants that can be used with
+   * any GraphQL client that supports TypedDocumentNode.
+   * @default false
+   */
+  typedDocumentNode?: boolean;
 };
 interface IESMImport {
   name: string;
@@ -72,10 +79,13 @@ interface ExternalServicePaths {
 interface ExternalGraphQLService {
   /** Unique name for this service (used for file naming and type generation) */
   name: string;
-  /** Schema source - can be URL(s) for remote schemas or file path(s) for local schemas */
-  schema: string | string[];
-  /** GraphQL endpoint for this service */
+  /** GraphQL endpoint for this service (also used as schema source if `schema` is not specified) */
   endpoint: string;
+  /**
+   * Schema source - can be URL(s) for remote schemas or file path(s) for local schemas
+   * @default Uses `endpoint` for introspection if not specified
+   */
+  schema?: string | string[];
   /** Optional headers for schema introspection and client requests */
   headers?: Record<string, string> | (() => Record<string, string>);
   /** Optional: specific document patterns for this service */
@@ -187,8 +197,43 @@ interface PathsConfig {
   /** Types directory (default: '{buildDir}/types') */
   typesDir?: string;
 }
+/**
+ * Security configuration for production environments
+ * All options auto-detect based on NODE_ENV when not explicitly set
+ */
+interface SecurityConfig {
+  /**
+   * Enable GraphQL introspection queries
+   * @default true in development, false in production
+   */
+  introspection?: boolean;
+  /**
+   * Enable GraphQL playground/sandbox UI
+   * @default true in development, false in production
+   */
+  playground?: boolean;
+  /**
+   * Mask internal error details in responses
+   * When enabled, internal errors show "Internal server error" instead of actual message
+   * @default false in development, true in production
+   */
+  maskErrors?: boolean;
+  /**
+   * Disable "Did you mean X?" field suggestions in error messages
+   * Prevents attackers from discovering field names via brute force
+   * @default false in development, true in production
+   */
+  disableSuggestions?: boolean;
+}
 interface NitroGraphQLOptions {
   framework?: 'graphql-yoga' | 'apollo-server';
+  /**
+   * Enable/disable GraphQL server functionality
+   * When set to false, only external services client types will be generated
+   * Server routes, resolvers, schemas, and directives will not be processed
+   * @default true
+   */
+  server?: boolean;
   endpoint?: {
     graphql?: string;
     healthCheck?: string;
@@ -241,6 +286,11 @@ interface NitroGraphQLOptions {
    * Customize base directories for file generation
    */
   paths?: PathsConfig;
+  /**
+   * Security configuration for production environments
+   * Auto-detects NODE_ENV and applies secure defaults in production
+   */
+  security?: SecurityConfig;
 }
 //#endregion
-export { ClientUtilsConfig, CodegenClientConfig, CodegenServerConfig, ExternalGraphQLService, ExternalServicePaths, FederationConfig, FileGenerationConfig, GenImport, GenericSdkConfig, NitroGraphQLOptions, PathsConfig, ScaffoldConfig, SdkConfig, StandardSchemaV1, TypesConfig };
+export { ClientUtilsConfig, CodegenClientConfig, CodegenServerConfig, ExternalGraphQLService, ExternalServicePaths, FederationConfig, FileGenerationConfig, GenImport, GenericSdkConfig, NitroGraphQLOptions, PathsConfig, ScaffoldConfig, SdkConfig, SecurityConfig, StandardSchemaV1, TypesConfig };

package/dist/utils/client-codegen.mjs

@@ -8,9 +8,10 @@ import { parse } from "graphql";
 import { createHash } from "node:crypto";
 import { codegen } from "@graphql-codegen/core";
 import { preset } from "@graphql-codegen/import-types-preset";
-import { plugin } from "@graphql-codegen/typescript";
-import { plugin as plugin$1 } from "@graphql-codegen/typescript-generic-sdk";
-import { plugin as plugin$2 } from "@graphql-codegen/typescript-operations";
+import { plugin } from "@graphql-codegen/typed-document-node";
+import { plugin as plugin$1 } from "@graphql-codegen/typescript";
+import { plugin as plugin$2 } from "@graphql-codegen/typescript-generic-sdk";
+import { plugin as plugin$3 } from "@graphql-codegen/typescript-operations";
 import { GraphQLFileLoader } from "@graphql-tools/graphql-file-loader";
 import { loadDocuments, loadSchemaSync } from "@graphql-tools/load";
 import { UrlLoader } from "@graphql-tools/url-loader";
@@ -41,7 +42,8 @@ async function graphQLLoadSchemaSync(schemaPointers, data = {}) {
 async function loadExternalSchema(service, buildDir) {
 	try {
 		const headers = typeof service.headers === "function" ? service.headers() : service.headers || {};
-		const schemas = Array.isArray(service.schema) ? service.schema : [service.schema];
+		const schemaSource = service.schema ?? service.endpoint;
+		const schemas = Array.isArray(schemaSource) ? schemaSource : [schemaSource];
 		if (service.downloadSchema && buildDir) {
 			const defaultPath = resolve(buildDir, "graphql", "schemas", `${service.name}.graphql`);
 			const schemaFilePath = service.downloadPath ? resolve(service.downloadPath) : defaultPath;
@@ -82,7 +84,8 @@ async function downloadAndSaveSchema(service, buildDir) {
 	const schemaFilePath = service.downloadPath ? resolve(service.downloadPath) : defaultPath;
 	try {
 		const headers = typeof service.headers === "function" ? service.headers() : service.headers || {};
-		const schemas = Array.isArray(service.schema) ? service.schema : [service.schema];
+		const schemaSource = service.schema ?? service.endpoint;
+		const schemas = Array.isArray(schemaSource) ? schemaSource : [schemaSource];
 		const hasUrlSchemas = schemas.some((schema) => isUrl(schema));
 		const hasLocalSchemas = schemas.some((schema) => !isUrl(schema));
 		let shouldDownload = false;
@@ -184,7 +187,7 @@ async function generateClientTypes(schema, docs, config = {}, sdkConfig = {}, ou
 				plugins: [{ pluginContent: {} }, { typescript: {} }],
 				pluginMap: {
 					pluginContent: { plugin: pluginContent },
-					typescript: { plugin }
+					typescript: { plugin: plugin$1 }
 				}
 			}),
 			sdk: `// THIS FILE IS GENERATED, DO NOT EDIT!
@@ -213,21 +216,28 @@ export function getSdk(requester: Requester): Sdk {
 }
 `
 		};
+		const enableTypedDocumentNode = config.typedDocumentNode === true;
+		const plugins = [
+			{ pluginContent: {} },
+			{ typescript: {} },
+			{ typescriptOperations: {} }
+		];
+		const pluginMap = {
+			pluginContent: { plugin: pluginContent },
+			typescript: { plugin: plugin$1 },
+			typescriptOperations: { plugin: plugin$3 }
+		};
+		if (enableTypedDocumentNode) {
+			plugins.push({ typedDocumentNode: {} });
+			pluginMap.typedDocumentNode = { plugin };
+		}
 		const output = await codegen({
 			filename: outputPath || "client-types.generated.ts",
 			schema: parse(printSchemaWithDirectives(schema)),
 			documents: [...docs],
 			config: mergedConfig,
-			plugins: [
-				{ pluginContent: {} },
-				{ typescript: {} },
-				{ typescriptOperations: {} }
-			],
-			pluginMap: {
-				pluginContent: { plugin: pluginContent },
-				typescript: { plugin },
-				typescriptOperations: { plugin: plugin$2 }
-			}
+			plugins,
+			pluginMap
 		});
 		const typesPath = virtualTypesPath || (serviceName ? `#graphql/client/${serviceName}` : "#graphql/client");
 		const sdkOutput = await preset.buildGeneratesSection({
@@ -239,7 +249,7 @@ export function getSdk(requester: Requester): Sdk {
 			plugins: [{ pluginContent: {} }, { typescriptGenericSdk: {} }],
 			pluginMap: {
 				pluginContent: { plugin: pluginContent },
-				typescriptGenericSdk: { plugin: plugin$1 }
+				typescriptGenericSdk: { plugin: plugin$2 }
 			}
 		});
 		return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nitro-graphql",
   "type": "module",
-  "version": "2.0.0-beta.36",
+  "version": "2.0.0-beta.37",
   "description": "GraphQL integration for Nitro",
   "license": "MIT",
   "repository": {
@@ -88,6 +88,7 @@
     "@apollo/subgraph": "^2.12.2",
     "@graphql-codegen/core": "^5.0.0",
     "@graphql-codegen/import-types-preset": "^3.0.1",
+    "@graphql-codegen/typed-document-node": "^6.1.5",
     "@graphql-codegen/typescript": "^5.0.6",
     "@graphql-codegen/typescript-generic-sdk": "^4.0.2",
     "@graphql-codegen/typescript-operations": "^5.0.6",
@@ -123,7 +124,7 @@
     "eslint": "^9.39.2",
     "graphql": "16.12.0",
     "graphql-yoga": "5.16.2",
-    "nitro": "npm:nitro-nightly@latest",
+    "nitro": "3.0.1-alpha.1",
     "tsdown": "^0.17.4",
     "typescript": "^5.9.3",
     "vite": "8.0.0-beta.0",