Creating PWA with Angular 5. Part 1: Getting started with framework, creating an application, hosting it on github-pages.

Nastya Smirnova
Nov 29, 2017 · 8 min read

I’ve been delaying my acquaintance with new Angular framework for too long time. As a big fan of AngularJS v1.x, I didn’t get the necessity of so radical changes came with new versions of it.

My eyes were opened during GDG DevFest Ukraine 2017. Tired and hungry by the end of the day 1, I’ve charged my final reserve force on the speech named “Web goes Native: Progressive Web Apps with Angular” by Shmuela Jacobs. And that was it! Inspiring, productive, fast and easy. I couldn’t believe that ‘progressifying’ of the web application can be just that simple.

A month later, when the new Angular 5 was announced and released, I decided to deal with it at all costs and create my first progressive web application. My experiment was successful, and now I am glad to share with you my steps and results.

Step 1. Getting started with Angular.io

As the most of us — I am a lazy person, so really felt in love with the such powerful helper tool — Angular CLI. It’s a magic wand of your project, so don’t be scared of it. The installation is as easy, as every npm module. (My current npm version is 5.5.1, node is 9.2.0).

❗️Check your cli version. 1.5.x is not working properly in some cases, so make sure you are using the 1.6 or higher. My current is 1.6.0-rc.0.

Time to generate a new project. Choose a nice, recognizable name for it. Following my instructions, you are going to create an app, that generates a new cute photo of a cat every time you visit it. Let it be PWCat (abbr. for Progressive Web Cat 😺 )

It can take a couple of minutes to set up a new project — nice chance to make a cup off coffee ☕️. Cheers!

Good news. We do not need any local web server for deployment. Just run in your terminal:

Last command will open a new tab in your browser (make sure that it’s Chrome!) on the http://localhost:4200/, serving your application with some default content. If everything is ok, you will see:

Open PWCat project in your favorite IDE. I’ve chosen the Visual Studio Code, ‘cause it supports the Typescripts without any additional installable packages. Take some time enjoying how many code you have already written 😄. You can read about all that generated files here.

To change the visible name of our application, let’s go to the app.component.ts file and change it’s title property:

Step 2. Adding Angular Material framework

We don’t want to be distracted by any styling, so material.angular.io is our salvation. Let’s install it through the terminal:

Choose one of pre-built themes for our app. Import it in styles.css file

Also we can add normalize.css module to prettify default html styling. In terminal:

In styles.css:

Now we can add material designed modules to our app. To begin with, let’s import the tool bar component. Open the app.module.ts file. You need to add only two lines of code:

❗️Don’t forget to include MatToolBarModule to ngModule decorator.

Now we can use toolbar in any place of our app. Go to the app.component.html, and remove all generated content with following lines:

By setting the color of element to be ‘primary’ we make it use the main theme color. If everything was done correctly, our app will show us a pretty enough header:

Step 3. Our first Angular component

We need to add and image card element to our app, where cute cats will be generated. Let it be the separate component, and nothing can be so easy, as generating components in Angular 5:

As a result you can see that angular has generated a new folder for you with all necessary files. Also take a look at app.module.ts. New component has been imported automatically.

To use new component in application just put it’s selector in the necessary place.

And again let’s use material outlook for our card.

Due to angular material docs, card template should look like:

As a source for cat images we will use awesome free service called cataas.com, which api is quite straightforward.

Also, it would be nice to have some ‘Refresh’ button to get new cat pictures if we want to. Try to add MatButtonModule by yourself.

Time to write some code

Let’s make the image source dynamic. Go to the img-card.component.ts and create a new class called something like CatImage.

Now we can add a private property image of type CatImage for ImgCardComponent. The property src should be public and of type string. Take a look on the way we use that properties in the ngOnInit method:

To make our button alive we should create a new function (public method), that will make some magic for us. I called mine generateSrc:

Keyword void shows that our function has nothing to return.
Size is one of the image options provided by cataas.com api.

Time to make some changes in img-card markup. Replace long hard-coded source url with component property {{ src }}. To add event listener to the card button, use (click) attribute.

Unfortunately, the image is not updating when we click on our Generate button, because actually the value of src stays unchanged. Let’s fix that by adding a fake query param with a timestamp in it.

After adding some custom styles…

… we will finally get our working app. Enjoy your cats!

Step 4. Hosting our app on GitHub

4.1 Creating a new repository

Create a new repository on github.com (without any init files — to avoid conflicts in the future). Give it a name of your project and press a big green button below.

Go to the terminal and run the following:

And that’s it! Reload repository page to see your code on github.

4.2 Build a production version of application

We don’t need ‘ng serve’ anymore, so turn it off. Time for some production options:

As a result, we can see a new ‘/dist’ folder with our bundled app.

4.3 GH-pages

If your are new to github pages, your can get familiar with it on the official page. After you’ve got the main idea, let set up gh hosting for our app.

To begin with, let’s create a new branch for it. In terminal:

Go the the Settings tab of your repo, scroll down a little bit and find a ‘GitHub Pages’ section. Make sure that gh-pages branch is set as a source.

Although our site is finally published and available on the provided link, unfortunately we see only a content of README.md file. The problem is that github doesn’t see the index.html file in our root folder, and doesn’t understand that it needs a ‘/dist’ one.

To fix that, we can push to the gh-pages branch only a content from the ‘dist’ folder. To help us, saint people created an angular-cli-ghpages module for that.

If everything was done correctly, you will see the ‘Successfully published!’ message. Refresh gh-url of your app and enjoy that moment of glory!

You can find source code of my application here. Live app is available here.

See you in the Part 2.

Nastya Smirnova

Written by

Front-end developer. Mentor. Lead of WTM Kropyvnytskyi. Trying to make friends with web-design, iconography and typography. 日本語を勉強します。