@stonecrop/nuxt-grafserv 0.12.7 → 0.13.0

package/README.md

@@ -39,32 +39,19 @@ For PostGraphile users, this is the recommended configuration approach:
 
 ```bash
 # Using pnpm
-pnpm add @stonecrop/nuxt-grafserv postgraphile
+pnpm add @stonecrop/nuxt-grafserv
 
 # Using yarn
-yarn add @stonecrop/nuxt-grafserv postgraphile
+yarn add @stonecrop/nuxt-grafserv
 
 # Using npm
-npm install @stonecrop/nuxt-grafserv postgraphile
+npm install @stonecrop/nuxt-grafserv
 ```
 
-2. Create your preset file `server/graphile.preset.ts`:
-
-```ts
-import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
-import { makePgService } from 'postgraphile/adaptors/pg'
+2. Set `DATABASE_URL` in your environment (`.env` or shell):
 
-const preset = {
-  extends: [PostGraphileAmberPreset],
-  pgServices: [
-    makePgService({
-      connectionString: process.env.DATABASE_URL || 'postgresql://localhost/mydb',
-      schemas: ['public'],
-    }),
-  ],
-}
-
-export default preset
+```
+DATABASE_URL=postgresql://localhost/mydb
 ```
 
 3. Configure in `nuxt.config.ts`:
@@ -74,13 +61,42 @@ export default defineNuxtConfig({
   modules: ['@stonecrop/nuxt-grafserv'],
   grafserv: {
     type: 'postgraphile', // Required: specify configuration type
-    preset: './server/graphile.preset.ts', // Path to preset file
     url: '/graphql',
     graphiql: true,
+    // fieldCasing: 'pascal',        // optional — defaults to 'camel'
+    // schemas: ['public', 'auth'],  // optional — defaults to ['public']
+    // explain: true,                // optional — enables Ruru Explain tab (dev only)
   }
 })
 ```
 
+For custom plugins, a non-standard connection, or advanced configuration, create a preset file:
+
+```ts
+// server/graphile.preset.ts
+import { createStonecropPreset, makePgService, createStonecropPlugin } from '@stonecrop/graphql-middleware'
+
+export default {
+  extends: [createStonecropPreset()],
+  pgServices: [
+    makePgService({
+      connectionString: process.env.DATABASE_URL,
+      schemas: ['public'],
+    }),
+  ],
+  plugins: [createStonecropPlugin(), MyCustomPlugin],
+}
+```
+
+Then reference it in `nuxt.config.ts`:
+
+```ts
+grafserv: {
+  type: 'postgraphile',
+  preset: './server/graphile.preset.ts',
+}
+```
+
 ### Custom Schema Configuration
 
 For custom GraphQL schemas with your own resolvers:
@@ -117,43 +133,42 @@ Use `type: 'postgraphile'` for PostGraphile-based GraphQL APIs:
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
 | `type` | `'postgraphile'` | ✅ | Configuration type discriminator |
-| `preset` | `string` | ✅ | Path to PostGraphile preset file (e.g., './server/graphile.preset.ts') |
-| `url` | `string` | ❌ | GraphQL endpoint URL (default: '/graphql/') |
-| `graphiql` | `boolean` | ❌ | Enable GraphiQL IDE (default: true in dev, false in prod) |
+| `preset` | `string` | ❌ | Path to preset file. When omitted, a default preset is synthesized from `DATABASE_URL`. |
+| `fieldCasing` | `'camel' \| 'pascal'` | ❌ | Column → field name casing (default: `'camel'`). Ignored when `preset` is set. |
+| `schemas` | `string[]` | ❌ | PostgreSQL schemas to expose (default: `['public']`). Ignored when `preset` is set. |
+| `explain` | `boolean` | ❌ | Enable Ruru Explain tab. **Never use in production.** Ignored when `preset` is set. |
+| `url` | `string` | ❌ | GraphQL endpoint URL (default: `/graphql/`) |
+| `graphiql` | `boolean` | ❌ | Enable GraphiQL IDE (default: `true`) |
 
