Healthy — Healthy across all four use cases

• Last commit 5d ago
• 16 active contributors
• MIT licensed
• Tests present
• ⚠ Scorecard: known vulnerabilities detected (scored 0/10 by OpenSSF)
• ⚠ Concentrated ownership — top contributor handles 50% of recent commits
• ⚠ No CI workflows detected

Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against OpenSSF Scorecard

RedwoodJS GraphQL is the backend/API framework for the Redwood full-stack JavaScript framework, providing opinionated GraphQL server infrastructure with built-in auth, caching, logging, and serverless deployment support. It includes packages/api (core GraphQL utilities), packages/api-server (Fastify-based HTTP server with watch/build management), and integrates JWT verification, Redis/Memcached caching, and AWS Lambda request handling. Monorepo split into packages/api (core library: auth verifiers, cache clients, logger, event system, errors) and packages/api-server (HTTP server: Fastify setup, CLI config, plugin system, request handlers). Fastify plugins (packages/api-server/src/plugins/) for GraphQL and API setup. Auth uses pluggable verifier pattern (base64Sha256, JWT, secretKey, skip). Cache abstracts multiple backends (InMemory, Redis, Memcached) via BaseClient.

LLM-derived; treat as a starting point, not verified fact.

Full-stack JavaScript developers building Redwood applications who need a production-ready GraphQL backend with integrated authentication, caching strategies, and multi-environment support (dev, serverless, traditional hosting). Also relevant for framework maintainers contributing to Redwood's backend ecosystem.

LLM-derived; treat as a starting point, not verified fact.

Actively developed as part of the Redwood framework ecosystem (250+ contributors). The codebase is substantial (3.8MB TypeScript) with organized plugin architecture and multiple production concerns addressed (auth verifiers, logging formatters, request handlers). Currently in 'Bighorn Epoch' development phase—not yet a stable release, so treat as actively evolving rather than locked-down stable.

Standard open source risks apply.

LLM-derived; treat as a starting point, not verified fact.

Framework is transitioning to Bighorn epoch with emphasis on Cloudflare Workers / RedwoodSDK mentioned prominently in README. Current codebase reflects mature GraphQL API layer but README signals strategic pivot toward edge computing. Activity appears focused on maintaining existing auth/cache/server infrastructure while parent project explores new deployment targets.

LLM-derived; treat as a starting point, not verified fact.

Clone and install: git clone https://github.com/redwoodjs/graphql.git && cd graphql && npm install (or yarn). No direct 'npm start' for this monorepo—it's consumed as packages. To develop locally: npm run dev in packages/api-server (inferred from buildManager.ts watching). For integration: this repo is typically consumed via @redwoodjs/api and @redwoodjs/api-server npm packages.

Daily commands: Dev server: Start in packages/api-server with npm run dev (inferred from watch.ts and serverManager.ts). This triggers buildManager to compile TypeScript and serverManager to start Fastify. API CLI: npm run redwood api dev (from packages/api/src/bins/redwood.ts). No monorepo-level start script visible—you must cd into specific packages.

• packages/api-server/src/createServer.ts — Core Fastify server initialization—entry point for all HTTP request handling and GraphQL/API plugin setup.
• packages/api-server/src/plugins/graphql.ts — GraphQL server plugin configuration—establishes Apollo Server integration and request/response lifecycle.
• packages/api/src/index.ts — API package main export—defines public API for serverless functions, auth, caching, and utilities.
• packages/auth/src/AuthProvider/AuthProvider.tsx — Client-side authentication context provider—manages user state, login/logout, and auth hooks across the app.
• packages/api/src/cache/index.ts — Cache abstraction layer—supports Redis, Memcached, and in-memory backends for multi-backend caching strategy.
• packages/api-server/src/bin.ts — CLI entry point for the API server—parses arguments and launches development or production server modes.
• packages/babel-config/src/index.ts — Babel configuration factory—applies Redwood-specific transpilation plugins for cells, imports, and routing.

• Fastify Server (Fastify, Node.js) — Receives HTTP requests, orchestrates middleware/plugins, and sends responses.
  • Failure mode: Server crashes on plugin initialization or unhandled exception; all requests fail.
• GraphQL Plugin (Apollo Server, GraphQL) — Parses GraphQL queries, validates against merged schema, and invokes matching resolvers.
  • Failure mode: Invalid schema or resolver error; returns 400 or 500 response with error details.
• Auth Middleware (JWT verifiers, crypto) — Extracts and verifies JWT/token from request headers, populates user context.
  • Failure mode: Invalid token or verification failure; request rejected with 401 Unauthorized.
• Cache Layer (Redis, Memcached, in-memory store) — Stores and retrieves cached query results or function outputs based on backend strategy.
  • Failure mode: Cache miss or backend unavailable; falls back to compute (no data loss).
