Skip to content
KeystoneJS LogoKeystoneJS (α)

Creating a New Keystone Project

In this guide we will learn how to manually create and run a new Keystone project.

Initialization and basic packages

First things first. Create a directry for your future project and init npm package there.

mkdir new-project
cd new-project
yarn init

Let's start from minimal setup. We will need two packages here: @keystone-alpha/keystone which is Keystone's core and @keystone-alpha/adapter-mongoose which allows our app to connect to MongoDB.


yarn add @keystone-alpha/keystone @keystone-alpha/adapter-mongoose

First steps in coding

After installation we can start to write our code. Main entry point of Keystone app is index.js file placed in root folder. Create it and type following:

// import neccessary modules
const { Keystone } = require('@keystone-alpha/keystone');
const { MongooseAdapter } = require('@keystone-alpha/adapter-mongoose');

// create an instance of Keystone app
const keystone = new Keystone({
  name: 'New Project',
  adapter: new MongooseAdapter(),

You can specify any suitable name for your application. Note that we created an instance of Mongoose adapter and passed it to Keystone's constructor.

Now we can export our instance and make it available for running. Add following to the end of index.js:

module.exports = {

That's it. But now our app does nothing, just starting and connecting to database. If you run application now it will display something like that:

TypeError: Router.use() requires a middleware function

Let's create some routes! For this we will use another powerful Keystone's feature - GraphQL explorer UI.

Setting up GraphQL interface

As in previous step install neccessary package.

yarn add @keystone-alpha/app-graphql

Import it.

const { GraphQLApp } = require('@keystone-alpha/app-graphql');

And create instance.

module.exports = {
  apps: [new GraphQLApp()],

In order to be able to start an app we need to add at least one List. List is a model that is compatible with Keystone's admin UI.

Adding first List

In index.js add following before module.exports:

keystone.createList('Todos', {
  fields: {
    name: { type: Text },

This code snippet creates a List named 'Todos'. Second argument is a config object. For now it have only one key - fields which is used to attach schema for newly created model. That means that we want our Todos item to have only one field - name and it should be of type Text. To specify type we need to import it:

yarn add @keystone-alpha/fields


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

That's it.

Starting application

Add following to package.json:

"scripts": {
    "start:dev": "keystone"

Now ensure that mongod is running and execute our start script:

yarn start:dev

You should see something like this

✔ Keystone instance is ready 🚀
🔗 GraphQL Playground:   http://localhost:3000/admin/graphiql
🔗 GraphQL API:          http://localhost:3000/admin/api

Now it's the time to check those routes in browser to ensure that everything works as expected. And then proceed to second step - Adding Lists

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