Keystone 5 vs 6, which should you use?

Updated July 22nd, 2021. See Updates for the latest improvements.

Keystone 5 is now in maintenance mode.

We’re focusing all our efforts on Keystone 6: it’s currently in a preview release, and will be released to general availability later this year. If you’re wondering which version to start your next project with, this guide is for you.

TL;DR

• Both versions are production ready.
• Use Keystone 5 if you need a stable, battle-tested foundation to build on today.
• If you’re happy to manage a few updates over the coming months then Keystone 6 is what you want.

What’s changing between Keystone 5 and 6

There are a few major things that will change between versions 5 and 6 which we’re currently implementing in Keystone 6:

• New field types. Including a new Document field field which replaces the old Content field.
• New configuration syntax and CLI.
• New express-independent session system.
• New internal APIs for querying lists.
• Completely new Admin UI.

DB adapters out. Prisma in.

We’re also moving away from maintaining several database adapters to just using Prisma, which simplifies things. Until Prisma supports MongoDB (which is currently a preview feature) we’ll have a gap in our database support.

There are also differences between Knex and Prisma for Postgres users, which mainly matter for advanced use cases like migrations and raw SQL, etc.

Keystone 6 is production ready

Thinkmill is already running Keystone 6 in production (including rugby.com.au) so we do rate it as stable from a runtime perspective; but from an API perspective it is still evolving fairly regularly.

Feature parity

We’ve stripped back quite a few field types (like File and Url) and some other functionality during the transition from 5 to 6. These will all be coming back, but we’re not at feature parity yet.

While parity isn’t far off, if you need something urgently that 6 doesn’t include then that might answer the question for you.

Keystone 6 APIs & supporting Docs are evolving

Keystone 6 APIs aren’t 100% stable yet. We’ve published docs for most of the APIs in Keystone 6, but there’s a lot more we have to write.

• If you need stable APIs and comprehensive documentation right now choose Keystone 5.
• If you’re OK spending a bit of time keeping up with changes over the year choose 6. It will be easier to transition from preview to the general availability release when it lands.

Transitioning projects

Transitioning projects from Keystone 5 to 6 will be possible, but it won’t be a simple process of tweaking the configuration.

You’ll have to rewrite your config, schema, session and access control functions, at a minimum. We don't want it to be hard -- the sort of thing you can do in a day or two. You’ll be fundamentally configuring the same things, but it’ll be quite different.

6 vs 5: Pros & Cons

Keystone 6

Pros

• The latest and greatest (Keystone 6 is already much better than Keystone 5).
• Awesome new document field.
• Better Admin UI (with more improvements planned).
• Built on more modern foundations.
• Easier to deploy with database migrations.
• If you keep on top of the updates, you won’t hit a major upgrade wall for quite a while.

Cons

• You’ll need to keep on top of changes for a month or two as we keep evolving Keystone 6 into a more complete and stable API.
• Docs aren’t comprehensive yet.
• Less battle tested (we have spent a lot of effort bringing our entire test suite forward and keeping it green, but there will always be things we could miss this early on).
• You should only use Postgres as the database back-end at this point.

Keystone 5

Pros

• Stable, well documented, battle tested.
• No API churn. It's not going to change much going forward, so your codebase will also be stable.
• More comprehensive features (it has more field types at this point than Keystone 6).

Cons

• It won’t be changed much going forward, so it’s a case of “use it if it works for you” at this point.
• You’ll have a moderate rewrite ahead of you to upgrade to Keystone 6 if you want the new stuff.
• If you’re starting from scratch with a new project, it’s more complex to configure and (aside from 6 docs being incomplete) and harder to learn.

Got questions?

Reach out in the community Slack for help and advice.