• Babel Plugin System (Babel, AST manipulation) — Transforms Redwood-specific syntax into standard JavaScript at compile time.
  • Failure mode: Syntax error or misconfigured plugin; build fails, preventing deployment.
• API Function Router (Node.js, file system loader) — Maps incoming HTTP requests to serverless function handlers; executes and returns results.
  • Failure mode: Function not found or runtime error; returns 404 or 500 with error details.

• HTTP Client (Browser/CLI) → Fastify Server — POST request with GraphQL query/mutation and optional Authorization header.
• Fastify Server → Auth Middleware — Extracts JWT token from Authorization header and verifies ownership/permissions.
• Auth Middleware → GraphQL Plugin — Attached authenticated user context (subject, claims) to request object.
• GraphQL Plugin → Resolver Functions — Parses query, validates schema, and invokes matching resolver with user context.
• Resolver Functions → Cache Layer — Queries cache first; stores result after execution for future lookups.
• Resolver → undefined — undefined

Add a new GraphQL resolver function

1. Create a new file in packages/api/src/functions/graphql/ with your resolver logic, exporting a named function matching your GraphQL field name. (packages/api/src/functions/graphql/[functionName].ts)
2. Define your SDL/schema in the same directory as [functionName].sdl.ts; Redwood auto-discovers and merges SDL files. (packages/api/src/functions/graphql/[functionName].sdl.ts)
3. Verify the resolver is exported from packages/api/src/index.ts if publishing the function as part of the public API. (packages/api/src/index.ts)
4. Restart the dev server or use hot-reload; the GraphQL plugin will automatically register the new resolver. (packages/api-server/src/plugins/graphql.ts)

Add custom authentication verifier

1. Create a new verifier class extending BaseAuthVerifier in packages/api/src/auth/verifiers/, implementing verify(token) method. (packages/api/src/auth/verifiers/[customVerifier].ts)
2. Export your verifier from packages/api/src/auth/verifiers/index.ts to make it discoverable. (packages/api/src/auth/verifiers/index.ts)
3. Configure auth in your API server via createServer options, selecting your verifier strategy in the auth plugin setup. (packages/api-server/src/createServer.ts)
4. Test by sending requests with your custom token format; the auth middleware will invoke your verify() logic. (packages/api/src/auth/index.ts)

Add a new cache backend

1. Create a new client class extending BaseClient in packages/api/src/cache/clients/[BackendName]Client.ts, implementing get/set/del/flush methods. (packages/api/src/cache/clients/[BackendName]Client.ts)
2. Export your client from packages/api/src/cache/clients/index.ts and register it in the cache factory. (packages/api/src/cache/index.ts)
3. Create a connection/initialization module for your backend (e.g., connection pooling, credential handling). (packages/api/src/cache/clients/[BackendName]Connection.ts)
4. Use the cache via createCache({ backend: '[BackendName]' }) in your API functions or middleware. (packages/api/src/index.ts)

Add a new Babel transformation plugin

1. Create a plugin file in packages/babel-config/src/plugins/babel-plugin-redwood-[feature].ts, exporting a default plugin factory. (packages/babel-config/src/plugins/babel-plugin-redwood-[feature].ts)
2. Import and register your plugin in packages/babel-config/src/api.ts (for API-side) or packages/babel-config/src/web.ts (for web-side). (packages/babel-config/src/index.ts)
3. Write visitor methods to transform your target AST nodes (e.g., Import, CallExpression, FunctionDeclaration). (packages/babel-config/src/plugins/babel-plugin-redwood-[feature].ts)
4. Test your plugin with sample code; restart the dev server to apply the transformation. (packages/babel-config/src/common.ts)

• Fastify — High-performance HTTP server with plugin ecosystem; ideal for both traditional and serverless API serving.
• Apollo Server — Industry-standard GraphQL implementation with rich ecosystem, middleware support, and schema merging capabilities.
• Babel plugins — Compile-time code generation for Redwood-specific syntax (cells, auto-imports, routes) without runtime overhead.
• JWT + multi-strategy verifiers — Flexible authentication allowing pluggable verification (SHA, Base64, custom schemes) without vendor lock-in.
• Multi-backend cache abstraction — Supports Redis, Memcached, and in-memory backends; enables environment-specific optimization (dev vs. prod).

• Plugin-based architecture for Fastify

  • Why: Allows loose coupling between GraphQL, API routes, and custom middleware; simplifies testing and feature toggling.
  • Consequence: Plugin ordering and initialization complexity; middleware registration must be explicit.

• Compile-time Babel transformation instead of runtime interpretation

  • Why: Zero runtime overhead; all code generation happens during build, improving performance.
  • Consequence: Requires full rebuild on code changes; harder to debug generated code.

