Frontend First Development

Frontend
   First
     Development

TL;DR

Solve friction between backend and frontend with an API mocking server, GraphQL, automatic server side rendering and a schema first headless CMS of your choice.

About

Back in the day, web development was a lot less complex. Those days the backend basically was the frontend, today the backend and frontend are two distinct and often rather complex entities. Syncing frontend templates and assets with backend rendered markup is often anything else than straight forward. Depending on the CMS driving your site, you get more or less container markup wrapping the data outputted by different modules and either you overwrite a lot of server templates (if that is even possible!) or you adapt your CSS (not always possible either with flex based layouts) to integrate your markup.

But thankfully there’s finally a promising path out of this mess! By doing as much as possible on the frontend, ideally component based so you can abstract complexity into smaller more focused pieces, and than render the routes and markup with a server side rendering framework, you never again have to sync markup from different sources. And by additionally mocking the API server, we can flexibly and much faster tinker with the project till everything is perfect, without first implementing the feature on the backend, making us more responsive and our clients happy.

Let’s be honest, letting the backend render markup was never a great idea anyway. Not only does it create the described friction between frontend and backend, it also isn’t really the expertise of backend developers, especially when it comes to things like accessibility and above the fold performance optimisations. A frontend first development workflow can solve us all these problems and this place here will try to do it’s best to point you in the right directions.

A content management system is for managing content, not for content rendering!

Why

Let’s first have an overview why we actually need to move to a frontend first development workflow by comparing its advantages and possible disadvantages.

Advantages:

Possible disadvantages:

Less friction between FE and BE

Let’s have a closer look at one of the pros, one that creates a lot of issues with current workflows, to get a better idea why frontend first is such a tempting idea.

Usual developer workflow:

This workflow creates friction when both paths meet!

Frontend First Workflow:

Only one development path, no friction!

Information architecture and technical specification is mostly a first draft. Than changes happen after the client can interact with the frontend or living style guide, while iterating till every stakeholder is happy. Without a frontend first approach, this leads to friction everywhere. Even content creation is more and more frontend first focused these days, just think of headlines that have to be limited to certain lengths to match the design and use fitting word lengths to break nicely in the limited space designed for that element.

Key technologies

Thanks to some key technologies of recent years like GraphQL and all the tooling around it, we are now pretty close to make a truly frontend first workflow possible!

API server mocking

The first key technology is API server mocking. On a frontend first workflow, you want to start working before any backend is set up. Traditionally we used hardcoded data and mocked JSON endpoints to mock our API endpoints, but these days it’s now possible to mock a whole REST or GraphQL server with just some sample data. These kind of servers support all the CRUD operations (create, read, update and delete) and especially with GraphQL, can feel like the real thing, but with almost no effort. This is very important, as you can create prototypes that are so close to the real thing, that your client can get a very realistic impression of the final product, without ever having to first setup a backend CMS. The other important feature of this approach, is that you can design your sample data so realistically, that you can test frontend edge cases, for example different content lengths, right from the beginning. As you’re working with sample data, changes to your API are done in seconds, even changing normally complicated stuff like relationships, becomes really easy.

If you want to have super fast iterations on your API, there’s no way around an API mocking server.

Let’s have a look at an example. The following sample data defines a blogging API where users have posts and posts can have comments and comments can be replies to other comments.

Of course in a real world app, you would add more realistic content (no lorem ipsum!) and more entries for each type to make it more realistic.

However, this small sample data file already defines quite a few features that would normally take quite a while to implement. For example there are multiple relationships between types, like that each user can have posts and comments assigned to him. Each post can have multiple comments and comments can reference another comment (replies). Some fields are optional, for example “comment_id” on the comment type as a post can have no comments.

Further, if we have to add a new field to our schema, all we need to do is add that field to the sample data, for example an email field on the user type:

Just restart the mocking server, and that’s it! Same thing for relationships, just add it to your sample data, restart the mocking server and you’re done. It couldn’t be easier and faster (well, beside adding a watcher to the mocking server so you don’t have to restart it after every single change), making it possible to dynamically alter your backend without actually writing any backend code, making it possible to iterate fast and even tinker live on the source together with your client!

API mocking server tools:

Our recommendation is of course to use one of the GraphQL variants, as it has multiple advantages like having just one very flexible endpoint, no over and under fetching and auto documentation and autocomplete for all possible queries and fields. And with Hasura, you even get a full GraphQL Engine from your sample data, how cool is that?!

GraphQL is the enabler of a true frontend first workflow!

GraphQL

In a real world application, where performance counts, REST runs into problems pretty fast. What normally happens on every project, is that you start implementing custom endpoints for pretty much everything, to prevent over and under fetching and especially having to call multiple endpoints to get all the data you need. Thankfully GraphQL solves all these problems. Not having to write custom endpoints, makes the switch from a mocked API to the real thing extremely easy. In most cases all you need to change is the url to the real API. Here is an example query for the sample data posted above:

With a REST API, this simple query could already end up in a maximum of 11 requests to the server as you would have to do one extra request for each unique user, definitely not something you want to happen on a mobile connection! That’s why in any realistic real world REST setup, you would create a custom endpoint for this case, but with GraphQL that isn’t needed at all, allowing us to easily mock the API in a realistic way.

For consuming a GraphQL endpoint, I highly recommend Apollo. It hits a sweet spot between advanced features like caching, optimistic UI, refetching etc. and ease of use and it’s where the community is at right now, so you have nice documentation, tons of articles and a great community in case you run into problems. For very simple APIs and frontends, Lokka can be a great alternative.

I would personally stick with Apollo, as it integrates nicely with server side rendering frameworks, as we’ll see next and has it’s own caching proxy solution that you can use out of the box.

