Registry / web-framework / grafserv

grafserv

JSON →
library1.0.0jsnpmunverified

Grafserv is a highly optimized and performant GraphQL server for Node.js, fundamentally powered by the Grafast execution engine. It is a core component of the Graphile Crystal ecosystem (PostGraphile v5), representing a significant architectural shift from prior Graphile implementations. Currently at version 1.0.0, Grafserv is actively developed with frequent patch releases across the Graphile monorepo, indicating a stable and evolving platform. Its key differentiators include its tight integration with Grafast for advanced query planning and execution optimization, offering superior performance compared to traditional resolver-based GraphQL servers. Grafserv provides flexible integration with various Node.js HTTP frameworks such as Hono, H3, and @whatwg-node/server, allowing developers to choose their preferred server environment while leveraging Grafast's capabilities. It's designed for modern Node.js environments, specifically requiring Node.js v22+ and operating exclusively as an ECMAScript Module (ESM).

npm install grafserv
INSTALL
IMPORT
SIG · GRAFSERV
G
grafserv
web-frameworkjavascriptv1.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createGrafserv
import { createGrafserv } from 'grafserv';
const createGrafserv = require('grafserv');
Grafserv is an ESM-only package and requires Node.js v22+. CommonJS `require()` is not supported.
makeHonoHandler
import { makeHonoHandler } from 'grafserv/hono';
import { makeHonoHandler } from 'grafserv';
Handlers for specific web frameworks (e.g., Hono, H3) are imported from dedicated subpaths to enable tree-shaking and avoid unnecessary dependencies. Do not import directly from 'grafserv'.
GrafservOptions
import type { GrafservOptions } from 'grafserv';
import { GrafservOptions } from 'grafserv';
Always use `import type` for type-only imports to prevent accidental runtime imports and ensure optimal bundle size in TypeScript projects.

Demonstrates how to set up a basic GraphQL server using grafserv with Hono, define a simple schema, and enable the GraphiQL interface.

import { createGrafserv } from 'grafserv'; import { makeHonoHandler } from 'grafserv/hono'; import { buildSchema } from 'graphql'; import { Hono } from 'hono'; // 1. Define a simple GraphQL schema const schema = buildSchema(` type Query { hello: String greeting(name: String!): String } `); // 2. Implement resolvers (Grafast-style execution is assumed by grafserv, // but for a quickstart, we can provide a simple rootValue for buildSchema) const rootValue = { hello: () => 'Hello, Grafserv!', greeting: ({ name }: { name: string }) => `Hello, ${name}!`, }; // 3. Create a Grafserv instance const grafserv = createGrafserv({ schema, // Grafast automatically hooks into the schema for optimized execution. // For this simple schema, the rootValue is sufficient for demonstration. // In a real application, you'd integrate with Grafast steps. rootValue, // Optional: enable GraphiQL interface for exploration graphiql: true, }); // 4. Create a Hono app instance const app = new Hono(); // 5. Integrate Grafserv's Hono handler. This handles GraphQL requests and GraphiQL. app.all('/graphql', makeHonoHandler(grafserv)); // 6. Start the Hono server const port = process.env.PORT ?? 4000; app.listen(port, () => { console.log(`🚀 GraphQL server running at http://localhost:${port}/graphql`); console.log(`Explore with GraphiQL at http://localhost:${port}/graphql`); });
Debug
Known issues
breakingGrafserv requires Node.js v22 or later and is exclusively an ECMAScript Module (ESM). It does not support CommonJS (require()).
fix
Ensure your project's `package.json` specifies `"type": "module"` or use `.mjs` file extensions. Update Node.js to v22+.
affects: >=1.0.0
breakingGrafserv is part of the Graphile Crystal (PostGraphile v5) ecosystem, which represents a fundamental shift in GraphQL server architecture, moving from traditional resolver functions to a Grafast-powered execution plan. Existing PostGraphile v4 concepts and many GraphQL server patterns are not directly compatible.
fix
Familiarize yourself with the Grafast documentation (grafast.org) and the new Graphile v5 architecture. Migration from PostGraphile v4 requires significant refactoring.
affects: >=1.0.0
gotchaGrafserv relies heavily on peer dependencies for its underlying GraphQL implementation, Grafast execution engine, and HTTP server adapters. Mismatched or missing peer dependencies can lead to runtime errors or unexpected behavior.
fix
Carefully install all required peer dependencies listed in `package.json`. Always ensure compatible versions are used to avoid conflicts.
affects: >=1.0.0
Errors
Common errors & fixes
ERR_REQUIRE_ESM
Attempting to `require('grafserv')` or any of its subpaths in a CommonJS environment. Grafserv is an ESM-only package.
fix
Convert your project to use ES modules by setting `"type": "module"` in `package.json` or by using `.mjs` file extensions. Use `import` statements instead of `require()` for Grafserv.
TypeError: Cannot create a GraphQLSchema from an AST that contains no type definitions.
The GraphQL schema provided to `createGrafserv` (or `buildSchema`) is empty, malformed, or does not contain any valid type definitions.
fix
Ensure the `schema` string or `GraphQLSchema` object passed to `createGrafserv` contains at least a `Query` type with some fields (e.g., `type Query { hello: String }`). Double-check schema syntax.
Cannot find module 'grafserv/hono' or its corresponding type declarations.
The specific HTTP handler module (e.g., `grafserv/hono`, `grafserv/h3`) is not found. This can be due to an incorrect import path, a missing peer dependency for the adapter, or build/bundler configuration issues.
fix
Double-check the import path for the specific handler (e.g., `import { makeHonoHandler } from 'grafserv/hono';`). Ensure `grafserv` and the relevant adapter's peer dependency (e.g., `hono`) are correctly installed.
Upgrade
Version history
1.0.0latest on npm
Audit
Dependencies
@envelop/corerequiredUsed for extending GraphQL execution via plugins.
@whatwg-node/serverrequiredProvides a WHATWG-compatible server interface for various environments.
grafastrequiredThe core GraphQL execution planning and optimization engine, fundamental to grafserv's operation.
graphile-configrequiredFor managing configuration within the Graphile ecosystem.
graphqlrequiredThe standard GraphQL.js library.
h3optionalAn optional HTTP server adapter for h3-compatible frameworks.
honooptionalAn optional HTTP server adapter for the Hono web framework.
wsrequiredRequired for WebSocket-based GraphQL subscriptions.
Agent activity
22 hits · last 30 days
node
22
Resources
grafserv — npm install grafserv · libregistry