• Cache abstraction with pluggable backends

  • Why: Avoids vendor lock-in; same code works with Redis, Memcached, or in-memory without changes.
  • Consequence: Added abstraction layer; some backend-specific optimizations cannot be exposed without custom client.

• Server-side JWT verification via verifiers instead of library defaults

  • Why: Allows custom token formats and multi-strategy fallback without rewriting auth logic.
  • Consequence: Security depends on correct verifier implementation; easy to misconfigure.

• Does not provide built-in database ORM—relies on user-provided data layer (Prisma, TypeORM, etc.).
• Does not handle frontend rendering or SSR—frontend is separate full-stack concern.
• Does not implement session management—clients must manage JWT storage and refresh token rotation.
• Does not provide real-time subscriptions natively—WebSocket support must be added via plugins.
• Does not enforce GraphQL subscriptions or live queries—standard query/mutation-only by default.

No visible GraphQL schema loading code: graphql.ts registers the plugin but schema origin (file path, validation) is likely in consuming Redwood app, not here—assume you must provide context.schema. CLI vs package consumption mismatch: packages/api/src/bins/ has CLI entry points but package is mostly a library; test locally via npm link or workspace. Auth verifier choice is global: once a verifier is selected (via config), it applies to all requests—no per-route override visible. Cache client selection at startup: InMemoryClient selected if no Redis/Memcached configured—watch for silent fallback on misconfiguration. Monorepo import paths: cross-package imports use @redwoodjs/api, not relative paths—ensure npm/yarn hoisting is set up correctly. Fastify plugin order matters: graphql plugin is loaded after base middleware; adding plugins in wrong order may bypass auth or logging.

• Pluggable Verifier Pattern — Auth in this repo is not monolithic—packages/api/src/auth/verifiers/ shows how to swap HMAC, JWT, timestamp, and skip verifiers at runtime. Understanding this pattern is key to securing or bypassing auth in tests.
• Cache-Aside Pattern — packages/api/src/cache/clients/ implements the cache-aside (lazy-load) pattern where application code checks cache, misses, fetches from origin, and populates cache. Critical for understanding Redwood's cache semantics.
• Fastify Plugin System — All server functionality (GraphQL, API routes, auth, logging) is wired via Fastify plugins in packages/api-server/src/plugins/. Modifying server behavior means understanding plugin hooks and decorators.
• JWT (JSON Web Tokens) — packages/api/src/auth/parseJWT.ts and jwtVerifier.ts are core to stateless auth; understanding JWT claims, expiry, and verification is mandatory for securing Redwood APIs.
• HMAC (Hash-based Message Authentication Code) — packages/api/src/auth/verifiers/ includes SHA1 and SHA256 HMAC verifiers for symmetric key signing. Important for webhook authentication and non-JWT auth flows.
• Monorepo Workspace Pattern — This repo is a monorepo (packages/api, packages/api-server, packages/*/src) managed by npm/yarn workspaces. Understanding cross-package dependencies and import paths (@redwoodjs/api) is essential for local development.
• Adapter Pattern for Serverless — packages/api-server/src/requestHandlers/awsLambdaFastify.ts adapts Fastify (Node.js HTTP) to AWS Lambda events/context. This abstraction layer allows Redwood to run on multiple serverless platforms.

• redwoodjs/redwood — Parent monorepo housing the full Redwood framework; this graphql repo is the extracted backend for Redwood apps
• redwoodjs/sdk — New Cloudflare Workers framework mentioned in README as strategic future; will eventually supersede or complement this GraphQL layer
• apollographql/apollo-server — The underlying GraphQL server implementation (likely peer dependency); understanding Apollo's plugin system clarifies redwood/graphql's plugin architecture
• fastify/fastify — HTTP server framework powering packages/api-server; Fastify plugin API directly used in createServer.ts and plugins/
• hashrocket/graphql-ruby — Alternative GraphQL backend (Ruby); useful for comparing architectural patterns if evaluating GraphQL server design trade-offs

• Add TypeScript test suite for packages/api/src/auth/verifiers/—currently no visible .test.ts files for base64Sha256Verifier, jwtVerifier, or secretKeyVerifier. Write unit tests validating each verifier rejects malformed tokens and accepts valid ones.
• Document the cache configuration flow in packages/api/src/cache/README.md—similar to packages/api-server/src/logFormatter/README.md pattern. Explain how Redis/Memcached clients are selected, how to add a custom cache backend, and include a quick-start example.
• Extract and document serverless request handler interface in packages/api-server/src/requestHandlers/—currently only awsLambdaFastify.ts exists. Create a HANDLER_CONTRACT.md explaining how to add Google Cloud Functions, Azure Functions, or Netlify request handlers by extending the pattern.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub