Rewrite the Admin UI in React

Some Background

The KeystoneJS Admin UI was originally built as a ‘simple’ web app, based on old-school form generation, submission and rendering techniques combined with jQuery for client-side UI enhancements.

This decision has helped us develop reusable processing techniques that are easily applied to server-driven projects (from contact form processing on websites to complete applications and APIs).

It’s also been limiting though, and ultimately we want the Admin UI to be a rich client-side app. Now that the server side patterns are mature, it’s time to focus on that.

Because we’ve known for a while that the Admin UI will be rewritten, this has unfortunately blocked several enhancements we’ve been keen to build, and which have often been requested by our community, including a plugin architecture, custom field types, and richer Admin UI functionality.

Primarily, the block has been that if we open it up to customisation then change the whole architecture, it’ll create a backwards compatibility nightmare for anyone who’s invested in the old system. So this is now the next big thing, that will lead to other big things, and I’m really excited to be digging into it.

Why React?

I’ve spent a long time trying to decide the best fit for Keystone’s Admin UI, and have assessed a lot of frameworks including Angular, Ember, Polymer, Backbone and more before settling on React.

Polymer was the favourite for a long time - because web components are the future, and play a very important role in our long term plans for Keystone - but unfortunately it’s just not mature enough.

React, on the other hand, has excellent support, a robust routing solution, is very fast, and does a great job of providing many of the benefits web components will bring, today.

It also plays very nicely with Browserify, which combined with a grunt workflow, provides a great development environment, and makes sense for the way we expect to implement custom field types and extensions.

The Plan

We don’t expect this to be a massive, disruptive rebuild - it doesn’t need to be. The first step will be to selectively replace server-generated code with React components that still behave the way the current Admin UI does, with a form-submission / processing / rendering workflow.

Once that is done, many of the blocks around allowing extensible field types and Admin UI customisation will be removed.

The next step will be to transition fully to a react app that will run client-side against API endpoints. In the same way we made the UpdateHandler and other tools work in a way that dramatically improves productivity when developing server-side processing workflows, we’ll use this transition to develop great client-side app workflows that are reusable in projects. Very little will be specific to the Admin UI itself.

For the field types (and forms, and list UI) our intention is to develop reusable components that can be dropped into Keystone projects and reused outside of the Admin UI, providing rich functionality regardless of whether the server or client is doing the processing.

Some things will certainly need a rich client interface, but server-side HTML generation and processing is still important on the web, and hopefully we can create a solution that facilitates the holy grail of sharing code between the client and the server without being locked into either.

Can you help?

There is still a lot to be worked out around the best way to manage application state, extensibility and component structure. There will also be quite a bit of work involved in transitioning all the current UI elements to React components.

If you have experience working with React and would be happy to help, please let us know!

[ryanflorence]

<drive-by-react-marketing>

For anybody bummed about not picking angular, this is from their last weekly meeting notes:

Key points: scope hierarchy is a huge pile of shared state that many components from the application because of two way data-binding it’s not clear what how the data flows because it can flow in all directions (including from child components to parents) - this makes it hard to understand the app and understand of impact of model changes in one part of the app on another (seemingly unrelated) part of it.

demo single data flow direction - always from the top to bottom each state has an owner - some component - and only that component can change the state

https://docs.google.com/document/d/150lerb1LmNLuau_a_EznPV1I1UHMTbEl61t4hZ7ZpS0/edit

In other words, changing $scope is a lot like changing a css selector. Its virtually impossible to identify what cascading effects that has on your app.

Its not just angular, Ember is also looking to learn from React to sort out similar problems.

Many people with experience in production apps that implement 2-way binding (read: ember/angular) are finding incidental complexity and performance problems that React has wonderful answers to.

Anecdotal, but I haven’t met a person yet who built something in React and walked away without wanting to do everything else in React 😛

</drive-by-react-marketing>

[ayoungh]

This sounds great but slightly puts me off development using keystone at the moment, what would you suggest in terms of starting a development with Keystone now or waiting till after these changes are made?