-> **Important:** The preset must be a file path, not an inline object. See "Why File-Based Presets?" section below.
-
-**Example:**
+**Minimal example (no preset file):**
 
 ```ts
-// nuxt.config.ts
+// nuxt.config.ts — DATABASE_URL is read from process.env automatically
 export default defineNuxtConfig({
   grafserv: {
     type: 'postgraphile',
-    preset: './server/graphile.preset.ts',
-    url: '/graphql',
+    url: '/graphql/',
     graphiql: true,
   }
 })
 ```
 
+**Explicit preset file (for custom plugins and advanced configuration):**
+
 ```ts
 // server/graphile.preset.ts
-import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
-import { makePgService } from 'postgraphile/adaptors/pg'
+import { createStonecropPreset, makePgService, createStonecropPlugin } from '@stonecrop/graphql-middleware'
 
-const preset = {
-  extends: [PostGraphileAmberPreset],
+export default {
+  extends: [createStonecropPreset()],
   pgServices: [
     makePgService({
       connectionString: process.env.DATABASE_URL,
       schemas: ['public'],
     }),
   ],
-  plugins: [MyCustomPlugin],
+  plugins: [createStonecropPlugin(), MyCustomPlugin],
 }
-
-export default preset
 ```
 
 ### Schema Configuration
@@ -165,8 +180,8 @@ Use `type: 'schema'` for custom GraphQL schemas with Grafast resolvers:
 | `type` | `'schema'` | ✅ | Configuration type discriminator |
 | `schema` | `string \| string[] \| SchemaProvider` | ✅ | Path(s) to .graphql files or schema provider function |
 | `resolvers` | `string` | ❌ | Path to resolvers file (required for .graphql files) |
-| `url` | `string` | ❌ | GraphQL endpoint URL (default: '/graphql/') |
-| `graphiql` | `boolean` | ❌ | Enable GraphiQL IDE (default: true in dev, false in prod) |
+| `url` | `string` | ❌ | GraphQL endpoint URL (default: `/graphql/`) |
+| `graphiql` | `boolean` | ❌ | Enable GraphiQL IDE (default: `true`) |
 
 **Example with files:**
 
@@ -176,7 +191,7 @@ export default defineNuxtConfig({
     type: 'schema',
     schema: 'server/**/*.graphql',
     resolvers: 'server/resolvers.ts',
-    url: '/graphql',
+    url: '/graphql/',
   }
 })
 ```
@@ -270,11 +285,10 @@ For database-backed GraphQL APIs:
 1. Create your preset file `server/graphile.preset.ts`:
 
 ```ts
