Frontend Frameworks eBook [sneak peek!]

As any of you know who follow Divante, we are MACH advocates who always endorse brilliant frontend frameworks and headless builds. We totally believe in technology that is Microservices based, API-first, Cloud-native and Headless. Not only do we believe in it, we’ve been ahead of the curve for quite some time on this. 

Vue Storefront, itself now part of the MACH Alliance, was developed fast and was the first PWA solution of its type to market, which helped it to gain the leadership position that it still holds today.

To help others build better headless frontend frameworks, we have collected our knowledge and experience from building Vue Storefront into a brand new ebook called ‘Designing a headless frontend framework for enterprise applications’. You can download the book now and, to give you a taste, here is a sample chapter.

‘Designing a headless frontend framework for enterprise applications’ is a free resource aimed at CTOs, CEOs, and developers who are looking to undertake a headless build and want to know how to get the most from their resources. 

Download your copy here 

Frontend Frameworks eBook sample: Designers and Harvesters

If I were asked to give a single piece of advice that would bring success in a software project, I’d say: Just get it started. And once you’ve got some progress, don’t forget to get it out of the door: Release it.

It’s often very difficult to start a new endeavor because, at first, it might look very complex and overwhelming. Peter Thiel wrote even a book on this. “Zero to one” is all about why being first to the market, going from zero (not having a product) to one (having a product). If the product is good enough, you might even advance the market, find yourself as a category leader, or even create a monopoly. However, it’s very hard to achieve—even with the greatest product—if you are in a crowded space that already has solid leaders.

The second reason for simplifying things and building a quick MVP is that it keeps the team motivated. You see and validate the results, and then adjust the assumptions. Every startup works this way.

Building a product, however, is a different challenge than building a platform or software framework. With a framework, the expectations are much higher because it will be used as a foundation for other applications and products. The common rule of thumb is that with the framework you should precisely design it, document it, and ask the opinion of the community. You should only release after these phases to complete. It’s ready when it’s ready.

We went a completely different way with Vue Storefront and I must say we learned a lot in the process. I’ll share some of the lessons to help you make more informed decisions based on our experience. 

Zero to one

We decided to break all the rules. We first built a killer application and only afterward extracted a framework out of it. to harvest the architecture as a result of building the first application.

Starting the project, the sheer scope of what we wanted to do made me unsure that we would even succeed in releasing version one. From a time perspective, I made a few decisions to help get things started. Firstly, I knew it had to be an open-source project because it would need support from a large community.

Secondly, I just took the Vue.js application boilerplate (generated by `vue-cli`) and started coding the project right away. One of my colleagues, Karol Bzik, created the Default UI frontend. He wasn’t a graphic designer but it didn’t matter. In fact, the default theme he created is still with us to this day as one of the themes. For me—a CTO who started out as a backend developer—it looked gorgeous. It was so motivating to get it up and running! We started the development right away.

I was coding the whole application a few hours a day, committing directly to the `master` branch. There were very few coding standards, no UML designs, and no pre-analysis documentation. I was experimenting and it was fun. Then Filip Rakowski joined me, coding the frontend, while I was working on the integration part. It was crazy… and we were crazily productive.

Harvesting the architecture

Within 2.5 months, we got the 0.3 release out with all the critical paths covered. You could browse the products and place orders. We also wrote a couple of blog posts on how to contribute and install everything. It was enough to get the ball rolling.

It was charmingly easy. It was a single repository which required two just commands to install the app (`git clone; yarn installer`). It was based on a standard Vue.js boilerplate so everyone who fires it up knows how it works. 

This gave us the first contributors. We initially accepted almost every pull request from the community and people loved it. I was scared and super-excited when I learned about the first production implementation of Vue Storefront in Q1 2018 after about five months of actual product development. 

Just after this, we engaged more developers into the team and started figuring out what was good and what was wrong with the core architecture. We figured out that what people expect from us was upgradability (to have a separate core and themes). We then introduced the themes concept very quickly. It was based on Vue.js components and people literally loved the idea. It looked like WordPress or Magento themes; you created your own customizable theme to which you could apply the desired look and feel within a couple of hours.

