System Configuration API

The keystone-next CLI expects to find a module named keystone.ts with a default export of a Keystone system configuration returned from the function config().

import { config } from '@keystone-next/keystone/schema';

export default config({ /* ... */ });

The config function accepts an object representing all the configurable parts of the system:

export default config({
  lists: { /* ... */ },
  db: { /* ... */ },
  ui: { /* ... */ },
  server: { /* ... */ },
  session: () => { /* ... */ },
  graphql: { /* ... */ },
  extendGraphqlSchema: { /* ... */ },
});

We will cover each of these options below.

The configuration object has a TypeScript type of KeystoneConfig, which can be imported from @keystone-next/types. This type definition should be considered the source of truth for the available configuration options.

lists

The lists config option is where you define the data model, or schema, of the Keystone system. It has a TypeScript type of ListSchemaConfig. This is where you define and configure the lists and their fields of the data model. In general you will use the createSchema() function to create this configuration option. See the Schema API docs for details on how to use this function.

import type { ListSchemaConfig } from '@keystone-next/types';
import { config, createSchema } from '@keystone-next/keystone/schema';

export default config({
  lists: createSchema({ /* ... */ }),
  /* ... */
});

db

import type { DatabaseConfig } from '@keystone-next/types';

The db config option configures the database used to store data in your Keystone system. It has a TypeScript type of DatabaseConfig. Keystone supports three different database types; Prisma, PostgreSQL, and MongoDB. These database types are powered by their corresponding Keystone database adapter; prisma_postgresql, knex, and mongoose. The prisma_postgresql adapter includes support for the migrate commands of the Keystone command line.

All database adapters require the url argument, which defines the connection URL for your database. They also all have an optional onConnect async function, which takes a KeystoneContext object, and lets perform any actions you might need at startup, such as data seeding.

As well as these common options, each adapter supports a number of optional advanced configuration options.

prisma_postgresql

Advanced configuration:

• enableLogging (default: false): Enable logging from the Prisma client.
• getPrismaPath (default: () => '.keystone/prisma' ): Set the location of the generated Prisma schema and client.
• getDbSchemaName (default: () => 'public' ): Set the schema named used in the database.

The functions for getPrismaPath and getDbSchemaName are each provided with the generated Prisma schema as a string in the { prismaSchema } argument.

export default config({
  db: {
    adapter: 'prisma_postgresql',
    url: 'postgres://dbuser:dbpass@localhost:5432/keystone',
    onConnect: async context => { /* ... */ },
    // Optional advanced configuration
    enableLogging: true,
    getPrismaPath: ({ prismaSchema }) => '.prisma',
    getDbSchemaName: ({ prismaSchema }) => 'prisma',
  },
  /* ... */
});

knex

Advanced configuration:

• schemaName (default: 'public' ): Set the schema named used in the database.
• dropDatabase (default: false): Setting this to true will cause Keystone to drop your database and then recreate the tables after connecting to the database.

export default config({
  db: {
    adapter: 'knex',
    url: 'postgres://dbuser:dbpass@localhost:5432/keystone',
    onConnect: async context => { /* ... */ },
    // Optional advanced configuration
    schemaName: 'public',
    dropDatabase: false,
  },
  /* ... */
});

mongoose

Advanced configuration:

• mongooseOptions (default: {} ): Additional options to be passed into mongoose.connect(). See the Mongoose docs for a detailed list of options

export default config({
  db: {
    adapter: 'mongoose':
    url: 'mongodb://localhost/keystone',
    onConnect: async context => { /* ... */ },
    // Optional advanced configuration
    mongooseOptions: { /* ... */ },
  },
  /* ... */
});

ui

import type { AdminUIConfig } from '@keystone-next/types';

The ui config option configures the Admin UI which is provided by Keystone. It has a TypeScript type of AdminUIConfig. This config option is for top level configuration of the Admin UI. Fine grained configuration of how lists and fields behave in the Admin UI is handled in the lists definition (see the Schema API for more details).

Options:

• isDisabled (default: false): If isDisabled is set to true then the Admin UI will be completely disabled.
• isAccessAllowed (default: (context) => !!context.session): This function controls whether a user is able to access the Admin UI. It takes a KeystoneContext object as an argument.

Advanced configuration:

(coming soon)

export default config({
  ui: {
    isDisabled: false,
    isAccessAllowed: async context => true,
    // Optional advanced configuration
    enableSessionItem: true,
    publicPages: [],
    getAdditionalFiles: async () => [],
    pageMiddleware: (async() = {}),
  },
  /* ... */
});

server

import type { ServerConfig } from '@keystone-next/types';

The run commands from the Keystone command line will start an Express web-server for you. This server is configured via the server configuration option.

Options:

• cors (default: undefined): Allows you to configure the cors middleware for your Express server. If left undefined cors will not be used.
• port (default: 3000 ): The port your Express server will listen on.

export default config({
  server: {
    cors: { origin: ['http://localhost:7777'], credentials: true }:
    port: 3000
  },
  /* ... */
});

session

import type { SessionStrategy } from '@keystone-next/types';

The session config option allows you to configure session management of your Keystone system. It has a TypeScript type of () => SessionStrategy<any>.

In general you will use functions from the @keystone-next/keystone/session package, rather than writing this function yourself.

import { statelessSessions, withItemData } from '@keystone-next/keystone/session';

export default config({
  session: withItemData(
    statelessSessions({ /* ... */ }),
    { /* ... */ }
  ),
  /* ... */
});

See the Session API for more details on how to configure session management in Keystone.

graphql

import type { GraphQLConfig } from '@keystone-next/types';

The graphql config option allows you to configures certain aspects of your GraphQL API. It has a TypeScript type of GraphQLConfig.

Options:

• queryLimits (default: undefined): Allows you to limit the total number of results returned from a query to your GraphQL API. See also the per-list graphql.queryLimits option in the Schema API.

export default config({
  graphql: {
    queryLimits: { maxTotalResults: 100 },
  },
  /* ... */
});

extendGraphqlSchema

import type { ExtendGraphqlSchema } from '@keystone-next/types';

The extendGraphqlSchema config option allows you to extend the GraphQL API which is generated by Keystone based on your schema definition. It has a TypeScript type of ExtendGraphqlSchema.

In general you will use the function graphQLSchemaExtension({ typeDefs, resolvers }) to create your schema extension.

import { config, graphQLSchemaExtension } from '@keystone-next/keystone/schema';

export default config({
  extendGraphqlSchema: graphQLSchemaExtension({ typeDefs, resolvers }),
  /* ... */
});

See the schema extension guide for more details on how to use graphQLSchemaExtension() to extend your GraphQL API.