@stonecrop/nuxt-grafserv 0.7.6 → 0.7.9

package/README.md

@@ -31,79 +31,187 @@ The module automatically registers these handlers:
 
 ## Quick Setup
 
-1. Add `@stonecrop/nuxt-grafserv` dependency to your project:
+### PostGraphile Integration (Recommended)
+
+For PostGraphile users, this is the recommended configuration approach:
+
+1. Add dependencies:
 
 ```bash
 # Using pnpm
-pnpm add @stonecrop/nuxt-grafserv
+pnpm add @stonecrop/nuxt-grafserv postgraphile
 
 # Using yarn
-yarn add @stonecrop/nuxt-grafserv
+yarn add @stonecrop/nuxt-grafserv postgraphile
 
 # Using npm
-npm install @stonecrop/nuxt-grafserv
+npm install @stonecrop/nuxt-grafserv postgraphile
+```
+
+2. Create your preset file `server/graphile.preset.ts`:
+
+```ts
+import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
+import { makePgService } from 'postgraphile/adaptors/pg'
+
+const preset = {
+  extends: [PostGraphileAmberPreset],
+  pgServices: [
+    makePgService({
+      connectionString: process.env.DATABASE_URL || 'postgresql://localhost/mydb',
+      schemas: ['public'],
+    }),
+  ],
+}
+
+export default preset
+```
+
+3. Configure in `nuxt.config.ts`:
+
+```ts
+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,
+  }
+})
 ```
 
-2. Add `@stonecrop/nuxt-grafserv` to the `modules` section of `nuxt.config.ts`:
+### Custom Schema Configuration
+
+For custom GraphQL schemas with your own resolvers:
+
+1. Add dependency:
+
+```bash
+pnpm add @stonecrop/nuxt-grafserv
+```
+
+2. Configure in `nuxt.config.ts`:
 
 ```ts
 export default defineNuxtConfig({
   modules: ['@stonecrop/nuxt-grafserv'],
   grafserv: {
+    type: 'schema', // Required: specify configuration type
     schema: 'server/**/*.graphql',
     resolvers: 'server/resolvers.ts',
-    url: '/graphql/', // Serves both GraphQL API and Ruru UI
+    url: '/graphql',
+    graphiql: true,
   }
 })
 ```
 
 ## Configuration
 
-### All Available Options
+The module supports two configuration types using a discriminated union pattern:
+
+### PostGraphile Configuration
+
+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) |
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `schema` | `string \| string[] \| SchemaProvider \| PostGraphileInstance` | `'server/**/*.graphql'` | Path(s) to GraphQL schema files, schema provider function, or PostGraphile instance |
-| `resolvers` | `string` | `undefined` | Path to resolvers file (optional - not needed for PostGraphile) |
-| `url` | `string` | `'/graphql/'` | GraphQL endpoint URL (also serves Ruru UI) |
-| `graphiql` | `boolean` | `true` in dev, `false` in prod | Enable GraphiQL IDE |
-| `preset` | `GraphileConfig.Preset` | `undefined` | Custom Graphile preset for advanced configuration |
+> **Important:** The preset must be a file path, not an inline object. See "Why File-Based Presets?" section below.
 
-### Full Configuration Example
+**Example:**
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  grafserv: {
+    type: 'postgraphile',
+    preset: './server/graphile.preset.ts',
+    url: '/graphql',
+    graphiql: true,
+  }
+})
+```
+
+```ts
+// server/graphile.preset.ts
+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'],
+    }),
+  ],
+  plugins: [MyCustomPlugin],
+}
+
+export default preset
+```
+
+### Schema Configuration
+
+Use `type: 'schema'` for custom GraphQL schemas with Grafast resolvers:
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `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) |
+
+**Example with files:**
 
 ```ts
 export default defineNuxtConfig({
-  modules: ['@stonecrop/nuxt-grafserv'],
   grafserv: {
-    // Schema configuration
+    type: 'schema',
     schema: 'server/**/*.graphql',
     resolvers: 'server/resolvers.ts',
+    url: '/graphql',
+  }
+})
+```
 
-    // Endpoints
-    url: '/graphql/', // Serves both GraphQL API and Ruru UI
-    graphiql: true,
+**Example with schema provider function:**
 