Now what if I need to integrate existing REST API endpoints? Maybe even external third party ones that I can’t port to GraphQL? With Apollo this is actually not a big issue. Thanks to Apollo Link Rest, you can easily use REST APIs together with GraphQL, in the same queries.

In case you don’t expect to use a CMS to manage the data, you can relatively easily setup a real GraphQL server. Have a look at GraphQL engines, that make it possible to setup real database driven endpoints without too much effort:

Those are great options if you’re building all functionality by yourself (or your team), without a CMS managing your data, but I wouldn’t do it initially, as it makes tinkering with your data quite a bit more involved.

Headless CMS

If you need a strong admin interface for content management, with approval workflows, the flexibility to integrate other services and other enterprise requirements, you normally don’t build everything yourself from scratch, you choose an enterprise level CMS that can handle all of that stuff already. Sadly all the currently most popular CMS solutions on the market aren’t very well suited for a frontend first workflow. But thankfully, new contenders are entering the market and are now realising the potential of a schema based GraphQL API approach. Directus for example is almost database agnostic, so you could write your own connector to, for example Hasura, our current GraphQL engine favorite, and manage the content decoupled from the database/API server. This would even solve the issue that Directus doesn't have a GraphQL API, as you would use the API from the Hasura Engine. It's not perfect, but we're not that far away from an optimal solution, either.

Here’s an incomplete list of possible options:

Server Side Rendering

When going frontend first, your CMS or API backend should only deliver the content and not render the frontend routes and markup. Now you could build everything as a single page app (SPA), but that has some serious disadvantages when it comes to search engine optimisation (SEO), a must for client projects. Thankfully we have great options now that can solve this issue. The idea is that you build your frontend as you would in a SPA, but than have a SSR framework that can extract the routes from your SPA and render them server side. Two options:

The nice thing with Rogue is that it guesses your endpoints based on your React Router 4 setup. This way you can build your project like a normal single page app, and Rogue will build the server side rendering part automatically based on your apps routes, meaning you don’t have to define anything twice and changes to your routes are immediately reflected to your server side routes.

Server side rendering can be quite easy these days, you don’t have to come up with your own solutions.

The other ones are less automatic, but can be great options, as well. Next.JS for example is quite battle tested by now, so you probably won’t run into early adopter issues.

The Frontend First Development workflow

As we had a look at the needed technologies now, let’s have a closer look at the frontend first workflow itself:

1. Create realistic sample data for your project

This is where everything starts. Initially build a simple sample data file that contains all the types, relationships and has at least one entry per type that only contains the required fields, so that the mocking server can guess the schema correctly. As the project goes on, start to add additional more realistic data. Work as long as possible with sample data, so you can implement changes as fast as possible.

2. Run the API mocking server

You can now run the mocking server using your sample data locally using either GraphQL JSON Server or less recommended, JSON Server for a REST API.

3. Build your server side rendered app

Setup your frontend with one of the server side rendering frameworks that can automate the server rendering part, currently either Rogue or Reframe. Both frameworks make it possible to render your routes server side in a SEO friendly way, without having to setup that part yourself, making it possible for you to focus on building your frontend.

For bigger projects, it is recommended to build your frontend on top of a living style guide, design system and component library. Here are some libraries that can help you with that:

4. Iterate with the client till the frontend is perfect

With the new powers and flexibility you get using a frontend first development workflow, use this chance to iterate often and improve the product together with your client. An agile project setup is a must in a project like this. While the one path workflow at first looks a lot like waterfall, your project actually profits most from an agile workflow, where you iterate fast and often.

5. Generate the schema for the backend and let them build the real API server

Using your final sample data, you can now easily generate the GraphQL schema for the backend. From the same guy that made JSON GraphQL Server, you can use this library to automatically generate the schema: GitHub - marmelab/graphql-schema-from-json: Guess a GraphQL schema from json data

6. The backend generates (automatically or not) the admin interface based on the schema

This is the point where you start implementing the CMS or the admin forms for the API server. Sadly on most current CMS options, this isn’t an automatic process where you just import the schema and you’re done. This step still involves clicking your backend types together, but things are starting to change, making this a one click process like it should. If you’re running you project on a GraphQL engine, things are a little bit easier, but your entry forms won’t be as client friendly as with a CMS solution.

7. Connect the SPA to the real backend

As soon as the backend is ready, switch your GraphQL endpoint in your SSR rendered app to the real thing. Deploy and you’re done.

… and lastly …

Are we there yet?

Almost.

There are still a few things that need to be improved before this approach can really take off. For example the GraphQL API mocking server still has some missing features (Edit: With Hasura JSON Data Import, we made a big step forward!):

On the server rendering side of things, many tools are still quite new and not extremely battle tested.

But overall it’s a good time to start building frontend first and help the community improve the available tools as much as you can.

Looking at the available CMS solutions, it would be nice if you could import your sample data directly, or at least the generated schema and than use the database from your GraphQL engine, for a real schema first experience.

Talking about schema first development. You may wonder why a sample data first and not schema first approach is described here. Using schema directives to tell the server how to generate sample data could look like this:

Or how GraphQL Faker does it: GitHub - APIs-guru/graphql-faker: 🎲 Mock or extend your GraphQL API with faked data. No coding required.

Personally I believe that you get much better results with realistically mocked data than with fake computer generated fields. I do think GraphQL Faker has it’s uses, maybe even by combining it with a sample data server, but working with clients and design driven development, realistic data is a must have.

Frontend First Community

If you like that idea of frontend first development, please join our new community on Reddit: r/FrontendFirst

And join the newsletter where we monthly post all the latest tools and articles about this topic.

Most importantly, help the community improve the tools, either by using them and post bug issues or feature request or by directly getting involved in the development of these tools! :-)