Themes were located in the `themes` folder at the beginning and the `core` was just in the `core` folder. Then we added `modules` and the modularity idea evolved within two or three iterations. 

We’ve continuously added features but, to be perfectly honest, most of the features you can find in the current version of Vue Storefront started from Vue Storefront 0.7. From that time we’ve changed pretty much everything under the hood. The whole architecture, in fact. We’ve refactored the full business logic, introducing data services, and refactoring state management. 

First of all, we’ve added TypeScript support. TypeScript is a typed programming language so we added types to all the functions we’ve got within the codebase. We then introduced the coding standards and added (almost full) unit test coverage, as well as functional tests and graphQL support instead of just plain REST APIs.

We’ve been working on Vue Storefront 1 in a really agile way and have been updating the docs along the way. This is what I call “Harvesting the architecture” from the product. It’s like learning by doing. I love it because of how productive it is and that you can get things done. But it has a dark side too.

Setting the ground rules

This agile, iterative approach gave us huge traction and positioned Vue Storefront as the leading PWA framework—a position which it has kept to this day. It was because we were first to the market and that was priceless.

If you’re building an enterprise, or perhaps even an internal application, being first to market might not be so important. It may be more crucial to build your first Proof of Concept (PoC) to get your management board’s approval.

Then, if you’re meaning to build a framework that’s a base for the other teams and other applications, try to first figure out what’s going to change and what’s not. Set the ground rules. Set the contract.

I think that—instead of developing a framework in a fully agile manner (by extracting it from the ready app) or designing it over months on a whiteboard—there is a third way. You can the ground rules, identify the design principles that won’t change, and then start building the product accordingly.

My recommendation is to set the ground rules first. The framework process we’re using for building new R&D products consists of three phases.

Phase 1: Core principles

Ground rules are set in place and shouldn’t change a lot over time. Think twice before adding more restrictions than needed. It will either slow down the team or bring a mess into the codebase. 

You then need to have clear business requirements in order to make sure the design process you’re creating in this first phase will end up with business success. The only sure thing is change, and your rules are meant to make the changes easier. 

The rules shouldn’t be centralized, so the separate teams—working together on the framework or working on separate apps based on the framework—can always make decisions on their own, at their own pace. The worst result of this phase would be a situation in which team members are waiting for a centralized committee to make a decision. This is not why you’re setting the foundation here. Instead, you want teams to be led by objectives and work with some autonomy. 

We accepted most of the contributions to Vue Storefront—even when we had to then fix most of them sometimes by ourselves (ironically, because we had skipped phase 1!). It may not seem ideal but it resulted in 186 active contributors after just a few months, and those people were encouraged and motivated. 

If we’re building a business application framework, we usually like to set the building blocks first. The layers that all the applications will be built of. I’m going to get much deeper into these layers, responsibilities, and designs later on. 

Let’s say our framework is going to have three layers:

• L1: data layer/business logic which is framework independent, just plain JS, and very re-usable
• L2: middle/controller layer which keeps the other things (UI + data) together. If it were MVC, this is the C (Controller). It’s probably based on a kind of boilerplate with a command-line interface to generate the project from the library or design system
• L3: UI library or design system

Here, when we think of ground rules, I mean that you should first set which layers are customizable, which are not.

Re-usability at the core; Customizable at the edge. These will be our key principles for building the frameworks. This means users can potentially modify the UI but probably won’t be allowed to modify the core a great amount. The core, itself, needs to stay upgradable.

You should set the goals and these may be in a form of user stories, such as: “As a developer, I should be able to modify and add new components to the UI library while still using the defaults.”

I’d then suggest you validate the principles and rules set in Phase 1 across all the business use cases and requirements discovered for the resulting applications. Once done, you will be pretty sure that your framework will be flexible enough.

This is an example of the key principles we set for the Storefront UI (which is L3 in our architecture):

We are building Storefront UI based on the following 6 fundamentals:

