Keystone 4 has landed 🎉

Five years ago (to the day!) I published the first version of KeystoneJS to npm. Today, I’m proud and excited to officially release the long awaited version 4.0.0! No more beta tag for you :)

We couldn’t have done this without our amazing community — with over 200 contributors, 2000 GitHub forks, and 8600 commits, it’s been pretty wild.

Over the last five years, Keystone has grown in ways I never imagined. It’s become the most popular open source content management framework for Node.js. As a framework, it’s powering some unknown-but-large number of live projects around the world — including many major platforms Thinkmill has developed.

But before we crack the champagne and celebrate this milestone, I need to address the fact that getting to version 4 has been tough — really tough — and it has taken way too long.

The Story So Far

Five years ago, I was fairly new to Node.js, and completely new to open source. Publishing Keystone to npm — my first package — was among the scariest things I’ve ever done.

I’ve been writing JavaScript since the late 90’s, but that was always only half the story… because a front-end needs a back-end, and despite there being a lot of back-end frameworks, it never felt like we got it right.

But Node.js! It was both a breath of fresh air, and a major back-to-basics move. I loved the library mindset (no more monolithic frameworks!) and the light-weight feel of it. Not to mention the promise of writing universal JavaScript for the front and back end.

At the same time, a lot was missing — any kind of high level abstraction to share patterns or CMS-like features across projects. We had Express, Mongoose, session management, all the building blocks… but there was so much boilerplate setting it all up! And so, KeystoneJS was born.

The ambition was to deliver a ready-to-go-platform that helps people easily get started without the lock-in that defines other frameworks.

Is it possible to build something that feels like a framework when you’re getting started, gives you a solid platform to build on, then fades into the background as the complexity of your application scales?

I believe so. We haven’t totally realised this vision, even today, but releasing Keystone 4 is a major step towards that, and Thinkmill has doubled-down on investing in the platform.

We didn’t nail it the first time (but who does, right?)

Back in 2013, we were happily building express-powered websites with jade templates, preprocessing stylesheets with LESS, writing complex route middleware that processed actions and loaded data, and decorating the front-end with jQuery to build rich experiences.

If this doesn’t sound like front-end development today, you’d be right.

As React emerged and changed the way we thought about building rich user interfaces, it was a challenging pivot to deal with in Keystone. Our ideas changed faster than the framework could, and we started using it for less.

Ultimately, this means we didn’t nail the architecture — or nail the balance of building our platform by aligning it to our day jobs. We made the mistake of being afraid to break things to fix them, and letting ourselves work around blocks rather than breaking them down.

We’ve learned a lot along the way. And six months ago, with my partners and collaborators at Thinkmill, we took stock and made some big decisions about the future of Keystone.

We asked ourselves: given what we’ve learned, given how technology has grown, if we were to start from scratch today, with the same ambition, how would we build it? What would it feel like to use?

Just as importantly, it became hard to work on Keystone. Why was this? Some personal burnout plays in here, and so does some need to focus on our business at Thinkmill (lesson: align all your incentives). But also the goal didn’t line up with the implementation. They were too far apart, and the codebase too hard to develop increasingly complex features in.

We admitted to ourselves that the current path was not going to achieve the vision we had for Keystone, or result in the platform we want to be using in 2020. Things had to change.

At the same time, when it looked from the outside like we’d given up, our community stepped up with a sense of enthusiasm and positivity for Keystone that just floored me.

Keystone 4

First up, we needed to get Keystone 4 out of beta and launch a dependable version for everyone who’s invested in building a project on it. The final release got caught up by two things: too much scope, and our goal to make the upgrade from v0.3.x seamless.

Turns out you should pick one, so we cut the scope and focused on releasing what works (and what we have been using in production for over a year now).

We did this by:

• Bringing forward required work but not including anything that requires major rearchitecting
• Updating dependencies, migrating deprecated packages and closing security issues that have been reported
• Addressing tech debt and cleaning up the code base (including tests)
• Updating the supporting documentation

While this approach has reduced the number of new features and changes in Keystone 4 compared to our original ambition, it means that anyone using it today has a solid and certain version that we can continue to update with proper semantic releases.

What’s next?

Several popular features, like nested lists and a permissions framework, aren’t in scope for Keystone 4.0 because they’ve proven too hard to implement in the current architecture.

Most “in the wild” stories we’ve heard about Keystone-powered projects have sounded similar to our own experience — frameworks like React, and GraphQL, have been implemented on top of the platform, which is cool… except we believe it would be more powerful to build support for these natively in Keystone itself.

To do this, we’re in the process of designing a new architecture for Keystone’s future based on everything we’ve learned. Follow @keystonejs on twitter to keep up with what we’re doing. We’ve also opened up our Slack to everyone, so if you want to get involved sign up here.

I’m looking forward to sharing more as we progress, and in the meantime if you’re using Keystone or looking for a node.js platform that helps you get a project started — we hope you enjoy this new release!

Jed