-    // Graphile preset with grafserv options
-    preset: {
-      grafserv: {
-        websockets: false,
-        graphqlOverGET: true, // Enable GET requests for queries
-        maxRequestLength: 100000,
-        allowedRequestContentTypes: [
-          'application/json',
-          'application/graphql+json'
-        ]
-      },
-      grafast: {
-        explain: true, // Enable plan diagrams
-      }
+```ts
+export default defineNuxtConfig({
+  grafserv: {
+    type: 'schema',
+    schema: async () => {
+      // Return a GraphQLSchema instance
+      return myCustomSchema
     },
   }
 })
 ```
 
+### Configuration Comparison
+
+| Feature | PostGraphile Config | Schema Config |
+|---------|---------------------|---------------|
+| Type discriminator | `type: 'postgraphile'` | `type: 'schema'` |
+| Schema source | Generated from preset | Files or function |
+| Resolvers | Auto-generated by PostGraphile | Must provide via resolvers file |
+| Primary use case | PostgreSQL-backed APIs | Custom GraphQL APIs |
+| Setup complexity | Minimal (DB connection only) | Moderate (schema + resolvers) |
+| Plugin system | PostGraphile plugins | Grafast standard steps |
+
 ## Basic Usage
 
+### Schema Configuration Example
+
+For custom schemas with resolvers:
+
 1. Create your GraphQL schema (`server/schema.graphql`):
 
 ```graphql
@@ -120,7 +228,7 @@ type Mutation {
 2. Create your resolvers (`server/resolvers.ts`):
 
 ```typescript
-import { constant, lambda, access, object, filter, type GrafastSchemaConfig } from 'grafast'
+import { constant, lambda, type GrafastSchemaConfig } from 'grafast'
 
 const resolvers: GrafastSchemaConfig['objects'] = {
   Query: {
@@ -142,61 +250,64 @@ const resolvers: GrafastSchemaConfig['objects'] = {
 export default resolvers
 ```
 
-## Advanced Usage
-
-### Middleware via Grafserv Plugins
-
-For middleware functionality (authentication, logging, etc.), use Grafserv plugins. The CLI installer creates a `server/plugins.ts` file with examples.
-
-#### Inline Plugin Configuration
+3. Configure Nuxt:
 
 ```ts
 export default defineNuxtConfig({
+  modules: ['@stonecrop/nuxt-grafserv'],
   grafserv: {
-    preset: {
-      plugins: [
-        {
-          name: 'request-logging',
-          version: '1.0.0',
-          grafserv: {
-            middleware: {
-              processGraphQLRequestBody: async (next, event) => {
-                const start = Date.now()
-                console.log('[GraphQL] Request started')
-
-                const result = await next()
-
-                console.log(`[GraphQL] Completed in ${Date.now() - start}ms`)
-                return result
-              }
-            }
-          }
-        }
-      ]
-    }
+    type: 'schema',
+    schema: 'server/schema.graphql',
+    resolvers: 'server/resolvers.ts',
   }
 })
 ```
 
-#### Using External Plugin File
+### PostGraphile Configuration Example
+
+For database-backed GraphQL APIs:
+
+1. Create your preset file `server/graphile.preset.ts`:
 
 ```ts
-// nuxt.config.ts
-import plugins from './server/plugins'
+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'],
+    }),
+  ],
+}
+
+export default preset
+```
+
+2. Configure PostGraphile in `nuxt.config.ts`:
+
+```ts
 export default defineNuxtConfig({
+  modules: ['@stonecrop/nuxt-grafserv'],
   grafserv: {
-    schema: 'server/schema.graphql',
-    resolvers: 'server/resolvers.ts',
-    preset: {
-      plugins
-    }
+    type: 'postgraphile',
+    preset: './server/graphile.preset.ts',
   }
 })
 ```
 
+3. That's it! PostGraphile automatically generates your GraphQL schema from your PostgreSQL database.
+
+## Advanced Usage
+
+### Custom Grafserv Plugins
+
+Add custom plugins for authentication, logging, or rate limiting through your preset file:
+
 ```ts
