{"id":13250,"library":"grafserv","title":"Grafserv","description":"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).","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/graphile/crystal","tags":["javascript","server","grafast","graphql","graphile","fast","graphite","typescript"],"install":[{"cmd":"npm install grafserv","lang":"bash","label":"npm"},{"cmd":"yarn add grafserv","lang":"bash","label":"yarn"},{"cmd":"pnpm add grafserv","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for extending GraphQL execution via plugins.","package":"@envelop/core","optional":false},{"reason":"Provides a WHATWG-compatible server interface for various environments.","package":"@whatwg-node/server","optional":false},{"reason":"The core GraphQL execution planning and optimization engine, fundamental to grafserv's operation.","package":"grafast","optional":false},{"reason":"For managing configuration within the Graphile ecosystem.","package":"graphile-config","optional":false},{"reason":"The standard GraphQL.js library.","package":"graphql","optional":false},{"reason":"An optional HTTP server adapter for h3-compatible frameworks.","package":"h3","optional":true},{"reason":"An optional HTTP server adapter for the Hono web framework.","package":"hono","optional":true},{"reason":"Required for WebSocket-based GraphQL subscriptions.","package":"ws","optional":false}],"imports":[{"note":"Grafserv is an ESM-only package and requires Node.js v22+. CommonJS `require()` is not supported.","wrong":"const createGrafserv = require('grafserv');","symbol":"createGrafserv","correct":"import { createGrafserv } from 'grafserv';"},{"note":"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'.","wrong":"import { makeHonoHandler } from 'grafserv';","symbol":"makeHonoHandler","correct":"import { makeHonoHandler } from 'grafserv/hono';"},{"note":"Always use `import type` for type-only imports to prevent accidental runtime imports and ensure optimal bundle size in TypeScript projects.","wrong":"import { GrafservOptions } from 'grafserv';","symbol":"GrafservOptions","correct":"import type { GrafservOptions } from 'grafserv';"}],"quickstart":{"code":"import { createGrafserv } from 'grafserv';\nimport { makeHonoHandler } from 'grafserv/hono';\nimport { buildSchema } from 'graphql';\nimport { Hono } from 'hono';\n\n// 1. Define a simple GraphQL schema\nconst schema = buildSchema(`\n  type Query {\n    hello: String\n    greeting(name: String!): String\n  }\n`);\n\n// 2. Implement resolvers (Grafast-style execution is assumed by grafserv,\n// but for a quickstart, we can provide a simple rootValue for buildSchema)\nconst rootValue = {\n  hello: () => 'Hello, Grafserv!',\n  greeting: ({ name }: { name: string }) => `Hello, ${name}!`,\n};\n\n// 3. Create a Grafserv instance\nconst grafserv = createGrafserv({\n  schema,\n  // Grafast automatically hooks into the schema for optimized execution.\n  // For this simple schema, the rootValue is sufficient for demonstration.\n  // In a real application, you'd integrate with Grafast steps.\n  rootValue,\n  // Optional: enable GraphiQL interface for exploration\n  graphiql: true,\n});\n\n// 4. Create a Hono app instance\nconst app = new Hono();\n\n// 5. Integrate Grafserv's Hono handler. This handles GraphQL requests and GraphiQL.\napp.all('/graphql', makeHonoHandler(grafserv));\n\n// 6. Start the Hono server\nconst port = process.env.PORT ?? 4000;\napp.listen(port, () => {\n  console.log(`🚀 GraphQL server running at http://localhost:${port}/graphql`);\n  console.log(`Explore with GraphiQL at http://localhost:${port}/graphql`);\n});","lang":"typescript","description":"Demonstrates how to set up a basic GraphQL server using grafserv with Hono, define a simple schema, and enable the GraphiQL interface."},"warnings":[{"fix":"Ensure your project's `package.json` specifies `\"type\": \"module\"` or use `.mjs` file extensions. Update Node.js to v22+.","message":"Grafserv requires Node.js v22 or later and is exclusively an ECMAScript Module (ESM). It does not support CommonJS (require()).","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Familiarize yourself with the Grafast documentation (grafast.org) and the new Graphile v5 architecture. Migration from PostGraphile v4 requires significant refactoring.","message":"Grafserv 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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Carefully install all required peer dependencies listed in `package.json`. Always ensure compatible versions are used to avoid conflicts.","message":"Grafserv 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to `require('grafserv')` or any of its subpaths in a CommonJS environment. Grafserv is an ESM-only package.","error":"ERR_REQUIRE_ESM"},{"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.","cause":"The GraphQL schema provided to `createGrafserv` (or `buildSchema`) is empty, malformed, or does not contain any valid type definitions.","error":"TypeError: Cannot create a GraphQLSchema from an AST that contains no type definitions."},{"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.","cause":"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.","error":"Cannot find module 'grafserv/hono' or its corresponding type declarations."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}