Keystone 5 vs Next. Which should you use?
Updated March 31st, 2021. See our roadmap for the latest improvements.
Keystone 5 is now in maintenance mode. We‘re focusing all our efforts on Keystone Next, to be released as Keystone 6 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 Next is what you want.
There are a few major things that will change between 5 and 6 which we’re currently implementing in Keystone Next:
- 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.
We’re also moving away from maintaining several database adapters to just using Prisma, which simplifies things. Until Prisma support MongoDB (which is planned) 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.
Thinkmill is already running Keystone Next 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.
We’ve stripped back quite a few field types (like
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 Next doesn’t include then that might answer the question for you.
Next APIs aren’t 100% stable yet. We’ve published docs for most of the APIs in Keystone Next, 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 Next. It will be easier to transition from Next to 6 when the major release lands.
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.
- The latest and greatest (Keystone Next 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.
- You’ll need to keep on top of changes as we keep evolving Keystone Next 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.
- Stable, well documented, battle tested.
- Not going to change much going forward, so your codebase will also be stable. No API churn.
- More comprehensive features (for example, more field types at this point that Keystone Next).
- 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 next docs being incomplete) and harder to learn.
Reach out in the community Slack for help and advice.