-import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
-import { makePgService } from 'postgraphile/adaptors/pg'
+import { createStonecropPreset, makePgService } from '@stonecrop/graphql-middleware'
 
 const preset = {
-  extends: [PostGraphileAmberPreset],
+  extends: [createStonecropPreset()],
   pgServices: [
     makePgService({
       connectionString: process.env.DATABASE_URL,
@@ -347,12 +361,11 @@ Import the plugins in your preset:
 
 ```ts
 // server/graphile/graphile.preset.ts
-import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
-import { makePgService } from 'postgraphile/adaptors/pg'
+import { createStonecropPreset, makePgService } from '@stonecrop/graphql-middleware'
 import plugins from './plugins'
 
 const preset = {
-  extends: [PostGraphileAmberPreset],
+  extends: [createStonecropPreset()],
   pgServices: [makePgService({ /* ... */ })],
   plugins
 }
@@ -362,78 +375,34 @@ export default preset
 
 #### Available Middleware Hooks
 
-- `processRequest` - Process all incoming requests
-- `processGraphQLRequestBody` - Process GraphQL request bodies
-- `ruruHTML` - Customize Ruru IDE HTML generation
-- `onSubscribe` - Handle GraphQL subscriptions
+These are hooks provided by the `grafserv` package itself via the Graphile preset system — they are not specific to `@stonecrop/nuxt-grafserv`. The hook used in the example above (`processGraphQLRequestBody`) is the most common entry point. For the full list of available hooks, refer to the [Grafserv documentation](https://grafast.org/grafserv/).
 
 ## PostGraphile Integration
 
-PostGraphile v5+ automatically generates your GraphQL schema from PostgreSQL.
+PostGraphile v5+ automatically generates your GraphQL schema from PostgreSQL. When using a custom preset file (`preset` option), you have access to all PostGraphile preset keys — these are PostGraphile features, not Stonecrop-specific ones.
 
 ### With Community Plugins
 
+Third-party PostGraphile plugins can be added via the `plugins` array in a custom preset file:
+
 ```typescript
-import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
-import { makePgService } from 'postgraphile/adaptors/pg'
+// server/graphile.preset.ts
+import { createStonecropPreset, makePgService, createStonecropPlugin } from '@stonecrop/graphql-middleware'
 import PgSimplifyInflectorPlugin from '@graphile-contrib/pg-simplify-inflector'
 
-const preset = {
-  extends: [PostGraphileAmberPreset],
-  plugins: [PgSimplifyInflectorPlugin],
+export default {
+  extends: [createStonecropPreset()],
+  plugins: [createStonecropPlugin(), PgSimplifyInflectorPlugin],
   pgServices: [
     makePgService({
       connectionString: process.env.DATABASE_URL,
       schemas: ['public'],
     }),
   ],
-  schema: {
-    defaultBehavior: 'connection', // Enable Relay-style connections
-  },
-  grafast: {
-    explain: process.env.NODE_ENV === 'development', // Plan diagrams in dev
-  },
 }
-
-export default preset
 ```
 
-### Advanced Configuration
-
-```typescript
-import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
-import { makePgService } from 'postgraphile/adaptors/pg'
-
-const preset = {
-  extends: [PostGraphileAmberPreset],
-  pgServices: [
-    makePgService({
-      connectionString: process.env.DATABASE_URL,
-      schemas: ['public', 'app_private'],
-      superuserConnectionString: process.env.SUPERUSER_DATABASE_URL, // For watch mode
-      pubsub: true, // Enable LISTEN/NOTIFY for subscriptions
-    }),
-  ],
-  gather: {
-    // Smart tags for schema customization
-    pgJwtTypes: 'app_public.jwt_token',
-  },
-  schema: {
-    // Behavior overrides
-    defaultBehavior: '-insert -update -delete', // Read-only by default
-    pgJwtSecret: process.env.JWT_SECRET,
-  },
-  grafast: {
-    explain: true,
-    context: (requestContext) => ({
-      // Custom context for all resolvers
-      userId: requestContext.user?.id,
-    }),
-  },
-}
-
-export default preset
-```
+For further PostGraphile preset configuration (behaviours, JWT, subscriptions, smart tags, etc.), refer to the [PostGraphile v5 documentation](https://postgraphile.org/postgraphile/5/).
 
 ### Why File-Based Presets?
 
@@ -450,10 +419,10 @@ This approach avoids GraphQL module duplication, follows PostGraphile's recommen
 **Your preset file needs a default export:**
 
 ```typescript
-import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
+import { createStonecropPreset } from '@stonecrop/graphql-middleware'
 
 const preset = {
-  extends: [PostGraphileAmberPreset],
+  extends: [createStonecropPreset()],
   // ...
 }
 
@@ -466,13 +435,12 @@ Relative imports in preset files work with file extensions:
 
 ```typescript
 // server/graphile/graphile.preset.ts
-import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
-import { makePgService } from 'postgraphile/adaptors/pg'
+import { createStonecropPreset, makePgService } from '@stonecrop/graphql-middleware'
 import { MyPlugin } from './plugins/my-plugin'
 import { AnotherPlugin } from './plugins/another'
 
 const preset = {
-  extends: [PostGraphileAmberPreset],
+  extends: [createStonecropPreset()],
   pgServices: [makePgService({/*...*/})],
   plugins: [MyPlugin, AnotherPlugin],
 }
@@ -577,27 +545,34 @@ See [Grafast Standard Steps](https://grafast.org/grafast/standard-steps) for the
 
 ## Development
 
+This package lives inside the Stonecrop Rush monorepo. Use `rushx` instead of `pnpm run` to invoke scripts.
+
 ```bash
-# Install dependencies
-pnpm install
+# Install all monorepo dependencies (run from the repo root)
+rush install
+
+# Bootstrap the playground database (first time only — requires Docker)
+cd playground && node scripts/bootstrap.mjs
 
 # Generate type stubs
-pnpm run dev:prepare
+rushx dev:prepare
 
-# Develop with the playground
-pnpm run dev
+# Develop with the playground (from nuxt_grafserv/)
+rushx dev
 
 # Build the module
-pnpm run build
+rushx build
 
 # Run ESLint
-pnpm run lint
+rushx lint
 
 # Run tests
-pnpm run test
-pnpm run test:watch
+rushx test
+rushx test:watch
 ```
 
+The playground runs against a PostgreSQL container managed by Docker Compose. The bootstrap script handles container startup, `.env` creation, and running the initial migration. On subsequent runs `rushx dev` is all that's needed (the container persists via a named volume).
+
 <!-- Badges -->
 [npm-version-src]: https://img.shields.io/npm/v/@stonecrop/nuxt-grafserv/latest.svg?style=flat&colorA=020420&colorB=00DC82
 [npm-version-href]: https://npmjs.com/package/@stonecrop/nuxt-grafserv

package/dist/module.d.mts

@@ -1,5 +1,6 @@
 import { NuxtModule } from '@nuxt/schema';
 import { GraphQLSchema } from 'graphql';
+import { FieldCasing } from '@stonecrop/graphql-middleware';
 
 /**
  * Schema provider function - returns a GraphQL schema
@@ -16,19 +17,30 @@ type SchemaProvider = () => GraphQLSchema | Promise<GraphQLSchema>;
  *
  * @example
  * ```typescript
+ * // Minimal config — no preset file needed. Uses DATABASE_URL automatically.
+ * export default defineNuxtConfig({
+ *   modules: ['@stonecrop/nuxt-grafserv'],
+ *   grafserv: {
+ *     type: 'postgraphile',
+ *     // fieldCasing: 'pascal',           // optional — defaults to 'camel'
+ *     // schemas: ['public', 'auth'],      // optional — defaults to ['public']
+ *     // explain: true,                    // optional — enables Ruru Explain tab; never set in production
+ *   },
+ * })
+ *
+ * // With an explicit preset file (for custom plugins, connection, etc.):
  * // 1. Create server/graphile.preset.ts
- * import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
- * import { makePgService } from 'postgraphile/adaptors/pg'
+ * import { createStonecropPreset, makePgService, createStonecropPlugin } from '@stonecrop/graphql-middleware'
  *
  * export default {
- *   extends: [PostGraphileAmberPreset],
+ *   extends: [createStonecropPreset()],
  *   pgServices: [
  *     makePgService({
  *       connectionString: process.env.DATABASE_URL,
  *       schemas: ['public'],
  *     }),
  *   ],
- *   plugins: [MyCustomPlugin],
+ *   plugins: [createStonecropPlugin(), MyCustomPlugin],
  * }
  *
  * // 2. Reference the preset file in nuxt.config.ts
@@ -47,17 +59,55 @@ interface PostGraphileConfig {
     /** Configuration type discriminator */
     type: 'postgraphile';
     /**
-     * Path to PostGraphile preset file
+     * Path to PostGraphile preset file.
+     *
+     * When omitted, a default preset is synthesized using `DATABASE_URL` for the
+     * connection string and `fieldCasing`/`schemas`/`explain` from this config.
+     * A warning is emitted at startup if `DATABASE_URL` is not set.
      *
      * The preset file must export the preset configuration using default export:
      * `export default { extends: [...], pgServices: [...], plugins: [...] }`
      *
-     * A PostGraphile instance will be created from this preset at build time.
-     *
      * @example './server/graphile.preset.ts'
      * @example './server/graphile.preset.js'
      */
-    preset: string;
+    preset?: string;
+    /**
+     * Column-to-field name casing for the synthesized preset.
+     * - `'camel'` (default): `my_column` → `myColumn` (PostGraphile Amber default)
+     * - `'pascal'`: `my_column` → `MyColumn`
+     *
+     * Ignored when an explicit `preset` file is provided.
+     */
+    fieldCasing?: FieldCasing;
+    /**
+     * PostgreSQL schemas to expose. Defaults to `['public']`.
+     * Ignored when an explicit `preset` file is provided.
+     */
+    schemas?: string[];
+    /**
+     * Enable the Ruru Explain tab (shows Grafast plan + SQL for each query).
+     * **Never enable in production** — it exposes query internals to any client.
+     * Ignored when an explicit `preset` file is provided.
+     *
+     * @default false
+     */
+    explain?: boolean;
+    /**
+     * Enable developer-friendly debug mode. When `true`, the synthesized preset
+     * automatically sets `grafast.explain: true`, injects `createDebugPlugin()`,
+     * and configures `grafserv.maskError` as a pass-through so full error details
+     * are visible in the GraphQL response.
+     *
+     * This is a convenience switch for local development — it is the equivalent of
+     * setting `explain: true` plus the debug plugin plus unmasked errors at once.
+     * **Never enable in production**.
+     *
+     * Ignored when an explicit `preset` file is provided.
+     *
+     * @default false
+     */
+    debug?: boolean;
     /** GraphQL endpoint URL (default: '/graphql/') */
     url?: string;
     /** Whether to enable GraphiQL IDE (default: true in dev, false in prod) */

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@stonecrop/nuxt-grafserv",
   "configKey": "grafserv",
-  "version": "0.12.7",
+  "version": "0.13.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
-import { useLogger, defineNuxtModule, createResolver } from '@nuxt/kit';
+import { useLogger, defineNuxtModule, createResolver, addServerPlugin, addServerHandler } from '@nuxt/kit';
 
 const logger = useLogger("@stonecrop/nuxt-grafserv");
 function validateConfig(options) {
@@ -13,12 +13,6 @@ Example: grafserv: { type: 'postgraphile', preset: { ... } }`
   }
   if (options.type === "postgraphile") {
     const config = options;
-    if (!config.preset) {
-      throw new Error(
-        `[@stonecrop/nuxt-grafserv] PostGraphile configuration error: 'preset' field is required when type is 'postgraphile'. 
-Example: { type: 'postgraphile', preset: { extends: [PostGraphileAmberPreset], ... } }`
-      );
-    }
     if ("schema" in config || "resolvers" in config) {
       logger.warn(
         `PostGraphile configuration should not include 'schema' or 'resolvers' fields. The schema is generated from the 'preset' configuration.`
@@ -78,48 +72,108 @@ const module$1 = defineNuxtModule({
       logger.info(`Grafserv server alias: ${config.alias["#grafserv-server"]}`);
       if (options.type === "postgraphile") {
         logger.info("Using PostGraphile preset configuration");
-        let presetPath = resolveForVirtualModule(options.preset);
-        if (!existsSync(presetPath)) {
-          const extensions = [".ts", ".js", ".mjs"];
-          let found = false;
-          for (const ext of extensions) {
-            const pathWithExt = presetPath + ext;
-            if (existsSync(pathWithExt)) {
-              presetPath = pathWithExt;
-              found = true;
-              break;
+        config.virtual = config.virtual || {};
+        if (!options.preset) {
+          logger.info("Synthesizing PostGraphile preset from DATABASE_URL");
+          const explain = options.debug ? true : options.explain ?? false;
+          const debug = options.debug ?? false;
+          const fieldCasing = options.fieldCasing || "camel";
+          const schemas = JSON.stringify(options.schemas || ["public"]);
+          const extraImports = debug ? `, createDebugPlugin` : ``;
+          const pluginsList = debug ? `createStonecropPlugin({ debug: true }), createDebugPlugin()` : `createStonecropPlugin({ debug: false })`;
+          const grafservBlock = !debug ? `` : `
+							grafserv: {
+								maskError(error) {
+									console.error('maskError was called with the following error:');
+									console.error(error);
+									console.error('which had an originalError of:');
+									console.error(error.originalError);
+									const { GraphQLError } = require('postgraphile/graphql');
+									const { isSafeError } = require('postgraphile/grafast');
+									if (error.originalError instanceof GraphQLError) {
+										return error;
+									} else if (error.originalError && isSafeError(error.originalError)) {
+										return new GraphQLError(
+											error.originalError.message,
+											error.nodes,
+											error.source,
+											error.positions,
+											error.path,
+											error.originalError,
+											error.originalError.extensions ?? null,
+										);
+									} else {
+										const { createHash } = require('node:crypto');
+										const hash = createHash('sha1').update(String(error)).digest('base64url');
+										console.error(\`Masked GraphQL error (hash: '\${hash}')\`, error);
+										return new GraphQLError(
+											\`An error occurred (logged with hash: '\${hash}')\`,
+											error.nodes,
+											error.source,
+											error.positions,
+											error.path,
+											error.originalError,
+											{},
+										);
+									}
+								},
+							},
+						`;
+          config.virtual["#internal/grafserv/pgl"] = `
+						import { postgraphile } from 'postgraphile'
+						import { createStonecropPreset, makePgService, createStonecropPlugin${extraImports} } from '@stonecrop/graphql-middleware'
+
+						const synthesizedPreset = {
+							extends: [createStonecropPreset({ fieldCasing: '${fieldCasing}' })],
+							pgServices: [makePgService({ connectionString: process.env.DATABASE_URL, schemas: ${schemas} })],
+							plugins: [${pluginsList}],
+							grafast: { explain: ${explain} },${grafservBlock}
+						}
+
+						export const pgl = postgraphile(synthesizedPreset)
+					`;
+        } else {
+          let presetPath = resolveForVirtualModule(options.preset);
+          if (!existsSync(presetPath)) {
+            const extensions = [".ts", ".js", ".mjs"];
+            let found = false;
+            for (const ext of extensions) {
+              const pathWithExt = presetPath + ext;
+              if (existsSync(pathWithExt)) {
+                presetPath = pathWithExt;
+                found = true;
+                break;
+              }
             }
-          }
-          if (!found) {
-            throw new Error(
-              `[@stonecrop/nuxt-grafserv] Preset file not found: ${presetPath}
+            if (!found) {
+              throw new Error(
+                `[@stonecrop/nuxt-grafserv] Preset file not found: ${presetPath}
 Tried extensions: ${extensions.join(", ")}
 
 Create the preset file with your PostGraphile configuration:
 
 // ${options.preset}.ts (or .js, .mjs)
-import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
-import { makePgService } from 'postgraphile/adaptors/pg'
+import { createStonecropPreset, makePgService, createStonecropPlugin } from '@stonecrop/graphql-middleware'
 
 export default {
-  extends: [PostGraphileAmberPreset],
+  extends: [createStonecropPreset()],
   pgServices: [makePgService({ connectionString: process.env.DATABASE_URL, schemas: ['public'] })],
-  plugins: [],
+  plugins: [createStonecropPlugin()],
 }
 `
-            );
+              );
+            }
           }
+          logger.info(`Resolved preset path: ${presetPath}`);
+          config.virtual["#internal/grafserv/pgl"] = [
+            `import { postgraphile } from 'postgraphile'`,
+            `import preset from '${presetPath}'`,
+            ``,
+            `// Create PostGraphile instance with the preset`,
+            `// This handles schema building, watch mode, and lifecycle`,
+            `export const pgl = postgraphile(preset)`
+          ].join("\n");
         }
-        logger.info(`Resolved preset path: ${presetPath}`);
-        config.virtual = config.virtual || {};
-        config.virtual["#internal/grafserv/pgl"] = [
-          `import { postgraphile } from 'postgraphile'`,
-          `import preset from '${presetPath}'`,
-          ``,
-          `// Create PostGraphile instance with the preset`,
-          `// This handles schema building, watch mode, and lifecycle`,
-          `export const pgl = postgraphile(preset)`
-        ].join("\n");
         config.virtual["#internal/grafserv/resolvers"] = "export default null";
         config.runtimeConfig = config.runtimeConfig || {};
         config.runtimeConfig.grafserv = {
@@ -163,18 +217,21 @@ export default {
           config.virtual["#internal/grafserv/resolvers"] = "export default null";
         }
       }
-      config.externals = config.externals || {};
-      config.externals.external = config.externals.external || [];
-      config.externals.external.push(
-        "graphql",
-        "grafast",
-        "postgraphile",
-        "graphile-config",
-        "graphile-build",
-        "@graphql-tools/schema",
-        "@graphql-tools/load",
-        "@graphql-tools/graphql-file-loader"
-      );
+      config.externals = {
+        ...config.externals,
+        external: [
+          ...config.externals?.external ?? [],
+          "graphql",
+          "grafast",
+          "postgraphile",
+          "graphile-config",
+          "graphile-build",
+          "@dataplan/pg",
+          "@graphql-tools/schema",
+          "@graphql-tools/load",
+          "@graphql-tools/graphql-file-loader"
+        ]
+      };
       const grafastPath = require.resolve("grafast");
       config.alias = config.alias || {};
       config.alias["grafast"] = grafastPath;
@@ -184,21 +241,16 @@ export default {
       config.typescript.tsConfig.compilerOptions.allowImportingTsExtensions = true;
       config.typescript.tsConfig.compilerOptions.moduleResolution = "bundler";
     });
-    nuxt.hook("nitro:config", (config) => {
-      config.handlers = config.handlers || [];
-      config.handlers.push({
-        route: options.url || "/graphql/",
-        handler: resolve("./runtime/handler")
-      });
-      config.handlers.push({
-        route: "/ruru-static/**",
-        handler: resolve("./runtime/ruru-static")
-      });
-      config.handlers.push({
-        route: "/graphql/cache",
-        handler: resolve("./runtime/cache")
-      });
-    });
+    if (options.type === "postgraphile" && !options.preset) {
+      addServerPlugin(resolve("./runtime/startup-check"));
+    }
+    addServerHandler({ route: options.url || "/graphql/", handler: resolve("./runtime/handler") });
+    if (options.graphiql) {
+      addServerHandler({ route: "/ruru-static/**", handler: resolve("./runtime/ruru-static") });
+    }
+    if (nuxt.options.dev) {
+      addServerHandler({ route: "/graphql/cache", handler: resolve("./runtime/cache") });
+    }
     if (options.url) {
       nuxt.hook("devtools:customTabs", (tabs) => {
         tabs.push({
@@ -217,7 +269,7 @@ export default {
       nuxt.hook("builder:watch", async (event, path) => {
         const isSchemaFile = path.endsWith(".graphql");
         const isResolverFile = options.type === "schema" && options.resolvers && path.includes(options.resolvers.replace("./", ""));
-        const isPresetFile = options.type === "postgraphile" && path.includes(options.preset.replace("./", ""));
+        const isPresetFile = options.type === "postgraphile" && !!options.preset && path.includes(options.preset.replace("./", ""));
         if (isSchemaFile || isResolverFile || isPresetFile) {
           if (!cacheClearing) {
             cacheClearing = true;

package/dist/runtime/startup-check.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("nitropack/types").NitroAppPlugin;
+export default _default;

package/dist/runtime/startup-check.js

@@ -0,0 +1,8 @@
+import { defineNitroPlugin } from "nitropack/runtime";
+export default defineNitroPlugin(() => {
+  if (!process.env.DATABASE_URL) {
+    console.warn(
+      "[@stonecrop/nuxt-grafserv] DATABASE_URL is not set. The synthesized PostGraphile preset will fail to connect. Set DATABASE_URL or provide an explicit preset file via the `preset` option."
+    );
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/nuxt-grafserv",
-  "version": "0.12.7",
+  "version": "0.13.0",
   "description": "Pluggable Grafserv GraphQL server as Nuxt Module",
   "license": "MIT",
   "type": "module",
@@ -40,11 +40,11 @@
     "@graphql-tools/load": "^8.1.10",
     "@graphql-tools/stitch": "^10.1.18",
     "@graphql-tools/wrap": "^11.1.14",
-    "grafast": "^1.0.1",
+    "grafast": "^1.0.2",
     "grafserv": "^1.0.0",
     "graphql": "^16.14.0",
     "postgraphile": "^5.0.3",
-    "@stonecrop/graphql-middleware": "0.12.7"
+    "@stonecrop/graphql-middleware": "0.13.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",