-// server/plugins.ts
+// server/graphile/plugins.ts
 import type { GraphileConfig } from 'graphile-config'
 
 const loggingPlugin: GraphileConfig.Plugin = {
@@ -219,7 +330,10 @@ const authPlugin: GraphileConfig.Plugin = {
     middleware: {
       processGraphQLRequestBody: async (next, event) => {
         const token = event.request.headers.get('authorization')
-        // TODO: Validate token and add user to context
+        // Validate token and add user to context
+        if (!token) {
+          throw new Error('Unauthorized')
+        }
         return next()
       }
     }
@@ -229,6 +343,23 @@ const authPlugin: GraphileConfig.Plugin = {
 export default [loggingPlugin, authPlugin]
 ```
 
+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 plugins from './plugins'
+
+const preset = {
+  extends: [PostGraphileAmberPreset],
+  pgServices: [makePgService({ /* ... */ })],
+  plugins
+}
+
+export default preset
+```
+
 #### Available Middleware Hooks
 
 - `processRequest` - Process all incoming requests
@@ -236,186 +367,122 @@ export default [loggingPlugin, authPlugin]
 - `ruruHTML` - Customize Ruru IDE HTML generation
 - `onSubscribe` - Handle GraphQL subscriptions
 
-## Advanced Usage
-
-### PostGraphile Integration
-
-This module has first-class support for PostGraphile, enabling instant GraphQL APIs from PostgreSQL databases. PostGraphile generates the complete schema and resolvers, so you don't need to define them manually.
+## PostGraphile Integration
 
-#### Setup with PostGraphile
+PostGraphile v5+ automatically generates your GraphQL schema from PostgreSQL.
 
-1. Install PostGraphile:
-
-```bash
-pnpm add postgraphile @graphile/crystal graphile-build-pg
-```
-
-2. Create a PostGraphile schema provider (`server/graphql/schema.ts`):
+### With Community Plugins
 
 ```typescript
-import { postgraphile } from 'postgraphile'
-import type { GraphQLSchema } from 'graphql'
+import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
+import { makePgService } from 'postgraphile/adaptors/pg'
+import PgSimplifyInflectorPlugin from '@graphile-contrib/pg-simplify-inflector'
 
-// Define your PostGraphile preset
 const preset = {
+  extends: [PostGraphileAmberPreset],
+  plugins: [PgSimplifyInflectorPlugin],
   pgServices: [
-    {
-      name: 'main',
-      connectionString: process.env.DATABASE_URL || 'postgres://localhost/mydb',
+    makePgService({
+      connectionString: process.env.DATABASE_URL,
       schemas: ['public'],
-    },
+    }),
   ],
-  grafserv: {
-    websockets: false, // Disable websockets for Nuxt compatibility
+  schema: {
+    defaultBehavior: 'connection', // Enable Relay-style connections
+  },
+  grafast: {
+    explain: process.env.NODE_ENV === 'development', // Plan diagrams in dev
   },
 }
 
-// Create PostGraphile instance
-const pgl = postgraphile(preset)
-
-// Export schema provider function
-export async function createPostGraphileSchema(): Promise<GraphQLSchema> {
-  const { schema } = await pgl.getSchemaResult()
-  return schema
-}
-
-// Export the instance if you need direct access
-export { pgl }
+export default preset
 ```
 
-3. Configure Nuxt to use the PostGraphile schema:
+### Advanced Configuration
 
 ```typescript
-// nuxt.config.ts
-import { createPostGraphileSchema } from './server/graphql/schema'
-
-export default defineNuxtConfig({
-  modules: ['@stonecrop/nuxt-grafserv'],
-  grafserv: {
-    // Use PostGraphile schema provider function
-    schema: createPostGraphileSchema,
-    // No resolvers needed - PostGraphile generates everything
-    url: '/graphql',
-    graphiql: true, // Enable Ruru IDE
-  }
-})
-```
-
-#### Direct PostGraphile Instance Usage
-
-You can also pass a PostGraphile instance directly:
-
-```typescript
-// nuxt.config.ts
-import { pgl } from './server/graphql/schema'
-
-export default defineNuxtConfig({
-  grafserv: {
-    schema: pgl, // Pass PostGraphile instance directly
-    url: '/graphql',
-  }
-})
-```
-
-#### PostGraphile with Custom Plugins
-
-Enhance your PostGraphile setup with custom plugins:
-
-```typescript
-// server/graphql/schema.ts
-import { postgraphile } from 'postgraphile'
 import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
-import PgSimplifyInflectorPlugin from '@graphile-contrib/pg-simplify-inflector'
+import { makePgService } from 'postgraphile/adaptors/pg'
 
 const preset = {
   extends: [PostGraphileAmberPreset],
-  plugins: [PgSimplifyInflectorPlugin],
   pgServices: [
-    {
-      name: 'main',
+    makePgService({
       connectionString: process.env.DATABASE_URL,
-      schemas: ['public'],
-    },
+      schemas: ['public', 'app_private'],
+      superuserConnectionString: process.env.SUPERUSER_DATABASE_URL, // For watch mode
+      pubsub: true, // Enable LISTEN/NOTIFY for subscriptions
+    }),
   ],
-  grafserv: {
-    websockets: false,
-  },
-  grafast: {
-    explain: process.env.NODE_ENV === 'development', // Enable plan diagrams in dev
+  gather: {
+    // Smart tags for schema customization
+    pgJwtTypes: 'app_public.jwt_token',
   },
   schema: {
-    // Add custom behavior overrides
-    defaultBehavior: 'connection', // Enable Relay-style connections by default
+    // 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,
+    }),
   },
 }
 
-const pgl = postgraphile(preset)
-
-export async function createPostGraphileSchema() {
-  const { schema } = await pgl.getSchemaResult()
-  return schema
-}
+export default preset
 ```
 
-#### Benefits of PostGraphile Integration
+### Why File-Based Presets?
 
-- **Zero Schema Definition**: Automatically generates GraphQL schema from PostgreSQL
-- **Auto-Generated Resolvers**: All queries and mutations created from database schema
-- **Real-time Subscriptions**: Live query support via PostgreSQL LISTEN/NOTIFY
-- **Row-Level Security**: Leverages PostgreSQL RLS for authorization
-- **High Performance**: Uses Grafast execution engine with intelligent batching
-- **Type Safety**: Full TypeScript support for generated schema
+PostGraphile presets must be in separate files, not inline in `nuxt.config.ts`.
 
-### Custom Graphile Preset
+The module uses PostGraphile's [instance-based approach](https://postgraphile.org/postgraphile/next/usage-library):
 
-Leverage the full power of the Graphile ecosystem with custom presets:
+1. At build time, the preset file is imported and a PostGraphile instance is created
+2. The instance is exposed via Nitro's virtual module system
+3. At runtime, handlers call `pgl.getSchema()` to get the schema
 
-```ts
+This approach avoids GraphQL module duplication, follows PostGraphile's recommended pattern, supports watch mode, and properly handles database connections.
+
+**Your preset file needs a default export:**
+
+```typescript
 import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
 
-export default defineNuxtConfig({
-  grafserv: {
-    preset: {
-      extends: [PostGraphileAmberPreset],
-      grafast: {
-        explain: true, // Enable plan diagrams for debugging
-        context: {
-          // Custom context available in all resolvers
-          apiVersion: '1.0'
-        }
-      },
-      grafserv: {
-        graphqlOverGET: true,
-        maxRequestLength: 200000
-      }
-    }
-  }
-})
-```
+const preset = {
+  extends: [PostGraphileAmberPreset],
+  // ...
+}
 
-### Accessing Grafserv Instance
+export default preset
+```
 
-For advanced use cases, you can access the grafserv instance directly:
+**Import Requirements:**
 
-```ts
-// server/api/custom.ts
-import { getGrafservInstance } from '@stonecrop/nuxt-grafserv/runtime/handler'
-import { useRuntimeConfig } from '#imports'
+Relative imports in preset files work with file extensions:
 
-export default defineEventHandler(async (event) => {
-  const config = useRuntimeConfig()
-  const serv = await getGrafservInstance(config.grafserv)
+```typescript
+// server/graphile/graphile.preset.ts
+import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
+import { makePgService } from 'postgraphile/adaptors/pg'
+import { MyPlugin } from './plugins/my-plugin'
+import { AnotherPlugin } from './plugins/another'
 
-  // Access grafserv methods or configuration
-  const preset = serv.getPreset()
+const preset = {
+  extends: [PostGraphileAmberPreset],
+  pgServices: [makePgService({/*...*/})],
+  plugins: [MyPlugin, AnotherPlugin],
+}
 
-  return { preset }
-})
+export default preset
 ```
 
-### Schema Building with Objects Structure
+### Schema Building with Grafast
 
-The module uses Grafast's modern objects structure for better type safety and performance. Leverage Grafast's standard steps for common operations:
+Grafast uses a step-based execution model. Common patterns:
 
 ```typescript
 import { constant, lambda, access, object, filter, type GrafastSchemaConfig } from 'grafast'
@@ -498,26 +565,15 @@ export default resolvers
 ```
 
 **Key Concepts:**
-- All resolvers return **steps** (constant, lambda, access, object, filter, etc.), not plain values
-- Arguments are accessed via `fieldArgs.$argumentName` (note the `$` prefix)
-- Use `constant()` for static values
-- Use `lambda()` to transform step values at execution time
-- Use `access()` to extract object properties (more efficient than lambda for simple property access)
-- Use `object()` to compose objects from multiple steps
-- Use `filter()` for list filtering operations
-- Source objects (`$source`, `$user`, `$order`, etc.) are also steps that need `lambda()` or `access()` to work with their properties
-
-**Standard Steps Reference:**
-- `constant()` - Create a step from a static value
-- `lambda()` - Transform step values with execution-time callbacks
-- `access()` - Extract properties from object steps
-- `object()` - Compose objects from multiple steps
-- `filter()` - Filter list steps based on conditions
-- `list()` - Create lists from step tuples
-- `first()`/`last()` - Get first/last elements from lists
-- `loadOne()`/`loadMany()` - Batch data loading (DataLoader-style)
-
-For the complete list, see [Grafast Standard Steps](https://grafast.org/grafast/standard-steps)
+- Resolvers return **steps** (constant, lambda, access, object, filter), not plain values
+- Arguments are accessed via `fieldArgs.$argumentName`
+- `constant()` - static values
+- `lambda()` - transform step values at execution time
+- `access()` - extract object properties efficiently
+- `object()` - compose objects from steps
+- `filter()` - filter list steps
+
+See [Grafast Standard Steps](https://grafast.org/grafast/standard-steps) for the complete reference.
 
 ## Development
 

package/dist/module.d.mts

@@ -1,39 +1,132 @@
 import { NuxtModule } from '@nuxt/schema';
-import { PromiseOrDirect } from 'grafast';
 import { GraphQLSchema } from 'graphql';
-import { GraphileConfig } from 'graphile-config';
 
 /**
  * Schema provider function - returns a GraphQL schema
  */
 type SchemaProvider = () => GraphQLSchema | Promise<GraphQLSchema>;
 /**
- * PostGraphile instance interface (minimal type for compatibility)
+ * PostGraphile configuration using preset
+ *
+ * This is the recommended approach for PostGraphile integration.
+ * The preset file path is resolved and imported at runtime, then passed to PostGraphile's makeSchema() function.
+ *
+ * Note: Inline preset objects are not supported due to Nitro's build/runtime separation.
+ * Complex objects with extends arrays, plugins, and functions cannot be serialized across this boundary.
+ *
+ * @example
+ * ```typescript
+ * // 1. Create server/graphile.preset.ts
+ * import { PostGraphileAmberPreset } from 'postgraphile/presets/amber'
+ * import { makePgService } from 'postgraphile/adaptors/pg'
+ *
+ * export default {
+ *   extends: [PostGraphileAmberPreset],
+ *   pgServices: [
+ *     makePgService({
+ *       connectionString: process.env.DATABASE_URL,
+ *       schemas: ['public'],
+ *     }),
+ *   ],
+ *   plugins: [MyCustomPlugin],
+ * }
+ *
+ * // 2. Reference the preset file in nuxt.config.ts
+ * export default defineNuxtConfig({
+ *   modules: ['@stonecrop/nuxt-grafserv'],
+ *   grafserv: {
+ *     type: 'postgraphile',
+ *     preset: './server/graphile.preset.ts',
+ *     url: '/graphql',
+ *     graphiql: true,
+ *   },
+ * })
+ * ```
  */
-interface PostGraphileInstance {
-    getSchema(): PromiseOrDirect<GraphQLSchema>;
-    getSchemaResult(): PromiseOrDirect<{
-        schema: GraphQLSchema;
-        resolvedPreset: GraphileConfig.ResolvedPreset;
-    }>;
+interface PostGraphileConfig {
+    /** Configuration type discriminator */
+    type: 'postgraphile';
+    /**
+     * Path to PostGraphile preset file
+     *
+     * 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;
+    /** GraphQL endpoint URL (default: '/graphql/') */
+    url?: string;
+    /** Whether to enable GraphiQL IDE (default: true in dev, false in prod) */
+    graphiql?: boolean;
 }
 /**
- * Configuration for the Grafast module
+ * Schema configuration using GraphQL schema files or provider function
+ *
+ * Use this for custom GraphQL schemas with Grafast resolvers.
+ * Schema files (.graphql) are loaded and combined with resolver functions.
+ *
+ * @example
+ * ```typescript
+ * // Using schema files with resolvers
+ * export default defineNuxtConfig({
+ *   modules: ['@stonecrop/nuxt-grafserv'],
+ *   grafserv: {
+ *     type: 'schema',
+ *     schema: 'server/schema/**\/*.graphql',
+ *     resolvers: 'server/resolvers/index.ts',
+ *     url: '/graphql',
+ *     graphiql: true,
+ *   },
+ * })
+ *
+ * // Using schema provider function
+ * export default defineNuxtConfig({
+ *   grafserv: {
+ *     type: 'schema',
+ *     schema: async () => {
+ *       // Return a GraphQLSchema instance
+ *       return myCustomSchema
+ *     },
+ *   },
+ * })
+ * ```
  */
-interface ModuleOptions {
-    /** Path to schema file(s), a schema provider function, or a PostGraphile instance */
-    schema?: string | string[] | SchemaProvider | PostGraphileInstance;
-    /** Path to resolvers file (optional, only needed for .graphql schema files without PostGraphile) */
+interface SchemaConfig {
+    /** Configuration type discriminator */
+    type: 'schema';
+    /**
+     * Path to schema file(s) or schema provider function
+     * - String: Single file path (e.g., 'server/schema/schema.graphql')
+     * - Array: Multiple file paths (e.g., ['server/schema/**\/*.graphql'])
+     * - Function: Returns a GraphQL schema directly
+     */
+    schema: string | string[] | SchemaProvider;
+    /**
+     * Path to resolvers file (optional)
+     * Only needed when using .graphql schema files.
+     * Should export Grafast resolver objects.
+     *
+     * @example 'server/resolvers/index.ts'
+     */
     resolvers?: string;
     /** GraphQL endpoint URL (default: '/graphql/') */
     url?: string;
     /** Whether to enable GraphiQL IDE (default: true in dev, false in prod) */
     graphiql?: boolean;
-    /** Custom Graphile preset to extend (for advanced grafast configuration) */
-    preset?: GraphileConfig.Preset;
 }
+/**
+ * Module configuration - use either PostGraphile preset or custom schema
+ *
+ * @see PostGraphileConfig for PostGraphile integration
+ * @see SchemaConfig for custom schemas with resolvers
+ */
+type ModuleOptions = PostGraphileConfig | SchemaConfig;
 
 declare const module$1: NuxtModule<ModuleOptions>;
 
 export { module$1 as default };
-export type { ModuleOptions, SchemaProvider };
+export type { ModuleOptions, PostGraphileConfig, SchemaConfig, SchemaProvider };

package/dist/module.json

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

package/dist/module.mjs

@@ -1,28 +1,60 @@
-import { join } from 'node:path';
+import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { join } from 'node:path';
 import { useLogger, defineNuxtModule, createResolver } from '@nuxt/kit';
 
 const logger = useLogger("@stonecrop/nuxt-grafserv");
+function validateConfig(options) {
+  if (!options.type) {
+    throw new Error(
+      `[@stonecrop/nuxt-grafserv] Configuration error: 'type' field is required. Must be either 'postgraphile' or 'schema'. 
+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.`
+      );
+    }
+  } else if (options.type === "schema") {
+    const config = options;
+    if (!config.schema) {
+      throw new Error(
+        `[@stonecrop/nuxt-grafserv] Schema configuration error: 'schema' field is required when type is 'schema'. 
+Example: { type: 'schema', schema: 'server/**/*.graphql', resolvers: 'server/resolvers/index.ts' }`
+      );
+    }
+    if ("preset" in config) {
+      logger.warn(
+        `Schema configuration should not include 'preset' field. Use type: 'postgraphile' for PostGraphile preset configuration.`
+      );
+    }
+  } else {
+    throw new Error(
+      `[@stonecrop/nuxt-grafserv] Configuration error: Invalid type '${options.type}'. Must be either 'postgraphile' or 'schema'.`
+    );
+  }
+}
 const module$1 = defineNuxtModule({
   meta: {
     name: "@stonecrop/nuxt-grafserv",
     configKey: "grafserv"
   },
-  defaults: (_nuxt) => ({
-    schema: "server/**/*.graphql",
-    resolvers: void 0,
-    // Optional - not needed for PostGraphile setups
-    url: "/graphql/",
-    graphiql: void 0,
-    // Will default based on dev mode
-    plugins: [],
-    preset: {
-      grafserv: {
-        websockets: false
-      }
-    }
-  }),
+  // No defaults - user must provide complete config with type discriminator
+  // Use undefined instead of {} to ensure user config is passed as-is
   setup(options, nuxt) {
+    if (Object.keys(options).length === 0) {
+      return;
+    }
+    validateConfig(options);
     const { resolve } = createResolver(import.meta.url);
     const require = createRequire(import.meta.url);
     nuxt.hook("nitro:config", (config) => {
@@ -44,41 +76,98 @@ const module$1 = defineNuxtModule({
       logger.info(`Nuxt srcDir: ${nuxt.options.srcDir}`);
       logger.info(`Nuxt rootDir: ${nuxt.options.rootDir}`);
       logger.info(`Grafserv server alias: ${config.alias["#grafserv-server"]}`);
-      const resolverPath = options.resolvers ? resolveForVirtualModule(options.resolvers) : void 0;
-      if (resolverPath) {
-        logger.info(`Resolved resolver path: ${resolverPath}`);
-      } else {
-        logger.info("No resolvers configured (normal for PostGraphile setups)");
-      }
-      let runtimeSchema;
-      if (typeof options.schema === "function" || options.schema && typeof options.schema === "object" && "getSchema" in options.schema) {
-        runtimeSchema = options.schema;
-        logger.info("Using schema provider function or PostGraphile instance");
-      } else if (typeof options.schema === "string") {
-        runtimeSchema = resolveForSchema(options.schema);
-        logger.info(`Resolved schema path: ${runtimeSchema}`);
-      } else if (Array.isArray(options.schema)) {
-        runtimeSchema = options.schema.map((s) => resolveForSchema(s));
-        logger.info(`Resolved schema paths: ${runtimeSchema.join(", ")}`);
-      } else {
-        runtimeSchema = options.schema;
-      }
-      config.runtimeConfig = config.runtimeConfig || {};
-      config.runtimeConfig.grafserv = {
-        ...options,
-        // Pass resolved resolver path for direct import
-        resolversPath: resolverPath,
-        // Pass schema (either resolved paths or function/instance)
-        schema: runtimeSchema
-      };
-      config.virtual = config.virtual || {};
-      if (resolverPath) {
-        config.virtual["#internal/grafserv/resolvers"] = `export { default } from '${resolverPath}'`;
+      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;
+            }
+          }
+          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'
+
+export default {
+  extends: [PostGraphileAmberPreset],
+  pgServices: [makePgService({ connectionString: process.env.DATABASE_URL, schemas: ['public'] })],
+  plugins: [],
+}
+`
+            );
+          }
+        }
+        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.runtimeConfig = config.runtimeConfig || {};
+        config.runtimeConfig.grafserv = {
+          type: "postgraphile",
+          url: options.url || "/graphql/",
+          graphiql: options.graphiql
+        };
+      } else if (options.type === "schema") {
+        logger.info("Using schema configuration");
+        const resolverPath = options.resolvers ? resolveForVirtualModule(options.resolvers) : void 0;
+        if (resolverPath) {
+          logger.info(`Resolved resolver path: ${resolverPath}`);
+        } else {
+          logger.info("No resolvers configured");
+        }
+        let runtimeSchema;
+        if (typeof options.schema === "function") {
+          runtimeSchema = options.schema;
+          logger.info("Using schema provider function");
+        } else if (typeof options.schema === "string") {
+          runtimeSchema = resolveForSchema(options.schema);
+          logger.info(`Resolved schema path: ${runtimeSchema}`);
+        } else if (Array.isArray(options.schema)) {
+          runtimeSchema = options.schema.map((s) => resolveForSchema(s));
+          logger.info(`Resolved schema paths: ${runtimeSchema.join(", ")}`);
+        } else {
+          runtimeSchema = options.schema;
+        }
+        config.runtimeConfig = config.runtimeConfig || {};
+        config.runtimeConfig.grafserv = {
+          type: "schema",
+          schema: runtimeSchema,
+          resolversPath: resolverPath,
+          url: options.url || "/graphql/",
+          graphiql: options.graphiql
+        };
+        config.virtual = config.virtual || {};
+        if (resolverPath) {
+          config.virtual["#internal/grafserv/resolvers"] = `export { default } from '${resolverPath}'`;
+        }
       }
       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"
