Keystone Nextpreview

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: { /* ... */ },
experimental: { /* ... */ },
});

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 the database types PostgreSQL and SQLite. These database types are powered by their corresponding Prisma database providers; postgresql and sqlite.

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 provider supports a number of optional advanced configuration options.

postgresql

Advanced configuration:

  • enableLogging (default: false): Enable logging from the Prisma client.
  • useMigrations (default: false): Determines whether to use migrations or automatically force-update the database with the latest schema and potentially lose data.
export default config({
db: {
provider: 'postgresql',
url: 'postgres://dbuser:dbpass@localhost:5432/keystone',
onConnect: async context => { /* ... */ },
// Optional advanced configuration
enableLogging: true,
useMigrations: true,
},
/* ... */
});

sqlite

Advanced configuration:

  • enableLogging (default: false): Enable logging from the Prisma client.
  • useMigrations (default: false): Determines whether to use migrations or automatically force-update the database with the latest schema and potentially lose data.
export default config({
db: {
provider: 'sqlite',
url: 'file:./keystone.db',
onConnect: async context => { /* ... */ },
// Optional advanced configuration
enableLogging: true,
useMigrations: true,
},
/* ... */
});

Limitations

The sqlite provider is not intended to be used in production systems, and has certain limitations:

  • document: The document field type is not supported.
  • decimal: The decimal field type is not supported.
  • timestamp: The timestamp field type only supports times within the range 1970 - 2038.
  • text: The text field type does not support the advanced filtering operations contains, starts_with, ends_with, or case insensitive filtering.
  • autoIncrement: The autoIncrement field type can only be used as an id field.
  • select: Using the dataType: 'enum' will use a GraphQL String type, rather than an Enum type.

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.
  • apolloConfig (default: undefined): Allows you to pass extra options into the ApolloServer constructor. See the Apollo docs for supported options.
export default config({
graphql: {
queryLimits: { maxTotalResults: 100 },
apolloConfig: { /* ... */ },
},
/* ... */
});

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.

experimental

The following flags allow you to enable features which are still in preview. These features are not guaranteed to work, and should be used with caution.

import { config } from '@keystone-next/keystone/schema';
export default config({
experimental: {
enableNextJsGraphqlApiEndpoint: true,
generateNextGraphqlAPI: true,
generateNodeAPI: true,
}
/* ... */
});

Options:

  • enableNextJsGraphqlApiEndpoint: (coming soon)
  • generateNextGraphqlAPI: Creates a file at node_modules/.keystone/next/graphql-api with default and config exports that can be re-exported in a Next API route
  • generateNodeAPI: Creates a file at node_modules/.keystone/api with a lists export

On this page

  • System Configuration API
  • lists
  • db
  • postgresql
  • sqlite
  • ui
  • server
  • session
  • graphql
  • extendGraphqlSchema
  • experimental