1. Customization: Along with standard prop-based customization, every component has a set of slots that let you replace any part of it with your own images, icons, or even custom HTML markup. You can also customize the whole library from a single SCSS file by an overriding set of variables.
2. Mobile-first: Every Storefront UI component is highly optimized for mobile user experience and, in many cases, behaves completely differently on desktop and mobile. The select list becomes a full-screen drop-down, tabs become an accordion, etc.
3. Performance: You’re importing ONLY what you need, and in a raw format which means you can benefit from all build-time optimizations like tree shaking or grouping common chunks. Unused components are tree shaken and global CSS is just < 0,1 kB unminified. Thanks to this, the initial footprint of the library is unnoticeable. You can use the library for how many components you want, even a single slider. You bundle only what you import.
4. Best practices: Storefront UI components follow best practices in terms of design and core. Every component is based on the Google Retail UX Playbook and is accessibility-friendly.
5. eCommerce: As a UI library dedicated to eCommerce, Storefront UI—along with standard UI components—has all the elements necessary for building modern online stores.
6. Open source: Storefront UI is a community effort to deliver the best possible experience to modern web applications and eCommerce shops, with carefully crafted components following best practices. Our team consists of agencies and volunteer contributors from all over the world.

The human mind is usually capable of keeping up with up to 7 elements within the random-access memory. Of course, you might need many more rules to be set. For example, we usually have a totally different document for contributing guides. However, the core principles should be as short a list as possible.

It’s okay to set some lower-level principles, like performance quotas. We need to set the frameworks/libs that are shared between all the other apps and/or components.

You should set the coding standards at this phase as well, particularly with reference to naming standards and unit test coverage. The most common areas to cover are branching standards, working with Github, and the minimum coverage of unit tests. 

Your docs will get developed and extended from this point on, so don’t worry if the starting set of principles is quite short. It’s better to extend it along the way than to start with a raft of rules which are both too complex and too limiting.

Phase 2: PoC or MVP

When you get your rules set, start coding immediately. I think that there’s no other way to verify if something works or not than putting it into the code. The other benefit of starting coding early is that you’ll learn a lot about the limitations of the code of conduct that you have just established. You’ll find the 10 or 20 edge cases which you must adjust and will also do a great deal of refactoring.

As a best practice, the first cases you implement should be quite general: Where do I put this new UI component? Where do I customize the routing? How do I implement this “Hello world” application?

You implement a boilerplate / framework core along with some example applications using it. It’s not about the functionalities but rather about prototyping and validating the mode which was created within Phase 1 and testing communication along the way.

You have a lot of questions in this phase and putting the answers into a kind of written FAQ is usually a great way to start the project-wiki. It is live documentation which we usually manage using just the markdown files on Github.

Phase 3: Actual implementation

In the later phase, you actually start coding the first application. If your framework is for building eCommerce sites (as Vue Storefront was), maybe just start building the example shop. Or maybe your brand’s shop? If this is a framework for building CRMs, start building your CRM product.

Mainly, I suggest you spend a couple of weeks setting the rules and then immediately go into IDE and start building the product. 

This is what we learned. With Vue Storefront 1, we started from Phase 3. But with Storefront UI, Vue Storefront Next, and our SAP Spartacus project, we did a short but intensive Discovery phase and then started building the product itself.

This keeps the team motivated but also providing the business stakeholders with the results extremely fast.

Everything developed at this stage is compliant with the ground rules. It’s reusable (to the point you defined the rules) and it’s not messy. You probably still will need to refactor a lot in the process but this is totally normal; after all, this is the essence of learning by doing.

Action points

It’s often easier to get the ball rolling than it seems at the outset. Here are some actionable items to consider if you’re starting a new project:

1. Find the right members for your team; there should be one person making the product/tech decisions when there’s no consensus. Read more in the ‘Let the team strive for success’ chapter of the full book
2. Set up two or three workshops within the first weeks and set the Ground Rules 
3. Validate the assumptions against the case studies on another meeting with someone from the business
4. Write down the ground rules in a centralized, easy to use, shared space like Confluence, Google Docs or Github
5. Start doing a PoC of the framework for one business case
6. Start coding the MVP and learn on the way. As necessary, refactor and change the principles that no longer seem valid as the project progresses