keystonejs/keystone
github.com/keystonejs/keystone ↗ · 1474 files · 5.6 MB
--- Keystone helps you build faster and scale further than any other CMS or App Framework.
Overview
Keystone is a TypeScript CMS and application backend framework for developers who define data models in code and give editors a generated management interface. List and field definitions produce GraphQL APIs, Prisma database schemas, typed server contexts, and a Next.js Admin UI, with configurable authentication, access control, hooks, actions, and asset storage. This brief describes the source inspected at commit 1a8f2b7fae39ea5dac415745caea4f766109e669; the investigation is bounded and no repository code or tests were executed.
System map
The repository packages a configurable backend framework alongside authentication, document editing, Cloudinary integration, examples, and a documentation website. Core separates configuration/schema construction, Prisma-backed execution, Express/Apollo transport, and a generated Next.js Admin UI. Package publication and static website deployment have separate GitHub Actions workflows.
- The private monorepo pins pnpm 11.21.0; its workspace includes packages, examples, documentation, multiple test workspaces, and prisma-utils, with shared dependency versions in the catalog.
- The keystone executable imports @keystone-6/core/scripts; main() passes process.cwd() and CLI arguments to cli(), which dispatches dev, build, start, postinstall, and telemetry.
- Core's public index exports config, list, group, action, and GraphQL schema builders; its package exposes separate context, session, fields, testing, and Admin UI entrypoints.
- createContextSystem() initializes lists and Admin metadata, builds public/internal schemas, creates or accepts a Prisma client, and exposes connect()/disconnect(); connect() invokes db.onConnect after $connect().
- createExpressServer() owns the HTTP server and Apollo transport; Admin UI middleware is attached separately after Next preparation, allowing UI-disabled deployments.
- config() accepts PostgreSQL, SQLite, or MySQL; applications supply prismaClientOptions(), while schema/client/type paths and Prisma extension callbacks are normalized centrally.
- Root build uses Preconstruct, lint uses oxlint, types use tsc, document tests use Vitest, and tests2 uses node:test; prisma-utils separately verifies generated filter material.
- Packages publish through Changesets after pnpm build; the docs build validates links and generates llms material, while production website CI enables STATIC_EXPORT and deploys docs/out to GitHub Pages.
Feature catalog
Keystone exposes generated CRUD APIs and an editor-facing interface from the same configured lists. Built-in fields cover scalar, relationship, password, and asset data, with a separate rich-document package. Authentication, custom actions, storage integrations, and project scaffolding provide additional application capabilities.
- Each generated list context exposes findOne, findMany, count, createOne/createMany, updateOne/updateMany, and deleteOne/deleteMany; omitted GraphQL operations become unsupported context calls.
- writeAdminFiles() generates home, no-access, list, item, and create pages; CreateItemPage submits the configured fields and navigates to the new item's route.
- ListPage supports field filters, search, sorting, selectable columns, pagination, and custom actions; list preferences are restored from localStorage with URL query values taking precedence.
- Core exports checkbox, numeric types, text, select/multiselect, JSON, bytes, timestamp/calendarDay, password, virtual, relationship, file, and image field factories.
- The document field supports configurable formatting, links, dividers, layouts, relationships, and component blocks; document output can optionally hydrate relationship data.
- createAuth() adds password authentication, authenticatedItem, endSession, generated sign-in files, session-data hydration, and denied-access redirects to sign-in.
- Custom list actions can collect field-rendered arguments and configure prompts, success/failure messages, visibility, and navigation; the actions example implements vote, report, and hideWithReason.
- Asset examples provide local filesystem storage and S3 public/signed URLs; Cloudinary exposes transformed image URLs, and create-keystone-app copies a starter project into a selected directory.
Data flow
Configuration is transformed into executable schemas, generated artifacts, and browser metadata before requests arrive. Each HTTP GraphQL request receives a context containing its decoded session and shared Prisma access. Persistence flows through input resolvers and hooks, while browser preferences, session stores, asset stores, and telemetry use separate state boundaries.
- config() adds IDs and list defaults; initialise-lists invokes each field factory with provider, list metadata, listKey, and fieldKey, then resolves its access, hooks, GraphQL enablement, and UI metadata.
- buildArtifacts() prints the public GraphQL schema and formatted Prisma schema; generateArtifacts() writes both, while generateTypes() derives TypeScript from the internal schema and initialized lists.
- Express parses GraphQL JSON and multipart uploads, then calls context.withRequest(req,res); withRequest() invokes the session strategy and returns a context bound to the resulting session.
- Admin creation serializes field-controller state into mutation variables; server input resolution applies field hooks before list hooks, validates resolved data, transforms it for Prisma, and returns before/after callbacks.
- findMany() enforces maxTake, operation access, list filters, field filtering/cursor permissions, and ordering permissions before a Prisma query; access filters are combined with caller filters using AND.
- File input streams are counted and passed to storage.put(); Prisma receives filename/filesize metadata, output URLs delegate to storage.url(), and changed or deleted assets are removed through afterOperation.
- Stateless sessions seal data into HTTP-only cookies and return the sealed token; storedSessions instead persists data under a random ID and seals that ID, then resolves or deletes it through the configured store.
- Development telemetry POSTs package versions, database provider, list/field counts, OS, and Node major version; Conf records per-project/device send dates, with CI, production, opt-out, and environment-variable exclusions.
Behavior traces
The inspected flows connect CLI startup, browser item creation, password login, and asset persistence to their actual execution functions. Branches such as disabled UI, failed authentication, denied queries, and frozen builds change the sequence materially. These are source-derived walkthroughs, not executed traces.
- Production startup follows cli('start') → start() → importBuiltKeystoneConfiguration() → createSystem() → importBuiltPrismaModule() → getKeystone() → connect() → createExpressServer(); --no-server returns before client/server initialization.
- After API startup, enabled UI follows createNextServer() → prepare() → createAdminUIMiddlewareWithNextApp(); PORT and HOST override listen options before httpServer.listen().
- CreateItemPage submits through useCreateItem.create(); invalid fields stop submission, otherwise serialization feeds tryCreateItem(), success clears navigation prevention and emits a toast, then the page navigates to /{list.path}/{id}.
- The generated create resolver calls createOne() → getOperationAccess() → createSingle__() → list/field access enforcement → resolveInputForCreateOrUpdate() → beforeOperation() → Prisma.create() → afterOperation(); singleton creation forces id=1.
- SigninPage submits identity/secret to the generated authentication mutation; its resolver performs sudo().db.findOne(), simulated hashing for missing password data, KDF comparison, and sessionStrategy.start(), returning failure if the token is empty.
- The next authenticated request follows withRequest() → wrapped session get() → stateless getToken()/Iron.unseal() → sudo().query.findOne(sessionData) → withSession(); missing tokens, missing users, or failed hydration leave the request unauthenticated.
- A file create resolves the Upload, opens its stream, transforms the filename, and awaits storage.put() before Prisma persistence; replacement cleanup runs after the update and deletes the old key only when it differs.
- build() bundles configuration, ensures Prisma config, then validates schemas when frozen or generates them otherwise; it generates types/client, bundles Prisma, and optionally generates/builds Next UI. postinstall selects frozen=true and ui=false.
Testing signals
Tests and CI were inspected, not executed; test existence and workflow commands do not establish passing results. The inspected coverage includes access control, authentication, asset lifecycle, editor behavior, CLI artifacts, and browser deletion feedback across several frameworks and database providers. This is a bounded inventory, with explicit suite exclusions and local coverage limits rather than exhaustive coverage claims.
- Vitest has a default 10-second timeout and excludes examples/testing and tests2; separate root scripts run document-package Vitest tests, Admin UI tests, tsc, filter verification, and node:test.
- API CI shards general tests across PostgreSQL, SQLite, and MySQL/MariaDB, excludes fields/crud.test.ts from those shards, and runs field CRUD separately for each provider.
- tests2/access.create.test.ts uses node:test and strict assertions to check list create denial, field create/read behavior, and privileged persisted values; its field cases skip lists containing unique fields.
- auth-header.test.ts exercises unauthenticated query/update behavior, rejects nonunique identity configuration, and verifies bearer-token access after password login.
- File tests verify bytes and metadata with in-memory storage plus replacement/deletion cleanup; these inspected cases exercise strategy doubles rather than a live S3 service.
- Document heading tests call editor.insertText()/insertBreak() and compare inline snapshots; the architecture guide describes normalization/input tests with UI rendering as smoke coverage.
- Admin UI tests combine Vitest and Playwright to check successful, failed, and partial bulk-deletion notifications; CI installs Chromium and runs selected Admin UI files with one worker.
- CLI tests cover missing builds, ESM builds, --no-prisma, and production NODE_ENV; inspected limits include manually triggered Windows CI and docs builds ignoring TypeScript errors while root tsc excludes docs.
Risk map
The main sensitive boundaries are privileged context APIs, authentication/session configuration, external storage, and commands that generate files or alter databases. Source inspection also reveals example/API drift and a Cloudinary metadata mapping concern. These findings are source observations or explicitly labeled hypotheses, not confirmed vulnerabilities or executed defect reproductions.
- sudo() constructs an internal context with permission bypass enabled, while internal() only changes schema scope; direct Prisma access is exposed separately and the actions example explicitly uses it to bypass Keystone access checks.
- Admin UI access defaults to allowed when no session strategy exists; server.cors=true becomes reflected origins with credentials=true. These configuration choices must be assessed independently of list API permissions.
- Hypothesis: omitting a stable session secret can invalidate sessions after strategy reconstruction or across independently initialized instances, because statelessSessions() generates a fresh random default secret. (inferred)
- Hypothesis: a successful storage.put() followed by validation or database failure can leave an orphaned asset, because upload occurs during input resolution and the inspected cleanup hook addresses replaced/deleted old filenames after persistence. (inferred)
- CLI operations have filesystem/database side effects: dev defaults to dbPush=true, Prisma helpers spawn the resolved CLI and use temporary directories, and artifact destinations can be configured through resolved paths.
- The magic-link example reads password.extensions.keystoneSecretField and calls generateHash(), whereas current core exports extensions.keystoneKDF with hash()/compare(); the source names disagree on its token redemption path.
- Cloudinary output maps both width and height from _meta.width, and the field implementation explicitly notes no delete support; dimension reporting and remote asset cleanup warrant focused review.
- The document site can build with TypeScript errors ignored; root tsc excludes docs, and the inspected main types job runs recursive check plus root tsc, while docs/package.json has no check script.
Extension points
Keystone extensions are primarily configuration callbacks and typed factories rather than a central plugin registry. Lists, fields, hooks, actions, schema extensions, sessions, and storage strategies feed into generated runtime and UI structures. Transport and Admin UI generation expose additional integration boundaries.
- Custom fields plug in as FieldTypeFunc factories receiving provider/list/field metadata; their result supplies database shape, input/output resolvers, access, hooks, views, and Admin metadata.
- graphql.extendGraphqlSchema() receives the generated schema after core query/mutation assembly; createAuth() composes its authentication extension before the application's existing extension.
- list.actions entries are initialized into GraphQL argument types, singular/plural operation names, telemetry labels, and UI prompt/navigation metadata; field-rendered arguments cannot suppress the item prompt.
- Field and list resolveInput hooks transform data in that order; validation and beforeOperation/afterOperation hooks provide separate lifecycle stages around CRUD persistence.
- Database customization uses prismaClientOptions(), extendPrismaClient(), extendPrismaSchema(), and onConnect(); getKeystone() also accepts an existing Prisma client.
- Session strategies implement get/start/end, storedSessions accepts a store factory parameterized by maxAge, and asset StorageStrategy delegates put/delete/url with access to the Keystone context.
- Admin UI generation accepts ui.getAdditionalFiles() and discovers admin/pages files; additional files take precedence, and custom pages override matching generated pages.
- server.extendExpressApp() and extendHttpServer() run before Apollo middleware registration; document consumers separately extend editing through componentBlocks and DocumentFeatures without exposing Slate as the public customization contract.
Contributor handoff
Begin with the owning package and relevant example, then trace configuration, generated schemas, request context, and persistence together. Tests and CI were inspected, not executed; future validation must distinguish selected test commands from actual results and use disposable databases. Keep source edits small, preserve generated/public API boundaries, and treat this inventory as bounded rather than exhaustive.
- Use the pinned pnpm version and workspace catalog; read root scripts before invoking checks because postinstall runs Preconstruct setup and recursive package checks.
- For runtime changes, read schema.ts, getContext.ts, createContext.ts, and Express startup together: defaults, dual schemas, client construction, and request-session ownership reside in different modules.
- Change schema generators/configuration rather than generated GraphQL, Prisma, type, or Admin output; frozen builds compare generated schemas to files, and non-live UI generation removes prior output except .next.
- Keep internal(), sudo(), query, db, and Prisma semantics separate; schema omission and permission bypass are distinct switches, and direct Prisma operations do not inherit the example's Keystone access checks.
- For authorized validation, select existing scripts or focused suites first: document edits use test:vitest, access changes use test:node/API tests, and Admin UI behavior uses test:admin-ui. These commands and CI were inspected, not executed here.
- Use disposable database targets for tests: tests2 selects provider from DATABASE_URL, creates temporary project directories and isolated database locations, then generates artifacts/client and pushes Prisma schema.
- Editor work should follow the architecture guide's normalization and rendering conventions: avoid reactive Slate hooks in element/leaf renderers, derive toolbar state centrally, and assert editor structure with snapshots.
- Before using examples as implementation templates, reconcile magic-link password metadata with core's KDF API and review lifecycle compatibility: bulk mutation errors deliberately preserve input ordering for legacy test expectations.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 978 | 98% |
| Markdown | 137 | docs/config |
| JSON | 109 | docs/config |
| YAML | 37 | docs/config |
| JavaScript | 18 | 2% |
| CSS | 11 | docs/config |
| HTML | 2 | docs/config |
| SQL | 1 | 0% |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (344 files)
Repository structure
| Top-level path | Files |
|---|---|
examples/ | 575 |
packages/ | 344 |
docs/ | 302 |
tests/ | 194 |
tests2/ | 17 |
.github/ | 15 |
prisma-utils/ | 4 |
scripts/ | 3 |
Docs found: CONTRIBUTING.mdREADME.mddocs/CHANGELOG.mddocs/README.mddocs/content/blog/a-year-of-releases-in-review.mddocs/content/blog/customisable-admin-ui.mddocs/content/blog/embedded-mode-with-sqlite-nextjs.mddocs/content/blog/general-availability.mddocs/content/blog/introducing-keystone-blog.mddocs/content/blog/keystone-8.md
Package
package.json — @keystone-6/mono-repo, 20 declared dependencies.
@babel/core@babel/plugin-transform-runtime@babel/preset-env@babel/preset-react@babel/preset-typescript@changesets/changelog-github@changesets/cli@changesets/get-github-info@changesets/get-release-plan@preconstruct/cli@types/node@types/react
CI & config entrypoints
README.md— Repository readme.github/workflows/tests_ci_windows.yml— GitHub Actions workflow.github/workflows/website_production.yml— GitHub Actions workflow.github/workflows/publish.yml— GitHub Actions workflow.github/workflows/tests_ci.yml— GitHub Actions workflow.github/workflows/publish_preview.yml— GitHub Actions workflow.github/workflows/version_packages.yml— GitHub Actions workflow.github/workflows/update_draft_release.yml— GitHub Actions workflowpackage.json— npm scripts: build, ci:version-packages, format, format:check, lint, lint:fix, postinstall, resolve:create-starter-catalogdocs/package.json— npm scripts: build, build:llms, build:rss, dev, dev:live, generate-redirects, remove-conditionals, sitemap
Structural health signals
Average score 7.2/10 across 96 analyzed source files; 21 hotspots surfaced.
packages/core/src/lib/core/initialise-lists.ts— 1316 lines, score 5 (Large file, Deep nesting)docs/app/(site)/page-client.tsx— 926 lines, score 5 (Large file, Deep nesting)docs/app/(site)/ds/page-client.tsx— 642 lines, score 5.5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
1a8f2b7fae392026-09-14 — Remove minio in CI (#10036)77f4965fe5262026-09-14 — Deploy site with GH Pages (#10035)5d58de638a752026-09-02 — Add verifyDepsBeforeRun: false to pnpm-workspace.yaml (#10033)928a45b4b05d2026-09-01 — Simplify examples/custom-session-passport (#10032)311188d29dba2026-09-01 — Use jose instead of jsonwebtoken in examples/custom-session-jwt (#10031)