@@ -86,6 +175,11 @@ const module$1 = defineNuxtModule({
       const grafastPath = require.resolve("grafast");
       config.alias = config.alias || {};
       config.alias["grafast"] = grafastPath;
+      config.typescript = config.typescript || {};
+      config.typescript.tsConfig = config.typescript.tsConfig || {};
+      config.typescript.tsConfig.compilerOptions = config.typescript.tsConfig.compilerOptions || {};
+      config.typescript.tsConfig.compilerOptions.allowImportingTsExtensions = true;
+      config.typescript.tsConfig.compilerOptions.moduleResolution = "bundler";
     });
     nuxt.hook("nitro:config", (config) => {
       config.handlers = config.handlers || [];
@@ -119,8 +213,9 @@ const module$1 = defineNuxtModule({
       let cacheClearing = false;
       nuxt.hook("builder:watch", async (event, path) => {
         const isSchemaFile = path.endsWith(".graphql");
-        const isResolverFile = options.resolvers && path.includes(options.resolvers.replace("./", ""));
-        if (isSchemaFile || isResolverFile) {
+        const isResolverFile = options.type === "schema" && options.resolvers && path.includes(options.resolvers.replace("./", ""));
+        const isPresetFile = options.type === "postgraphile" && path.includes(options.preset.replace("./", ""));
+        if (isSchemaFile || isResolverFile || isPresetFile) {
           if (!cacheClearing) {
             cacheClearing = true;
             try {

package/dist/runtime/handler.js

@@ -13,68 +13,69 @@ async function loadTypeDefsFromFiles(schemaPath) {
   });
   return sources.map((source) => source.document).filter(Boolean);
 }
-function isPostGraphileInstance(value) {
-  return value !== null && typeof value === "object" && "getSchema" in value && typeof value.getSchema === "function";
-}
 async function getSchema(options) {
   if (cachedSchema) {
     return cachedSchema;
   }
   let schema;
-  if (isPostGraphileInstance(options.schema)) {
-    console.debug("[@stonecrop/nuxt-grafserv] Using PostGraphile instance for schema");
+  if (options.type === "postgraphile") {
+    console.debug("[@stonecrop/nuxt-grafserv] Getting schema from PostGraphile instance");
     try {
-      if ("getSchemaResult" in options.schema && typeof options.schema.getSchemaResult === "function") {
-        const result = await options.schema.getSchemaResult();
-        schema = result.schema;
-      } else {
-        schema = await options.schema.getSchema();
-      }
-      console.debug("[@stonecrop/nuxt-grafserv] PostGraphile schema loaded successfully");
+      const { pgl } = await import("#internal/grafserv/pgl");
+      console.debug("[@stonecrop/nuxt-grafserv] Calling pgl.getSchema()");
+      schema = await pgl.getSchema();
+      console.debug("[@stonecrop/nuxt-grafserv] PostGraphile schema retrieved successfully");
     } catch (error) {
-      console.error("[@stonecrop/nuxt-grafserv] Error loading PostGraphile schema:", error);
+      if (error instanceof Error && "code" in error && error.code === "MODULE_NOT_FOUND") {
+        throw new Error(
+          '[@stonecrop/nuxt-grafserv] PostGraphile preset provided but "postgraphile" package not found. Install it with: npm install postgraphile'
+        );
+      }
+      console.error("[@stonecrop/nuxt-grafserv] Error getting PostGraphile schema:", error);
       throw error;
     }
-  } else if (typeof options.schema === "function") {
-    schema = await options.schema();
-  } else if (options.schema) {
-    const typeDefDocs = await loadTypeDefsFromFiles(options.schema);
-    const objects = {};
-    if (options.resolvers) {
-      try {
-        const resolverModule = await import("#internal/grafserv/resolvers");
-        const resolvers = resolverModule.default || resolverModule;
-        console.debug("[@stonecrop/nuxt-grafserv] Resolvers loaded:", Object.keys(resolvers));
-        for (const typeName of Object.keys(resolvers)) {
-          const typeResolvers = resolvers[typeName];
-          if (typeResolvers && typeof typeResolvers === "object" && "plans" in typeResolvers) {
-            objects[typeName] = typeResolvers;
-          } else {
-            objects[typeName] = { plans: typeResolvers };
+  } else if (options.type === "schema") {
+    if (typeof options.schema === "function") {
+      console.debug("[@stonecrop/nuxt-grafserv] Using schema provider function");
+      schema = await options.schema();
+    } else {
+      console.debug("[@stonecrop/nuxt-grafserv] Loading schema from file(s)");
+      const typeDefDocs = await loadTypeDefsFromFiles(options.schema);
+      const objects = {};
+      if (options.resolversPath) {
+        try {
+          const resolverModule = await import("#internal/grafserv/resolvers");
+          const resolvers = resolverModule.default || resolverModule;
+          console.debug("[@stonecrop/nuxt-grafserv] Resolvers loaded:", Object.keys(resolvers));
+          for (const typeName of Object.keys(resolvers)) {
+            const typeResolvers = resolvers[typeName];
+            if (typeResolvers && typeof typeResolvers === "object" && "plans" in typeResolvers) {
+              objects[typeName] = typeResolvers;
+            } else {
+              objects[typeName] = { plans: typeResolvers };
+            }
           }
+        } catch (e) {
+          console.error("[@stonecrop/nuxt-grafserv] Error loading resolvers:", e);
+          throw e;
         }
-      } catch (e) {
-        console.error("[@stonecrop/nuxt-grafserv] Error loading resolvers:", e);
-        console.warn("[@stonecrop/nuxt-grafserv] Continuing without resolvers - this is normal for PostGraphile setups");
+      } else {
+        console.debug("[@stonecrop/nuxt-grafserv] No resolvers specified");
+      }
+      try {
+        schema = makeGrafastSchema({
+          typeDefs: typeDefDocs,
+          objects
+        });
+        console.debug("[@stonecrop/nuxt-grafserv] Grafast schema created successfully");
+      } catch (error) {
+        console.error("[@stonecrop/nuxt-grafserv] Error creating Grafast schema:", error);
+        throw error;
       }
-    } else {
-      console.debug(
-        "[@stonecrop/nuxt-grafserv] No resolvers specified - using schema-only mode (normal for PostGraphile)"
-      );
-    }
-    try {
-      schema = makeGrafastSchema({
-        typeDefs: typeDefDocs,
-        objects
-      });
-      console.debug("[@stonecrop/nuxt-grafserv] Grafast schema created successfully");
-    } catch (error) {
-      console.error("[@stonecrop/nuxt-grafserv] Error creating Grafast schema:", error);
-      throw error;
     }
   } else {
     throw new Error(
-      "[@stonecrop/nuxt-grafserv] No schema provided. Configure schema path, provider function, or PostGraphile instance."
+      `[@stonecrop/nuxt-grafserv] Invalid configuration type: ${options.type}`
     );
   }
   cachedSchema = schema;
@@ -86,7 +87,7 @@ export async function getGrafservInstance(options) {
     return grafservInstance;
   }
   const schema = await getSchema(options);
-  grafservInstance = grafserv({ schema, preset: options.preset });
+  grafservInstance = grafserv({ schema });
   console.log("[@stonecrop/nuxt-grafserv] Grafserv instance created");
   return grafservInstance;
 }

package/dist/types.d.mts

@@ -1,3 +1,3 @@
 export { default } from './module.mjs'
 
-export { type ModuleOptions, type SchemaProvider } from './module.mjs'
+export { type ModuleOptions, type PostGraphileConfig, type SchemaConfig, type SchemaProvider } from './module.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/nuxt-grafserv",
-  "version": "0.7.6",
+  "version": "0.7.9",
   "description": "Pluggable Grafserv GraphQL server as Nuxt Module",
   "license": "MIT",
   "type": "module",
@@ -42,12 +42,10 @@
     "@graphql-tools/wrap": "^11.1.4",
     "grafast": "^1.0.0-rc.4",
     "grafserv": "^1.0.0-rc.4",
-    "graphile-config": "^1.0.0-rc.3",
     "graphql": "^16.12.0",
-    "@stonecrop/graphql-middleware": "0.7.6"
+    "@stonecrop/graphql-middleware": "0.7.9"
   },
   "devDependencies": {
-    "@casl/ability": "^6.8.0",
     "@eslint/js": "^9.39.2",
     "@nuxt/devtools": "^3.1.1",
     "@nuxt/eslint-config": "^1.12.1",
@@ -67,13 +65,13 @@
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
     "vitest": "^4.0.17",
-    "vue-tsc": "^3.2.2",
-    "@stonecrop/casl-middleware": "0.7.6",
-    "@stonecrop/rockfoil": "0.7.6"
+    "vue-tsc": "^3.2.2"
   },
   "peerDependencies": {
-    "@stonecrop/casl-middleware": "0.7.6",
-    "@stonecrop/rockfoil": "0.7.6"
+    "@stonecrop/casl-middleware": "*",
+    "@stonecrop/rockfoil": "*",
+    "postgraphile": "^5.0.0-rc.4",
+    "graphile-config": "^1.0.0-rc.3"
   },
   "peerDependenciesMeta": {
     "@stonecrop/casl-middleware": {
@@ -81,6 +79,12 @@
     },
     "@stonecrop/rockfoil": {
       "optional": true
+    },
+    "postgraphile": {
+      "optional": true
+    },
+    "graphile-config": {
+      "optional": true
     }
   },
   "scripts": {