DOCSEARCHbyAlgolia
Submit Docs

KeystoneJS v5 Documentation

website·Indexed 35 days ago

https://v5.keystonejs.com/

Documentation for KeystoneJS v5, a headless CMS that provides a GraphQL API and Admin UI. Includes guides on data modelling with Lists and Fields, access control, relationship configuration, and the Hooks API. Covers integration with the Prisma adapter, Docker deployment, and migration paths to Keystone 6.

Tokens
57.1K
Snippets
318
Records
417
Agent score
60%

What's inside KeystoneJS

  1. Overview of Keystone 5 Passport Authentication Flows

    The @keystonejs/auth-passport package supports three primary authentication flows for integrating third-party services (e.g., Google, Twitter, Facebook, GitHub):

    1. Single-Step Account Creation & Authentication: The default flow. If the service provides sufficient information (like name and email), a Keystone account is created and the user is authenticated immediately.
    2. Multi-Step Account Creation & Authentication: Used when additional information (e.g., age or email confirmation) is required. The process pauses after the service callback to gather extra data via a form before completing account creation.
    3. Existing Account Authentication: If a user already exists with a matching ID in the configured idField, they are authenticated without creating a new account.

  2. Overview of @keystonejs/server-side-graphql-client

    The @keystonejs/server-side-graphql-client library provides utility functions to perform server-side queries and mutations without writing manual GraphQL strings.

    Key behavioral differences compared to keystone.executeGraphQL:

    1. Error Handling: Errors are thrown as exceptions rather than returned as values.
    2. Access Control: By default, these functions run with access control disabled, making them ideal for data seeding or system scripts. This can be overridden using the context option.
    3. Pagination/Chunking: Queries are internally paginated and mutations are internally chunked (configurable via pageSize).

  3. Overview of available Keystone App types

    Keystone Apps are used to prepare Express-compatible middleware and provide a build() method for static production builds. Available app types include:

    • GraphQLApp: Provides the GraphQL API (Required).
    • AdminUIApp: Provides the Keystone Admin UI.
    • Static App: Used for serving static files.
    • Next.js App: Used for serving a Next.js application on the same server as the API.

  4. Overview of Keystone Hooks

    Hooks allow developers to inject custom logic into Keystone's lists, fields, and operations. They are categorized by Stage (when they run), Operation (which action triggers them), and Hook Type (where they are attached).

  5. Use the CalendarDay field for timezone-independent dates

    The CalendarDay field stores an abstract date value that is independent of any time zone. This is ideal for dates like birthdays or all-day events that should remain the same regardless of the user's local time zone.
    const { Text, Password, CalendarDay } = require('@keystonejs/fields');

keystone.createList('User', {
  fields: {
    email: { type: Text },
    password: { type: Password },
    lastOnline: {
      type: CalendarDay,
      dateFrom: '2001-01-16',
      dateTo: '2020-05-20',
    },
  },
});

  6. Understand Keystone field type categories

    Field types in Keystone define how data is stored in the database, how GraphQL types are defined, and how the Admin UI is rendered. They are divided into two main categories:

    1. Core Field Types: Included in the @keystonejs/fields package. These are typically primitive values (e.g., Text, Number, DateTime) or essential CMS structures (e.g., Select, Relationship).
    2. Non-Core Field Types: Specialized 'flavors' of core fields. They often share a primitive data structure with a core field but provide a different conceptual meaning or a specialized UI (e.g., the Markdown field stores data like a Text field but provides a rich editor interface).

  7. Handle database migrations in Keystone

    Keystone does not automatically manage database migrations because it cannot determine how to transform existing data when List definitions change (e.g., renaming fields or changing field types). If a List definition is updated without a corresponding database migration, Keystone may throw errors upon restart because the database schema no longer matches the application code.

  8. Query items from a Keystone list

    Keystone automatically generates four top-level queries for every list. Using a User list as an example, you can retrieve all items, a single item, or metadata about the items and the list itself.
    # Retrieve all items (supports filter, limit, and sorting)
query {
  allUsers {
    id
  }
}

# Retrieve meta info about items (e.g., count for pagination)
query {
  _allUsersMeta {
    count
  }
}

# Retrieve a single item by ID
query {
  User(where: { id: "some-id" }) {
    name
  }
}

# Retrieve meta info about the list itself (e.g., access control)
query {
  _UsersMeta {
    # fields available here
  }
}

  9. Understand KeystoneJS database schema mapping

    KeystoneJS models data using Lists and Fields. Database adapters translate these into the underlying data store. Generally, a Keystone List (e.g., User) maps to a table in PostgreSQL (e.g., Users) or a collection in MongoDB (e.g., users). Most Field types have a one-to-one correspondence with a database column or field.

  10. Prisma Adapter production readiness and limitations

    The Prisma adapter for KeystoneJS is currently not considered production-ready. Key limitations include:

    • Database Support: Currently only supports PostgreSQL databases.
    • Migrations: Dependent on the production readiness of Prisma Migrate, which is currently in preview mode.

  11. Integrate Prisma database adapter with Keystone

    The Prisma database adapter allows Keystone developers to use Prisma's type-safe query builder for server-side data interactions. This integration provides access to advanced database features including transactions, aggregations, and migrations. At the time of this release, the adapter primarily supports PostgreSQL, though MySQL and SQLite are planned.

  12. Choose a supported database for Keystone

    Keystone supports two database types: MongoDB and PostgreSQL. You must choose one of these to store your system data. Ensure you record the connection string used to connect to your chosen database, as it is required during the Keystone project setup.