Tools of the trade - Progressive Web App for WikiToLearn

This is the second post in my GSoC series. You can read the first one here.

When creating anything from scratch you really have to choose the best resources and tools for the job: if you are baking a cake you want the best ingredients, if you are building a table you want the best wood. The same goes for creating software, one should alwasy aim at using the best technologies availbale.

Finding the best tools in Web Development is sometimes not an easy task, this field moves so fast that one can't possibly keep up with all the new libraries, frameworks and methodologies (That's why sites like Days Since Last JavaScript Framework exists).

The best possible way to find the right combination of tools for a project is by experimenting with as many tools as possible, discarding the one you don't like and keeping the one you like the most (or, sometimes, dislike the less).

And this is exactly what I started to do in the last months. I got out of my web development comfort zone and gave a try to some new things. Some I didn't like and many others I loved. Yes, sometimes it felt like this article but I am learning tons of new stuff, which is what matters.

During this Google Summer of Code I will keep experimenting and use many of the concepts I learnt recently: let's wait no more, here is an overview of what I will be using to create WikiToLearn new frontend.

Frontend

Since we are building a PWA the most (and for many use cases, the only) important thing to consider is the frontend technologies.

Since we are building something a little bit complex it is definitely worth it to use some kind of frontend framework. There are many out there (React and Angular are probably the most popular) and after trying a few of these I decided to choose Vue.js.

Vue Logo

Not only it is one of the most lightweight (and fast) framework available, it is actively developed and has an awesome and welcoming community. It is far from being as popular as React or Angular but in the near future I hope it will reach their popularity, because it deserves it.

I choose it because it is simple enough for newcomers but powerful for experienced users. Its templating language is also very easy to understand: I never liked React and its JSX.

Out of the box it only provides the minimal required functionalities: it is more of a micro framework that you can complete with additional (but alwasy optional) libraries. In our case we will use Vuex for state management (think of it as a global variable which does control the state of the application) and vue-router for route managament (it does basically control which parts of the interface to display based on the links you click).

Writing code

For writing HTML code for components and views we decided to use pug instead of plain HTML. This is because pug forces you to indent your code properly (in the same way Python does): it may seems like a small reason but this means that one is forced to write clearer code, something very important when working on a open source project.

For styling the interface we are using Sass. We have been using this for some time and it does it job very well. Since we already have some parts of the interface styled in Sass it will be easy to port them.

For Javascript we will be writing ES6 Javascript: this allows us to write cleaner and easier to understanand code, all thanks to the syntatic sugar it provides. Of course many browsers don't understand ES6, that's why we are transpiling it to ES5 Javascript using buble.

Bundling with webpack

A few years ago there were Bash scripts, then grunt came, then gulp. Nowadays everyone is moving to webpack. Although all the previous mentioned solutions are still valid (and one may say compltely different from webpack), webpack does allow faster development and better building for production.

Webpack

When executing our build-for-production configuration, webpack takes care of many interesting tasks:

  • delete unused code and minify used one
  • compile pug to HTML, Sass to CSS, ES6 to ES5
  • localize the PWA to different languages
  • inline images by converting them to Base64
  • build an HTML file with all the scripts and styles already linked
  • automatic generation of a service worker for caching
  • much more

Although all of these (actually not all) were probably possible with the existing tools it is definitely worth it to invest time in learning webpack: with webpack you just specify the configuration, without defining the work pipeline (in Gulp you had to control which tasks to execute in which order).

Coding Conventions

Since it is very important to write consistent code in term of conventions, we will be using linters all over the codebase. Most importantly we will lint the source Javasript (via EsLint), using Google' style guide as a base, but we will apply a few customizations to it. We will also lint our CSS via stylelint.

Linters will be running both when developing and when building for production, forcing the developer to fix the existing code according to the linters: you won't be able to run your code unless it is written correctly.

And yes, we will be using tabs, not spaces: this is where EditorConfig is very important:

EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs.

Backend

Server Side Rendering

Since we want to keep basic compatibility for people without Javascript and for slow devices we decided to implement server side rendering.

This means that every request will be pre-rendered server side before reaching the browser; Most of the Web Application out there don't pre-render the code, sending to the browser just an almost empty page, leaving to the browser the work to render the interface: this means that if you don't have JS enabled, you are out of luck, nothing will display.

With SSR, even if you don't have JS, you will at least be able to use the basic functionalities of the website, such as reading pages.

Serving the PWA

For serving the PWA to the public we will use a Node.js server, running Express. Node.js is absolutely needed because we want server side rendering: without it we could have used just a simple HTTP server such as Apache or nginx.

The template

In the past months I have been developing (together with another friend of mine) a Vue-based PWA boilerplate project which serves as a starting point for everyone looking to develop a progressive web app with Vue.

I was going to develop this template anyway regardless of GSoC, because right now there is not a single example project out there with as many features as this one: as soon as I head I was selected I began finalizing the details especially needed for WikiToLearn.

Template for a PWA
The generic template: very simple

If you are interested on the template it is available on Github. Don't worry, there is plenty of documentation that explains everything.

What's next?

I will be now forking the template and start using it as a base for the WikiToLearn PWA. I will be publishing the project on KDE's git: check it out here

In the next weeks I will be developing the first few features for the web app, focusing on the browsing and reading functionalities.

Let me know what you think about this post in the comments. Expect another post as soon as I have something good to show you.