redwoodjs/redwood
github.com/redwoodjs/redwood ↗ · 4000 files · 27.2 MB · scan capped
[source preview omitted from public export]
Overview
Redwood is a TypeScript/JavaScript framework monorepo for building React applications backed by GraphQL services and Prisma databases. Its distinctive integration spans declarative routing, query lifecycle components called Cells, authentication providers, application generators, background jobs, storage, and development tooling. At commit a7852fb92d0e4ac2bcce1d9a755717ba6cf53ffd, the inspected implementation belongs to Redwood GraphQL; the README separately promotes RedwoodSDK and describes Bighorn capabilities as aspirational.
System map
The repository contains framework packages, generated application templates, integration fixtures, task tooling, and a separate Docusaurus documentation application. Application runtime boundaries divide browser rendering from API execution, with Prisma clients owned by applications. Fastify hosts ordinary functions and a dedicated GraphQL Yoga integration, while a separate handler adapts Yoga to Lambda events. Root scripts coordinate package builds and tests through Nx; package manifests define the published entrypoints.
- The root is a private Yarn 4.6.0 workspace covering framework packages, adapters, authentication providers, CLI packages, and mailer components; create-redwood-rsc-app is explicitly excluded from that workspace list.
- Root build, test, test-ci, and test:types scripts dispatch Nx targets; tsconfig.json references internal, structure, API, server, auth, web, router, testing, prerender, GraphQL, forms, and codemod projects.
- The CLI publishes rw and redwood binaries from dist/index.js; source startup resolves --cwd, RWJS_CWD, or the nearest redwood.toml before loading application environment files.
- The browser entrypoint imports application root and routes through ~redwood aliases, then selects hydrateRoot for existing markup or createRoot for an empty redwood-app element.
- createServer constructs Fastify, creates request-scoped context, registers the generic API adapter, and separately imports compiled GraphQL options to register a Yoga server.
- createGraphQLYoga owns schema assembly and an ordered Envelop plugin chain covering authentication, context, directives, Armor, operation filtering, trusted documents, errors, readiness, and logging.
- Database clients are application-owned: the todo fixture constructs PrismaClient in src/lib/db.js and its service performs queries and mutations against db.todo.
- The server executable defaults NODE_ENV to production and provides combined, api-only, and web-only modes; the Lambda GraphQL wrapper instead translates API Gateway events into yoga.fetch requests.
- The router publishes ESM and CommonJS exports plus react-server conditionals for RSC routing; its dependencies pin a React 19 release candidate.
- Documentation is a separate Docusaurus application with build, serve, start, and deploy scripts; its maintenance instructions identify docs/docs as the editable source.
Feature catalog
The primary users are developers constructing applications with framework commands and runtime components. Inspected features include application creation, development servers, scaffolding, routing, GraphQL Cells, forms, authentication, realtime transport, background jobs, file storage, and mail delivery. The CLI also exposes operational and quality commands and loads Storybook and data-migration plugins. This catalog covers inspected interfaces and documented deployment targets; it is bounded rather than an exhaustive enumeration of the monorepo.
- create-redwood-app checks compatibility, collects target directory and TypeScript/Git preferences, copies the selected template, and conditionally installs dependencies and generates types.
- rw registers build, check, console, deploy, destroy, dev, exec, experimental, generate, info, jobs, lint, prerender, prisma, record, serve, setup, studio, test, ts-to-js, type-check, and upgrade commands.
- rw dev supports selecting api/web sides, artifact generation, and an API debugger port; its handler chooses SPA or streaming-SSR frontend commands.
- The scaffold generator produces Pages, SDL, and Services from a database model, supports nested path/model names, optional tests and Tailwind assets, and rollback configuration.
- Router supports named routes, path and search parameters, redirects, layout Sets, PrivateSets, lazy page loading, and not-found pages; the todo fixture demonstrates public and role-restricted routes.
- Cells expose QUERY, beforeQuery, afterQuery, isEmpty, Loading, Failure, Empty, and Success hooks/components, with a separate suspending factory selected for streaming SSR.
- Form wraps react-hook-form validation and submission, accepts externally created form methods, and exposes GraphQL validation messages through ServerErrorsContext.
- Authentication setup registers Auth0, Azure Active Directory, Clerk, custom auth, dbAuth, Firebase, Netlify, Supabase, and SuperTokens; dbAuth setup offers WebAuthn support.
- DbAuthHandler dispatches login, logout, signup, password recovery/reset, token retrieval, and WebAuthn registration/authentication through an explicit method and HTTP verb table.
- Apollo transport supports multipart uploads, SSE subscriptions/live queries, and persisted query hashes; the Fastify GraphQL adapter exposes GraphQL, health, readiness, and stream routes.
- Background jobs support named queues, delayed scheduling, priorities, configurable workers, retry limits, and configurable deletion of completed or failed jobs.
- FileSystemStorage saves, reads, and removes files, while UrlSigner generates HMAC-signed access URLs with optional expiration.
Data flow
Application configuration determines paths, endpoints, feature flags, and browser-exposed values. Browser queries travel through Cell hooks and Apollo links to Yoga, where SDL fields map to service exports and application-owned Prisma clients. Authentication adds identity to request-scoped context before resolver execution. Jobs use a separate durable path that serializes invocation metadata into database records and later loads compiled code in workers.
- getRawConfig reads and interpolates TOML; getConfig merges the parsed values with defaults such as web port 8910, API port 8911, and /.redwood/functions.
- getEnvVarDefinitions converts configuration into RWJS_ENV endpoint/title/feature values and exposes both explicitly included environment variables and REDWOOD_ENV_ prefixed values to browser expressions.
- NamedCell removes children from query-variable derivation, runs beforeQuery, resolves a static or functional QUERY, and calls the GraphQLHooksProvider useQuery hook.
- Apollo obtains getToken for each operation, adds auth-provider and Bearer authorization headers, and sends operations through upload, SSE, or persisted-operation terminating links.
- The Fastify GraphQL handler supplies a Lambda-shaped event alongside req/reply to yoga.handleNodeRequest, then copies response headers, status, and body into the Fastify reply.
- getAuthenticationContext prefers an auth-provider-bearing cookie over provider-header authorization, runs configured decoders until a payload is returned, and passes the result to getCurrentUser through the auth-context plugin.
- makeMergedSchema combines SDL, directive, subscription, and root definitions; service exports matching field names receive GraphQL args followed by root/context/info.
- The todo mutation passes a body string from React state into createTodo, stores it through db.todo.create, and appends the returned Todo to Apollo's cached list.
- Job scheduling converts job name/path/args, queue, priority, and computed runAt into a payload; PrismaAdapter persists invocation metadata as JSON in the handler column.
- PrismaAdapter selects jobs by priority/runAt, conditionally updates a candidate's lock and attempt count, reloads the record, and deserializes name/path/args for Executor.
- FileSystemStorage turns a File arrayBuffer into a Node Buffer at a configured or overridden path; UrlSigner binds a path and optional expiry into an HMAC and returns a decoded path after validation.
Behavior traces
The investigation followed browser startup, development-command startup, todo creation and persistence, authentication context construction, and background-job execution through their relevant source files. These traces describe source call order, not observed execution. The todo fixture demonstrates the client-to-service data contract but contains a legacy GraphQL bootstrap, so the current server boundary is substantiated separately with test-project and framework sources. Job scheduling and consumption form an additional end-to-end persistence flow.
- Browser startup: index.jsx finds redwood-app → hydrateRoot or createRoot.render → App → FatalErrorBoundary → RedwoodProvider → RedwoodApolloProvider → supplied Routes.
- Routing continuation: Router → LocationProvider → LocationAwareRouter → analyzeRoutes → matchPath/parseSearch → ParamsProvider → WrappedPage → ActiveRouteLoader → LazyRouteComponent.
- Development startup: CLI resolves cwd → sets RWJS_CWD → loadEnvFiles → main/runYargs → registered dev handler dynamically imports devHandler.handler.
- Development continuation: devHandler reads paths/config → checks configured ports → generates Prisma client for the API side → constructs API/web/gen commands → concurrently starts eligible processes; port conflicts exit instead of automatically switching ports.
- Todo creation, client phase: HomePage renders AddTodo → AddTodoControl.handleChange stores input → handleSubmit calls submitTodo and clears input → AddTodo.submitTodo calls createTodo with variables and an optimistic Todo.
- Todo creation, persistence contract: CREATE_TODO selects createTodo(body) → SDL declares that mutation → matching service export calls db.todo.create → SQLite schema supplies an autoincrement id and default off status → Apollo update appends the response to TODOS.
- Current GraphQL startup: test-project creates a dbAuth decoder and passes SDL/services/directives/logger to createGraphQLHandler → createGraphQLYoga → makeMergedSchema → ordered plugin construction → createYoga.
- Authenticated operation: Apollo withToken obtains credentials → authMiddleware sets headers → Yoga auth plugin calls getAuthenticationContext → decoders run → getCurrentUser resolves application identity → extendContext adds currentUser.
- dbAuth login: constructor extracts/decrypts the session → invoke calls init/normalizeRequest → validates method and verb → dispatches login → _verifyUser → configured login.handler → _loginResponse → encrypted session and provider cookies plus csrf-token response header.
- Job submission: JobManager.createScheduler returns a scheduling function → Scheduler.schedule → buildPayload/computeRunAt → adapter.schedule → PrismaAdapter creates the database record with serialized invocation metadata.
- Job consumption: Worker.run → #work → adapter.find → conditional Prisma lock → Executor.perform → loadJob dynamically imports the compiled job → job.perform(...args) → adapter.success or adapter.error/failure.
Testing signals
Tests and CI were inspected, not executed; no passing result is asserted. The inspected framework packages use Vitest, with React Testing Library for component tests and jsdom for browser-oriented packages. Playwright smoke tests and Cypress tutorial CI exercise application integration, while background-job CI has a separate job. Coverage observations are bounded to inspected files: mocked component and worker tests do not establish real network, database-concurrency, provider, or deployment behavior.
- The CLI, router, and GraphQL-server package scripts invoke Vitest; router additionally exposes tstyche through test:types.
- Web and router Vitest configurations use jsdom and exclude __typetests__; their type-test files therefore require a separate validation path.
- createCell.test.tsx uses React Testing Library and Vitest, injecting a custom useQuery through GraphQLHooksProvider rather than contacting a GraphQL server.
- Cell tests explicitly cover Success with populated fields and the case where a later field contains data while the first field is empty.
- lambdaLoader tests set RWJS_CWD to a fixture, reset LAMBDA_FUNCTIONS after each test, and assert function discovery, GraphQL ordering, and warning behavior for missing handlers.
- Auth-context plugin tests mock getAuthenticationContext, assert currentUser enrichment and argument forwarding, and expect getCurrentUser exceptions to propagate.
- Worker.test.ts explicitly mocks Executor and uses MockAdapter; its constructor tests verify option extraction and defaults, without executing real job implementations in those tests.
- Signed URL tests cover expiration rejection, URL-encoded paths, wrong signatures, and signing a different file path.
- GraphQL-server's Vitest configuration forces graphql/index.js and enables fallbackCJS to avoid loading multiple GraphQL module instances.
- Playwright's dev smoke configuration launches a fixture dev server and waits for the API GraphQL endpoint; the shared smoke flow checks blog data, selected CSS, and navigation to About, Contact, and Admin.
- simple-ci runs on pull requests and pushes to next/release branches, invokes yarn test-ci, runs Cypress tutorial specs against a generated app, and includes a background-jobs E2E job.
Risk map
The observations below identify security-sensitive boundaries and correctness hotspots in source, not confirmed vulnerabilities. Authentication and filesystem APIs rely on application configuration and authorization decisions, while dynamic module loading trusts installed or compiled code. Several explicit comments document unfinished behavior, including CSRF validation and job runtime enforcement. Runtime severity, exploitability, and whole-repository coverage remain unverified.
- DbAuthHandler._validateCsrf compares the session token to the request header but is explicitly labeled 'not used yet'; login responses nevertheless issue a CSRF token and encrypted session cookie.
- useRequireAuth catches authentication errors, clears currentUser, and still calls handlerFn; its development warning instructs applications to call requireAuth inside their own handlers.
- The Lambda GraphQL wrapper logs execution exceptions and returns an error body with statusCode 200, accompanied by a source comment saying it should be 500.
- Worker awaits Executor.perform in-process and explicitly leaves maxRuntime timeout enforcement as a TODO requiring a separate process; maxRuntime is currently passed to adapter.find.
- FileSystemStorage.read/remove accept caller-supplied paths directly, and save accepts a path override; these methods contain no local check confining operations to baseDir.
- CLI plugin auto-install defaults to true, and loadPluginPackage can install and dynamically import a configured package; the source also notes installed/requested version mismatch handling is incomplete.
- Vite publishes explicitly included and REDWOOD_ENV_ prefixed environment values in browser definitions and HTML substitutions; naming/configuration determines which values cross the server-to-browser boundary.
- lambdaLoader keys imported functions by basename and assigns them into a shared registry; hypothesis: two discovered files with the same basename could collide, which should be checked before changing discovery rules. (inferred)
- Fastify server setup imports a Babel-generated __rw_graphqlOptions export from the application's compiled GraphQL function; this creates a coupling between the build transform and runtime registration.
- The todo fixture retains a GraphQL bootstrap importing makeServices/makeMergedSchema from @redwoodjs/api and passing schema, whereas test-project uses @redwoodjs/graphql-server with sdls/services/loggerConfig; it should not be treated as a current server setup recipe.
- UrlSigner deliberately supports nonexpiring signatures when no expiresInMs is supplied and compares signatures with ordinary string inequality; expiration and comparison behavior are review points at this access boundary.
- Job loaders join stored jobPath to the compiled jobs directory and dynamically import the result; protecting persisted invocation metadata is consequently part of the worker's code-execution trust boundary.
Extension points
The framework exposes explicit extension seams across commands, transport, schema assembly, authentication, jobs, storage, and mail. Most customization is expressed through configuration objects, exported functions, registries, or adapter classes. Build-time transforms provide some runtime metadata, so extensions must respect the compiler/runtime contract. Plugin ordering and package export conditions are especially consequential boundaries.
- New built-in CLI commands plug into the imports and yargs .command registrations in index.js; PLUGIN_CACHE_BUILTIN is a separate list that must remain aligned.
- CLI plugins are configured under experimental.cli.plugins, expose plugin.commands, and are registered directly for @redwoodjs or beneath third-party namespaces.
- createServer accepts configureApiServer, Fastify options, and discovery globs; the generic API plugin executes the custom configuration callback before loading functions.
- GraphQL applications extend execution through extraPlugins, custom context, directives, schemaOptions, and subscriptions; createGraphQLYoga inserts extra plugins into its ordered chain.
- Named service exports implement Query/Mutation/Subscription fields, while other object types use an exported object named after the GraphQL type; explicit SDL resolvers take precedence over inferred service functions.
- Authentication accepts a Decoder or ordered Decoder array and an application getCurrentUser callback, allowing provider verification and application identity lookup to be composed.
- GraphQLHooksProvider is the Cell-compatible client seam, while RedwoodApolloProvider accepts custom cache, cacheConfig, HTTP configuration, fragments, and an ApolloLink or link factory.
- Router accepts custom paramTypes and useAuth; route Sets supply wrapper components, and PrivateSets add AuthenticatedRoute around the wrapper chain.
- JobManager accepts adapter, queue, logger, and worker configurations; createJob defines perform behavior, while name/path are supplied by the build process.
- FileSystemStorage subclasses BaseStorageAdapter and overrides save/read/remove; PrismaAdapter subclasses the jobs BaseAdapter and implements persistence operations.
- Mailer configuration supplies named handler and renderer registries with defaults and per-send overrides; Mailer.send delegates rendering and delivery through those interfaces.
- Trusted document integration accepts a hash-to-operation store and a configurable allowArbitraryOperations policy, with a built-in exception for the precise Redwood current-user query.
Contributor handoff
Begin with the owning package and follow the application's configuration, compiler, and runtime boundaries before editing. The repository contains current implementations alongside legacy fixtures and documentation that can describe different development epochs. Tests and CI were inspected, not executed, and this inventory is bounded; future agents must obtain actual check results under appropriate execution authority. Keep changes small and account for generated metadata, browser environment exposure, and interfaces shared across deployment modes.
- Use the root's Yarn 4.6.0 package-manager declaration and existing Nx scripts as the tooling baseline; the empty-project fixture's Node 14–16/Yarn 1 constraints describe that fixture rather than the root.
- For CLI changes, read index.js, the command module, and its handler first; the dev command illustrates lazy handler import and a documented hidden forwarding option.
- For Cell changes, inspect createCell.tsx together with GraphQLHooksProvider-based tests and Apollo defaults, since variables, lifecycle rendering, and cache-and-network behavior cross those boundaries.
- For GraphQL changes, read both createGraphQLHandler and the Fastify GraphQL plugin: Lambda uses yoga.fetch, while the server uses handleNodeRequest and can add realtime plugins.
- Use __fixtures__/test-project/api/src/functions/graphql.ts as the inspected current bootstrap reference; compare older example-todo-main imports before copying them.
- Package export changes need ESM/CommonJS/react-server consideration, and GraphQL test setup contains a deliberate single-module-instance workaround that should not be removed casually.
- Under later execution authorization, start with the owning workspace's existing test script, such as yarn workspace @redwoodjs/cli test or yarn workspace @redwoodjs/graphql-server test; root yarn test is the broader Nx suite.
- Tests and CI were inspected, not executed in this briefing; the active workflow's test-ci, tutorial Cypress, and background-job E2E commands are configured checks, not evidence of successful runs.
- Documentation edits belong in docs/docs rather than generated versioned documentation; the README's separate SDK promotion and aspirational Bighorn section require care when describing implemented capabilities.
- Framework-to-project synchronization is materially stateful: CONTRIBUTING documents rebuilding, copying dependencies, running installation, copying packages, and watching changes, controlled by RWFW_PATH.
- Read Scheduler, PrismaAdapter, Worker, Executor, and loaders before altering jobs: persisted handler JSON, conditional locking, retries, and compiled module paths jointly define the execution contract.
- Avoid exploratory CLI execution during source-only audits: CLI startup loads application environment files and starts telemetry unless disabled, while plugin loading can install packages and write commandCache.json.
Languages
| Language | Files | Share of source |
|---|---|---|
| Markdown | 2125 | docs/config |
| TypeScript | 1604 | 67% |
| JavaScript | 739 | 31% |
| JSON | 344 | docs/config |
| TOML | 52 | 2% |
| CSS | 44 | docs/config |
| HTML | 34 | docs/config |
| YAML | 31 | docs/config |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (1469 files)
Repository structure
| Top-level path | Files |
|---|---|
docs/ | 1470 |
packages/ | 1469 |
__fixtures__/ | 728 |
tasks/ | 195 |
.github/ | 59 |
.changesets/ | 54 |
.ona/ | 1 |
.devcontainer/ | 1 |
Docs found: CONTRIBUTING.mdREADME.mddocs/README.mddocs/docs/a11y.mddocs/docs/app-configuration-redwood-toml.mddocs/docs/assets-and-files.mddocs/docs/auth/auth0.mddocs/docs/auth/azure.mddocs/docs/auth/clerk.mddocs/docs/auth/custom.md
Package
package.json — , 78 declared dependencies.
@actions/cache@actions/core@actions/exec@actions/glob@babel/cli@babel/core@babel/generator@babel/node@babel/plugin-proposal-decorators@babel/plugin-transform-class-properties@babel/plugin-transform-nullish-coalescing-operator@babel/plugin-transform-private-methods
CI & config entrypoints
README.md— Repository readme.github/workflows/simple-ci.yml— GitHub Actions workflow__fixtures__/empty-project/web/src/App.tsx— React root__fixtures__/example-todo-main/web/vite.config.ts— Vite config__fixtures__/fragment-test-project/web/src/App.tsx— React root__fixtures__/fragment-test-project/web/vite.config.ts— Vite config__fixtures__/rsc-caching/web/src/App.tsx— React root__fixtures__/rsc-caching/web/vite.config.ts— Vite config__fixtures__/test-project-rsa/web/src/App.tsx— React root__fixtures__/test-project-rsa/web/vite.config.ts— Vite config
Structural health signals
Average score 7.4/10 across 96 analyzed source files; 16 hotspots surfaced.
packages/auth-providers/dbAuth/api/src/DbAuthHandler.ts— 1592 lines, score 4.7 (Large file, Deep nesting)tasks/test-project/tui-tasks.ts— 1036 lines, score 5 (Large file, Deep nesting)packages/auth-providers/dbAuth/api/src/__tests__/DbAuthHandler.fetch.test.js— 1726 lines, score 5.2 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
a7852fb92d0e2025-12-13 — Fix docs.3ff0bf08e1bf2025-11-15 — Update testing.md (#12092)5358368bfae42025-11-15 — Simplify CI. (#12109)d0fcf20713332025-10-13 — chore(deps): Bump form-data to fix security alerts (#12103)6ccff00166fe2025-10-13 — chore(deps): update dependency rollup to v4.46.2 (#12075)