Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/keystonejs/keystone-5


https://github.com/keystonejs/keystone-5

Last synced: 3 months ago
JSON representation

Awesome Lists containing this project

README 

        


  
⚠️ Maintenance Mode


  
Keystone 5 has moved into maintenance mode!


  
We recommend starting any new projects using Keystone 6


  
Information on upgrading an existing keystone 5 project to keystone 6 can be found here


  
For more information please read our Keystone 5 and beyond post.


  










  

  
KeystoneJS


  


  
A scalable platform and CMS to build Node.js applications.


  
schema => ({ GraphQL, AdminUI })


  


  
Keystone comes with first-class GraphQL support, a highly extensible architecture, and a wonderful Admin UI.


  Looking for Keystone v4.x / Keystone Classic? Head over to keystone-classic.

  








![CI](https://github.com/keystonejs/keystone-5/workflows/CI/badge.svg)

[![slack](https://img.shields.io/badge/chat-on%20slack-blue.svg)](https://community.keystonejs.com/)

[![Supported by Thinkmill](https://thinkmill.github.io/badge/heart.svg)](http://thinkmill.com.au/?utm_source=github&utm_medium=badge&utm_campaign=react-select)



## Contents



- [What's new](#whats-new)

- [Getting Started](#getting-started)

- [Documentation](#documentation)

- [Version Control](#version-control)

- [Contributing](#contributing)

- [Code of Conduct](#code-of-conduct)

- [License](#license)



## What's new?



Keystone 5 is a complete re-imagining of older versions It builds on the lessons we learned over the last 5 years of the KeystoneJS' history and focuses on the things we believe are the most powerful features for modern web and mobile applications.



This means less focus on hand-holding Node.js template-driven websites and more focus on flexible architecture, a powerful GraphQL API with deep authentication & access control features, an extensible Admin UI and plugins for rich field types, file and database adapters, and session management.



We believe it's a powerful backend for rich React / Vue / Angular applications, Gatsby and Next.js websites, Mobile applications and more. It also makes a great Headless CMS.



## Getting Started



To get up and running with a basic project template, run the following commands.



```shell

yarn create keystone-5-app my-app

cd my-app

yarn start

```



For more details and system requirements, check out the [5 Minute Quick Start

Guide](https://v5.keystonejs.com/quick-start/).



## Documentation



The [Keystone 5 API documentation](https://v5.keystonejs.com/api) contains a reference for all KeystoneJS packages.



For walk-throughs and discussions, see the [Keystone 5 Guides

documentation](https://v5.keystonejs.com/guides).



## Version control



We do our best to follow SemVer version control within Keystone. This means package versions have 3 numbers. A change in the first number indicates a breaking change, the second number indicates backward compatible feature and the third number indicates a bug fix.



You can find **changelogs** either by browsing our repository, or by using our [interactive changelog explorer](https://changelogs.xyz/@keystonejs/keystone).



A quick note on dependency management: Keystone is organised into a number of small packages within a monorepo. When packages in the same repository depend on each other, new versions might not be compatible with older versions. If two or more packages are updated, it can result in breaking changes, even though collectively they appear to be non-breaking.



We do our best to catch this but recommend updating Keystone packages together to avoid any potential conflict. This is especially important to be aware of if you use automated dependency management tools like Greenkeeper.



## Contributing



This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.



**Contributions of any kind are welcome!**



You will find the set-up steps in this readme and full release processes and project guidelines in [`CONTRIBUTING.md`](/CONTRIBUTING.md).



### Contributors



We'd like to start by thanking all our wonderful contributors:

([emoji key](https://allcontributors.org/docs/en/emoji-key)):



  

    
Jed Watson
💻

    
Jess Telford
💻

    
Tim Leslie
💻

    
Mitchell Hamilton
💻

    
Joss Mackison
💻

    
Nathan Simpson
💻

    
Mike
💻

  

  

    
John Molomby
💻 🐛

    
Dominik Wilkowski
💻

    
Ben Conolly
💻 🚧 🔧

    
Jared Crowe
💻

    
Gautam Singh
💻

    
lukebatchelor
💻

    
Ticiana de Andrade
💻

  

  

    
aghaabbasq
💻

    
Ajay Narain Mathur
💻

    
mshavliuk
🐛 💻

    
Wes Bos
📖 🤔 🚧

    
vlad-elagin
📖

    
Olya-Yer 
🐛

    
1337cookie
📖

  

  

    
Mike
🤔 📆 👀 💻

    
Jordan Overbye
💻 📖

    
prvit
📖

    
Kennedy Baird
📖

    
Thiago De Bastos
📖

    
Daniel Cousens
📖

    
Simon Vrachliotis
💡 ✅ 📹

  

  

    
Charles Dang
💻 📖

    
dzigg
📖

    
Cristian Mos
📖

    
Arnaud Zheng
📖

    
Ashinze Ekene
📖

    
Fabyao
📖

    
Marcos RJJunior
💻

  

  

    
Ginkgoch
📖

    
MaisaMilena
📖

    
Martin Pham
🐛

    
Justin Smith
📖

    
Gabriel Petrovay
💻 📖

    
Liam Clarke
📖

    
Vladimir Barcovsky
💻

  

  

    
Caleb Gray
💻 ⚠️

    
frank10gm
💻

    
mbrodt
📖

    
Misha Zamkevich
💻

    
Matheus Chimelli
📖

    
Gita Permatasari Sujatmiko
📖

    
Andreas Borg
📖

  



### Demo Projects



These projects are designed to show off different aspects of KeystoneJS features

at a range of complexities (from a simple Todo App to a complex Meetup Site).



See the [`examples/README.md`](/examples/README.md) docs to get

started.



### Development Practices



All source code should be formatted with [Prettier](https://github.com/prettier/prettier).

Code is not automatically formatted in commit hooks to avoid unexpected behaviour,

so we recommended using an editor plugin to format your code as you work.

You can also run `yarn format` to prettier all the things.

The `lint` script will validate source code with both ESLint and prettier.



### Setup



Keystone 5 is set up as a monorepo, using [Yarn Workspaces](https://yarnpkg.com/lang/en/docs/workspaces/). Make sure to [install Yarn](https://yarnpkg.com/lang/en/docs/install) if you haven't already.



First, clone the Keystone 5 repository



```

git clone https://github.com/keystonejs/keystone-5.git

```



Also make sure you have a local MongoDB server running

([instructions](https://docs.mongodb.com/manual/installation/)).



Then install the dependencies and start the test project:



```shell

yarn

yarn dev

```



See [`examples/README.md`](/examples/README.md) for more details on

the available demo projects.



#### Note For Windows Users



While running `yarn` on Windows, the process may fail with an error such as this:



```shell

Error: EPERM: operation not permitted, symlink 'C:\Users\user\Documents\keystone\packages\arch\packages\alert\src\index.js' -> 'C:\Users\user\Documents\keystone\packages\arch\packages\alert\dist\alert.cjs.js.flow'

```



This is due to permission restrictions regarding the creation of [symbolic links](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/). To solve this, you should enable Windows' [Developer Mode](https://docs.microsoft.com/en-us/windows/uwp/get-started/enable-your-device-for-development?redirectedfrom=MSDN) and run `yarn` again.



### Testing



Keystone uses [Jest](https://facebook.github.io/jest) for unit tests and [Cypress](https://www.cypress.io) for end-to-end tests.

All tests can be run locally and on [GitHub](https://github.com/keystonejs/keystone-5/actions?query=workflow%3ACI).



### Unit Tests



To run the unit tests, run the script:



```shell

yarn jest

```



Unit tests for each package can be found in `packages//tests` and following the naming pattern `.test.js`.

To see test coverage of the files touched by the unit tests, run:



```shell

yarn jest --coverage

```



To see test coverage of the entire monorepo, including files which have zero test coverage, use the special script:



```shell

yarn coverage

```



### End-to-End Tests



Keystone tests end-to-end functionality with the help of [Cypress](https://www.cypress.io).

Each project (ie; `tests/test-projects/basic`, `tests/test-projects/login`, etc) have their own set of Cypress tests.

To run an individual project's tests, `cd` into that directory and run:



```shell

yarn cypress:run

```



Cypress can be run in interactive mode from project directories with its built in GUI,

which is useful when developing and debugging tests:



```shell

cd tests/test-projects/basic && yarn cypress:open

```



End-to-end tests live in `project/**/cypress/integration/*spec.js`.

It is possible to run all cypress tests at once from the monorepo root with the command:



```shell

yarn cypress:run

```



_NOTE: The output from this command will mix together the output from each project being tested in parallel._

_This is only recommended as sanity check before pushing code._



## Code of Conduct



KeystoneJS adheres to the [Contributor Covenant Code of Conduct](/code-of-conduct.md).



## License



Copyright (c) 2019 Jed Watson. Licensed under the MIT License.