Skip to content
KeystoneJS LogoKeystoneJS (α)

keystone

Constructor

Usage

const { Keystone } = require('@keystone-alpha/keystone');

const keystone = new Keystone({
  /*...config */
});

Config

OptionTypeDefaultDescription
nameStringnullThe name of the project. Appears in the Admin UI.
adapterObjectRequiredThe database storage adapter. See the Adapter Framework page for more details.
adaptersArray[]
defaultAdapterObjectnull
adapterConnectOptionsObject{}
defaultAccessObject{}
onConnectFunctionnull
cookieSecretStringqwerty
cookieMaxAgeInt30 days
secureCookiesBooleanVariableDefaults to true in production mode, false otherwise.
sessionStoreObjectnull
schemaNamesArray[public]

Methods

MethodDescription
createListAdd a list to the Keystone schema.
extendGraphQLSchemaExtend keystones generated schema with custom types, queries, and mutations.
connectManually connect to Adapters.
prepareManually prepare Keystone middlewares.
createItemsAdd items to a Keystone list.
disconnectDisconnect from all adapters.
executeQueryRun GraphQL queries and mutations directly against a Keystone instance.

createList(listKey, config)

Usage

keystone.createList('Posts', {
  /*...config */
});

Config

Registers a new list with Keystone and returns a Keystone list object.

OptionTypeDefaultDescription
listKeyStringnullThe name of the list. This should be singular, E.g. 'User' not 'Users'.
configObject{}The list config. See the createList API page for more details.

extendGraphQLSchema(config)

Extends keystones generated schema with custom types, queries, and mutations.

Usage

keystone.extendGraphQLSchema({
  types: ['type FooBar { foo: Int, bar: Float }'],
  queries: [
    {
      schema: 'double(x: Int): Int',
      resolver: (_, { x }) => 2 * x,
    },
  ],
  mutations: [
    {
      schema: 'double(x: Int): Int',
      resolver: (_, { x }) => 2 * x,
    },
  ],
});

Config

OptionTypeDescription
typesarrayA list of strings defining graphQL types.
queriesarrayA list of objects of the form { schema, resolver }.
mutationsarrayA list of objects of the form { schema, resolver }.

The schema for both queries and mutations should be a string defining the graphQL schema element for the query/mutation, e.g.

{
  schema: 'getBestPosts(author: ID!): [Post]';
}

The resolver for both queries and mutations should be a resolver function with the signature (obj, args, context, info). See the Apollo docs for more details.

createItems(items)

Allows bulk creation of items. This method's primary use is intended for migration scripts, or initial seeding of databases.

Usage

keystone.createItems({
  User: [{ name: 'Ticiana' }, { name: 'Lauren' }],
  Post: [
    {
      title: 'Hello World',
      author: { where: { name: 'Ticiana' } },
    },
  ],
});

The author field of the Post list would have the following configuration:

keystone.createList('Post', {
  fields: {
    author: { type: Relationship, ref: 'User' },
  },
});

Config

OptionTypeDescription
[listKey]ObjectAn object where keys are list keys, and values are an array of items to insert.

Note: The format of the data must match the lists and fields setup with keystone.createList()

It is possible to create relationships at insertion using the Keystone query syntax.

E.g. author: { where: { name: 'Ticiana' } }

Upon insertion, Keystone will resolve the { where: { name: 'Ticiana' } } query against the User list, ultimately setting the author field to the ID of the first User that is found.

Note an error is thrown if no items match the query.

prepare(config)

Manually prepare middlewares. Returns a promise representing the processed middlewares. They are available as an array through the middlewares property of the returned object.

Usage

const { middlewares } = await keystone.prepare({
  apps,
  dev: process.env.NODE_ENV !== 'production',
});

Config

OptionTypedefaultDescription
devBooleanfalseSets the dev flag in Keystone's express middleware.
appsArray[]An array of 'Apps' which are express middleware.
distDirStringdistThe build directory for keystone.

connect()

Manually connect Keystone to the adapters.

Usage

keystone.connect();

Note: keystone.connect() is only required for custom servers. Most example projects use the keystone start command to start a server and automatically connect.

See: Custom Server.

disconnect()

Disconnect all adapters.

executeQuery(queryString, config)

Use this method to execute queries or mutations directly against a Keystone instance.

Note: When querying or mutating via keystone.executeQuery, there are differences to keep in mind:

  • No access control checks are run (everything is set to () => true)
  • The context.req object is set to {} (you can override this if necessary, see options below)
  • Attempting to authenticate will throw errors (due to req being mocked)

Returns a Promise representing the result of the given query or mutation.

Usage

keystone.executeQuery(queryString, config);

queryString

A graphQL query string. For example:

query {
  allTodos {
    id
    name
  }
}

Can also be a mutation:

mutation newTodo($name: String) {
  createTodo(name: $name) {
    id
  }
}

Config

OptionTypeDefaultDescription
variablesObject{}The variables passed to the graphql query for the given queryString.
contextObject{}Override the default context object passed to the GraphQL engine. Useful for adding a req or setting the schemaName

Have you found a mistake, something that is missing, or could be improved on this page? Please edit the Markdown file on GitHub and submit a PR with your changes.

Edit Page