For instance, take an Angular project, this requires a few things to get started, like Typescript, NodeJS, Angular CLI, etc. This can easily be created using docker and once set up can easily be re-created on demand. As you can imagine, this can have several benefits, which we will look at later.

On its own, it still leaves much to be desired though. But, a while back the Visual Studio Code team released a pack of extensions for remote development. These extensions enabled you to work with development environment hosted remotely such as docker containers, among others and continue with development workflow as you would if they were on your local PC.

Combined with VS Code Remote - Container's extension, part of Visual Studio Remote extensions pack, which enables you to use docker as a full-fledged development environment. The Remote Container extension, provides you with tools to connect to a docker container and carry on with your development workflow on the container.

On top of that, it provides tools to:

• Generate Docker Environment Configurations for different environment requirements like Typescript, Golang, etc. This allows you fine-grained control over your development environment with exactly the dependencies you need to enable your development workflow.
• Clone a repository directly to docker containers. You can target different branches and PRs, allowing you to have a development environment per PR if need be.

Benefits For Development

For one, since docker containers are isolated environments, collision between different development environment dependencies is greatly reduced if not entirely eliminated. How many times have you required to have different versions of the same dependency installed, for instance NodeJS? Docker development container would eliminate such collisions entirely, reducing the need for tools such as NVM.

Secondly, it is easier to onboard developers, as the development environment are already specified and it's a matter of building the containers. This makes it easy to onboard developers as they can set up their environment faster and go straight to understanding what actually matters to the organization.

On top of on boarding new developers, reviewing PRs is easier, as you can easily and quickly create a new development environment per PR for review purpose. VS Code remote container extension provides you with tools to enable clone repository, branches or PRs into development containers, making this a more viable approach.

Another key benefit is keeping your development environments up to date across team members becomes easier. When you come back from a vacation, with a single command, you can update your development environment making easy to continue as if you never left with little to no hinderances.

Fully compatibility with GitHub Code Spaces. GitHub code spaces is a remote development environment that uses docker development containers under the hood. While still in beta and a lot could change, as of the moment of writing, they are fully compatible. This means that you can easily take your development environment on the road without needing to configure anything after the initial configuration. GitHub code spaces will provide you with all the computing power you need while on the road.

Cons

Steep learning curve. While VS Code helps to set up common development environments like NodeJS, Typescript, etc., setting a fine-grained environment will require you to understand docker and dockerfiles. This can be a barrier to people who aren't familiar to docker and adds an extra barrier to getting up to speed.

Conclusion

In this article, we looked at Docker development containers and the benefits of using them. I am hoping that the benefits we looked at above convinced you to give docker development containers a try.

If you are looking to get started, here some resources for you:

• Developing inside a Container using Visual Studio Code Remote Development
• Use containers for development | Docker Documentation
• Develop with Docker | Docker Documentation

So, what are template literal types?

Literal Types

In order to understand what template literal types are, we first need to have a brief look at literal types. Literal types allow us to define types that are more specific, instead of something that is generalized like string or number.

Let's say you have a switch; it can have the value of either on or off. One way of defining the types of this, is to use literal types, giving it the type of either On or Off:

type Switch = "On" | "Off"

In the case above, the value of any variable of type Switch can only be On or Off:

const x: Switch = "On"
const y: Switch = "Off"

If you tried to assign any other values other than On or Off, typescript will throw an error:

Template Literal Types

Template Literal Types build on this, allowing you to build new types using a template and can expand to many different string using Unions. This works just like template literal/strings, but instead of concatenating to form strings, it concatenates to form types.

const variable = "string";
type tVariable = "string";

// this results to a variable
const val = `This is a concatenated ${variable}`

// while this results to type
type X = `This is a concatenated ${tVariable}`

As you can see, they are similar in syntax apart from what they are defined as, the first being a variable and the second being a type. The type of the first definition will be string, while the second one will be of type This is a concatenated string and a variable of that type can only be assigned to that string.

NB: If you tried to use variable instead of a type when defining Template Literal Type, it will throw the following error: 'variable' refers to a value, but is being used as a type here. Did you mean 'typeof variable'?

If we take our example above of type Switch, we may want to have a function that returns the status of the switch, i.e. Switch is On or Switch is Off, and have it strongly typed, in that it can only return only those strings. With Template Literal Types, we can define this as follows:

type Switch = "On" | "Off"

const x: Switch = "On"
const y: Switch = "Off"


type SwitchStatus = `Switch is ${Switch}`;

And this in return gives us the types: Switch is On and Switch is Off:

Using To Build Types for Grid Items Coordinates

Let's say we are working with a grid system, and wanted to perform a task on various boxes in our grid, like placing something on a specific box given its coordinates. It would be nice if we could strongly type it and ensure we don't specify values outside the grid.

For instance, if we had a grid whose length was 3 smaller boxes on either side of the box. This makes it that we have 9 smaller box fitting on our big box. We can use literal types to create a type for each of our boxes, with the type being its position in the grid. So, the first gets L1-H1 and the last gets L3-H3 types, as shown below.

type SquareBoxes = "L1-H1" | "L1-H2" | "L1-H3" | "L2-H1" | "L2-H2" | "L2-H3" | "L3-H1" | "L3-H2" | "L3-H3"; 

Those are a lot of types to create by hand even for a small grid of 9 boxes. But, with template literals types, we could define just the type of the length of one side and use template string literals to expand the rest of the types:

type length = "1" | "2" | "3";

type SmallerBoxes = `L${length}-H${length}`

And this would yield the same result as before:

This makes our work easier and it is more versatile, because if the smaller boxes ever increased or decreased, you only need to adjust the size of the length.

// 16 boxes
type length = "1" | "2" | "3" | "4";

// 25 boxes
type length = "1" | "2" | "3" | "4" | "5";

// 4 boxes
type length = "1" | "2";

Combining With Generics

We can combine template literal types with generics to some amazing effect. Let's take with a Type of Person, which has two properties - name and age.

type Person = {
    name: string;
    age: number;
}

We want to add two methods to be called to update the values of name or age i.e. nameChanged or ageChanged. We can create a new type, that will take type Person as a generic, and for each property of type Person, we will add new properties with Changed appended the original properties of type Person i.e. nameChanged and ageChanged. We will used template literal types to create a new property by appending Changed to the property name.

type WithPersonChangedEvents<Type> = {
    [Property in keyof Type as `${string & Property}Changed`]: (newValue: Type[Property]) => void;
} & Type;

NB: The above example uses some advanced typescript technique for manipulating types on top of Template Literal Types which you can learn more here.

Now, we can use both of our Types (Person and WithPersonChangedEvent) above:

const person: WithPersonChangedEvents<Person> = {
    name: "Name",
    age: 20,
    nameChanged: (newName) => console.log(newName),
    ageChanged: (newAge) => console.log(newAge),
};

person.ageChanged(21); // Logs: 21
person.nameChanged("new Name"); // Logs: "new Name"

And as you can see, our object - person has 4 properties, with 2 being the added methods.

Conclusion

We have learned about Template Literal Types in Typescript and how they build on top Literal types to provide you even more flexibility when defining types. We have also looked at different use cases like in a grid system type definition for different boxes coordinates and combining them with generics to define extra properties for an object.

Resources

• Creating Types from Types - Link.
• Template Literal Types Documentation - Link.
• Template literals (Template strings) - Link.
• Types and Mocking - Typescript - Link.
• Transforming Types in TypeScript with Utility Types - Link.

For an RSS plugin, we will build a routeDiscoveryDone plugin, which is usually called when all routes have been discovered. This is going to use data discovered during the route discovery process to create an RSS feed. The route discovery process is done by a router plugin, which you can learn more about here.

Scully provides 9 types of plugins which are called during different stages of Scully build. For more information about different types of plugins, please visit the official documentation here.

Prerequisites

• Setup Scully for Your Angular Project - Link.

Building the Plugin

Getting Started

If you used schematics to setup your Scully for your Angular project, you should be able to spot a Scully directory at the root of the workspace. This directory contains a tsconfig file for Scully plugins and a plugins directory, which is where our plugin will live.

Inside the plugins directory - scully/plugins - we will create a new file named rss.ts, which is going to contain the source code for our plugin.

Plugin Code

To create our RSS feed, we will use the NPM package Feed, which make it easy to generate syndicated feed using Typescript.

Our RSS plugin will be called when Scully discovers all routes and it will receive a list of routes and route data associated with each route discovered.

const createRSSFeed = async (routes: HandledRoute[]) => {
  // code here
}

We will start by creating a new instance of Feed.

First, we need to import Feed.

import { Feed } from 'feed';

Then instantiate Feed.

const feed = new Feed({
  title: 'John Doe Blog',
  language: 'en-us',
  author: {
    email: 'johndoe@example.com',
    name: 'John Doe',
  },
  description: 'about you website or blog',
  id: 'https://example.com',
  link: 'https://example.com/blog',
  favicon: 'https://example.com/favicon.png',
  copyright: "John Doe Copyright"
});

NB: Update the content above according to your own specification.

Next, we will loop over the routes, and add an RSS Feed item for each.

routes.forEach((route) => {
	// add each item to an RSS Feed Article  
})

Then, for each route, we want to add an RSS item, and use the route data - route.data.* to fill in the different properties like title, date, content, etc.

routes.forEach((route) => {
  feed.addItem({
    title: route.data.title,
    date: new Date(route.data.publishedAt),
    link: route.data.link,
    // loop through the names of the authors if list
    author: [
      {
        email: route.data.author.email,
        name: route.data.author.email,
      },
    ],
    // uses tags as categories
    category: route.data?.tags?.map((t: Tag) => ({
      name: t.name,
    })),
    content: route.data.html,
    id: route.data.id,
    image: route.data.featured_image,
    published: new Date(route.data.publishedAt),
  });
})

NB: update the different properties of each item according to the structure of your data. For markdown content, this are the keys in the Front Matter.

Finally, we will save our RSS feed as an XML file inside the output directory of Scully. We can use fs-extra to do that, so we will start by installing the package.

Yarn:

yarn add --dev fs-extra

NPM:

npm i -D fs-extra

Then, we will import outputFileSync from fs-extra.

import { outputFileSync } from 'fs-extra';

Finally, we will save the RSS feed.

// the output directory of your scully builds artefacts
const outDir = './dist/static';

outputFileSync(join(outDir, 'blog', `feed.xml`), feed.rss2());

On top of that, we can also generate both JSON and Atom files:

outputFileSync(join(outDir, 'blog', `feed.atom`), feed.atom1());
outputFileSync(join(outDir, 'blog', `feed.json`), feed.json1());

That's it for the plugin, here is what the plugin function looks like.

const createRSSFeed = async (routes: HandledRoute[]) => {
  log(`Generating RSS Feed for Blog`);

   const feed = new Feed({
    title: 'John Doe Blog',
    language: 'en-us',
    author: {
      email: 'johndoe@example.com',
      name: 'John Doe',
    },
    description: 'about you website or blog',
    id: 'https://example.com',
    link: 'https://example.com/blog',
    favicon: 'https://example.com/favicon.png',
    copyright: "John Doe Copyright"
  });

  routes.forEach((route) => {
    feed.addItem({
      title: route.data.title,
      date: new Date(route.data.publishedAt),
      link: route.data.link,
      // loop through the names of the authors if list
      author: [
        {
          email: route.data.author.email,
          name: route.data.author.email,
        },
      ],
      // uses tags as categories
      category: route.data?.tags?.map((t: Tag) => ({
        name: t.name,
      })),
      content: route.data.html,
      id: route.data.id,
      image: route.data.featured_image,
      published: new Date(route.data.publishedAt),
    });
  })

  try {
    const outDir = './dist/static';
    outputFileSync(join(outDir, 'blog', `feed.xml`), feed.rss2());
    log(`✅ Created ${yellow(`${outDir}/blog/feed.xml`)}`);
    outputFileSync(join(outDir, 'blog', `feed.atom`), feed.atom1());
    log(`✅ Created ${yellow(`${outDir}/blog/feed.atom`)}`);
    outputFileSync(join(outDir, 'blog', `feed.json`), feed.json1());
    log(`✅ Created ${yellow(`${outDir}/blog/feed.json`)}`);
  } catch (error) {
    logError('❌ Failed to create RSS feed. Error:', error);
    throw error;
  }
};

NB: log and logError are helper functions from Scully, imported from @scullyio/scully.

Registering the Plugin

Next, we will give our plugin a name. First, we will declare and export a variable for the name of the plugin.

export const BlogRSSFeed = Symbol('BlogRSSFeed');

This variable can be imported in to the Scully config file to use the plugin.

Then, we will register our Scully plugin as a routeDiscoveryDone plugin.

registerPlugin('routeDiscoveryDone', BlogRSSFeed, createRSSFeed);

Using the Plugin

Finally, we can use the RSS plugin by adding to the array of postRederrers. This can be achieved using two approaches. The first one will be for all routes within our our application:

export const config: ScullyConfig = {
  projectRoot: './src',
  projectName: 'project-name',
  outDir: './dist/website',
  defaultPostRenderers: [BlogRSSFeed], // for all routes
  routes: {
    '/blog/:slug': {
     	// ...
    },
  },
};

While the second one can be specified for a specific route i.e. blog. This is useful when you only want to generate an RSS feed for a single section of your site like the blog section.

export const config: ScullyConfig = {
  // ...
  routes: {
    '/blog/:slug': {
      postRenderers: [BlogRSSFeed],
      // ...
    },
  },
};

Conclusion

In this article, we learnt how to create a Scully plugin to generate RSS feeds for our Angular app. We have created a routeDiscoveryDone plugin that's called after routes for our application have been discovered and uses the route data to generate RSS feed for each of our route.

Resources

• Speeding Up Angular Scully Builds in GitHub Actions - Link.
• Angular CDK - Platform Module - Link.
• Scully Documents - Link.

Let's take the following function, how do you mock it's inputs i.e. person:

interface Person {
    name: {
        firstName: string;
        lastName: string;
    }
    id: string;
    age: number;
    height: number;
    weight: number;
}

function getPersonsFullName(person: Person) {
    return `${person.name.firstName} ${person.name.lastName}`;
}

One common way, is to create an object of type Person with only the fields being used by function and then cast the object as any, as shown below:

const person = {
    name: {
        firstName: "Wycliffe",
        lastName: "Maina"
    }
}

console.log(getPersonsFullName(person as any));

This works, but you are losing the benefits of typescript typing system by casting as any, since the compiler won't type check the object person being passed to the function.

A good reason as to why this is not a good idea, is that if the function changes and starts using other properties or the shape of the input object changes, TypeScript will not help you. I am guilty of casting as any, especially when writing mocks for tests.

But, is there a better way? Yes, we can improve the function above, so that it is easier to mock the input without resulting to the above technique. One approach, which I really recommend, is to create a new type which only has the fields the function needs to run successfully, in this case the name property. This can easily be achieved in Typescript using Utility Types, which you can learn more about here.

We can use the Pick<T> utility type, to create a new type from Person, with only the name field i.e. picking the name field from the Person type.

function getPersonsFullName(person: Pick<Person, "name">) {
    return `${person.name.firstName} ${person.name.lastName}`;
}

This way, our mock example still works, but without resulting to casting as any:

const person = {
    name: {
        firstName: "Wycliffe",
        lastName: "Maina"
    }
}

console.log(getPersonsFullName(person));

The advantage of this is that you can still pass a person object with more properties as long as name property is present, as shown below:

const person = {
    name: {
        firstName: "Wycliffe",
        lastName: "Maina"
    },
    id: 21
}

// this still works
console.log(getPersonsFullName(person));

Utility types such as Omit, Pick, Partial, Required, etc. can help you create new types easily that define the shape of an input object for a function. This makes it possible to define with precision what a function input type is, with just a little extra work on your part. You can learn more about TypeScript utility types in my previous article here.

This makes your functions and methods more friendly since they are taking in only what they need, making it easy to mock as seen above. Another advantage is that your functions are more re-usable as they don't place an unnecessary burden on the consumer of the function by requiring larger input than they are using.

Typescript offers Utility Types, which are intended to solve this particular problem. In this article, we are going to have a look at these built-in utility types and a third-party library (with examples) that offers more utilities you might find helpful in achieving the above goal.

Built-in Utility Types

This section focuses on TypeScript built-in utility types, they are numerous and I won't be able to cover all of them, I will just look at a few key ones, with examples, in my own opinions.

Partial

This utility type constructs a new type from an existing one, with the keys at the top level being marked as optional (?).

interface Type {
    field: string;
}

type Type2 = Partial<Type>;

NB: This only runs one level, meaning keys below one level will not be affected. If you want to mark all keys as optional, regardless the level they are in, check out PartialDeep below.

Required

This utility type does the opposite of the above, constructing a new type with all keys from the old type that are optional being marked as required.

interface Type {
    field?: string;
    optional?: string;
}

type Type2 = Required<Type>;

Omit

This utility type constructs a new type from an existing type while omitting specified keys from the new type.

interface Type {
    field1?: string;
    field2: string;
    field3: string;
}

type Type2 = Omit<Type, "field3" | "field1">;

Pick

This utility type constructs a new type by picking keys specified from the old type. It does the opposite of Omit, as described above.

interface Type {
    field1?: string;
    field2: string;
    field3?: string;
    field4: string;
    field5?: string;
}

type Type2 = Pick<Type, "field2" | "field3">;

Readonly

This utility type constructs a new type from an existing one and marks all keys as read-only i.e. they cannot be re-assigned. This is useful for types of a frozen object - i.e. Object.freeze().

interface Type {
    field1?: string;
    field2: string;
    field3: string;
}

type Type2 = Readonly<Type>;

Record

This utility type constructs a new type with union members as keys and the type as the type of the keys.

interface Name {
    firstName: string;
    lastName: string;
}

type Names = "user1" | "user2";

type Type2 = Record<Names, Name>;

Above are a few built-in utility types that I find very useful, you can find out more about built-in utility types in the official documentation here.

Extending Built-in Utility Types

While the above built-in utility types are amazing, they don't cover all use cases, and this is where libraries that provide more utilities fill in the gap. A good example of such a library is type-fest, which provides even more utilities.

While I won't look in to all utilities provided by type-fest, I will highlight a few that are quite help and build on the built-in types utilities.

Except

This is a variation of the Omit utility type described above, but stricter. It constructs a new type by omitting specified keys from a Type, but unlike Omit, the keys being emitted must strictly exist in the Type.

import { Except } from "type-fest"

interface X {
  a: string;
  b: string;
  c: string;
}

// Omit Example
type Y = Omit<X, "d">

// Except Example
type Z = Except<X, "d" >

As you can see in the image below, Except throws an error if you provide a Key that doesn't exist.

Merge

Constructs a new type by merging two Types, with keys of the second type overriding the keys of the first type.

import { Merge } from "type-fest"

interface X {
  a: string;
  b: string;
  c: string;
}

interface Y {
  c: number;
  d: number;
  e: number;
}

type Z = Merge<X, Y>

const x : Z = {
  a: "is string",
  b: "is string",
  c: 1,
  d: 2,
  e: 3,
}

PartialDeep

This utility type constructs a new type where all keys in all levels are optional. This is quite similar to the Partial built-in utility type, with one significant difference, it runs deeply to all levels, while the former does it at the first level.

import { PartialDeep } from "type-fest";

interface X {
  a: string;
  b: string;
  c: string;
}

interface Y {
  c: number;
  d: number;
  e: number;
  f: X;
}

type Z = PartialDeep<Y>;

const x: Z = {};

ReadonlyDeep

This utility type constructs a new type with all keys on all levels marked as required. This is also similar to the built-in Readonly utility type, but unlike the built-in utility type, this one goes down to all keys in all levels, making them immutable.

Mutable

This utility type constructs a type that strips out readonly from a keys in a type, essentially the opposite of what the built-in utility type Readonly does.

import { Mutable } from "type-fest";

interface X {
  readonly a: string;
  readonly d: string;
}

type Y = Mutable<X>;

Conclusion

In this article, I looked into typescript utility types and how they can help you automatically create types from existing ones without resulting to duplicating eliminating the need to keep related types in sync.

I highlighted a few built-in utility types that I find particularly useful on my day to day job as a developer. On top of that, we looked into type-fest, a library with a lot of utility types that extends the built-in types, and highlighted just a few.

Resources

• Utility Types - Typescript Docs
• type-fest
  

It is common for most websites, that content can change without the source code of your website changing. Therefore, it can be wasteful to run an Angular build every time your website content changes.

Normally, Angular builds time are decent. But due to a number of factors, Angular builds could slow down, like in my case, running purge CSS against Tailwindcss extends the build time to over 7 minutes. Add everything else together, and my GitHub Actions would take over 12 minutes.

Using GitHub Releases

First, we are going to need a place to store our Angular build artifacts. GitHub releases are a nice way, as it allows you to have a long-term storage of your artifacts that you can use anytime you want. This combined with npm version means ones you have your features ready; you can cut a release that will be used by subsequent builds as you continue to work on other features and/or improvements.

So, we are going to build our workflow to have two jobs, the first job will take care of building our Angular app, and creating a release and uploading our build artifacts to the release. While the second job will take care of Scully builds using the latest artifacts stored in GitHub releases and publishing our website to our hosting platform.

Whenever a new tag is added to the repository, we will create a release with the version no. of the tag and upload our angular builds to that release.

Building our Angular App

Listening to Tags

First, we will need to trigger our GitHub workflow every time a new tag is created. We will be using tags to create release version. This will allow us to use npm version to create new build artifacts for us to use during the publishing process.

on:
  push:
    tags:
      - "*"

NB: In the publish our blog section, we will modify this section to listen to repository_dispatch, which we will use with webhooks to trigger the workflow when events outside our repository like blog post published occur, you can learn more here.

We will limit this job to only run when a new tag is created using startsWith(github.ref, 'refs/tags/'). This will allow us to utilize the same workflow file for building and publishing, with them being two separate jobs.

jobs:
  build:
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest

Installing NPM Packages

Next, we will need to install NPM packages before we can build our angular app. In this case, we are using yarn but feel free to use your favorite package manager. We will start by checking out (git checkout) our repository. After that, we will then setup NodeJS and finally run yarn install to install our NPM packages.

steps:
  - uses: actions/checkout@v1
  - name: Setup Node
    uses: actions/setup-node@v1
    with:
      node-version: 12.x
  - name: yarn install
    run: yarn install

Building Angular Project

And then, we can add a step to run yarn build:prod to build our Angular app in production.

- name: yarn build
  run:  yarn build:prod

Creating a Release and Uploading Artifacts

Now that we have built our project, we are going to do two things next. We will zip the build artefacts and then create a release and upload our zipped artifact to the releases. We will use papeloto/action-zip action to zip the files:

- uses: papeloto/action-zip@v1
  with:
    files: "./dist/webapp/"
    dest: webapp.zip

Replace webapp with the output directory of your angular project build.

And then, we are going to create a GitHub release and upload the above zipped artifact to the GitHub release. We will be using ncipollo/release-action action, to accomplish this as shown below.

- name: Push Build to Releases
  uses: ncipollo/release-action@v1
  with:
    artifacts: "webapp.zip"
    token: ${{ secrets.GITHUB_TOKEN }}

Here is what our workflow looks so far:

name: Release a new Version

on:
  push:
    tags:
      - "*"

jobs:
  build:
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      
      - name: Setup Node
        uses: actions/setup-node@v1
        with:
          node-version: 12.x
          
      - name: yarn install
        run: yarn install
        
      - name: yarn build
        run:  yarn build:prod
        
      - uses: papeloto/action-zip@v1
        with:
          files: "./dist/webapp/"
          dest: webapp.zip
          
      - name: Push Build to Releases
        uses: ncipollo/release-action@v1
        with:
          artifacts: "webapp.zip"
          token: ${{ secrets.GITHUB_TOKEN }}

Building Scully and Publishing Blog

Next, we are going to add a second job - publishing - that will download our Angular build artifacts from our repos latest release, run Scully build and upload the artifacts to our hosting platform.

First, we will need to listen to the on repository_dispatch as this is how we will trigger our website rebuild when the content on our CMS changes, as explained here. Feel free to use any other GitHub action triggers suitable for your content management system i.e. on push to master on the blog directory if you are using markdown.

on:
  push:
    tags:
      - "*"
      
  repository_dispatch:
    types:
      - publish_blog

Next, we are going to create a publish job, which will run after the build job but if the build job doesn't run, it will run anyway. We will use the if: always() condition to run the job even if the build doesn't. This will run the publish job if a new blog post is published, which will skip the build job, but also when a new release is made, in which case you want the website to be published with changes that were released.

The one downside of this approach is that the publish job will run even if the build job fails.

publish:
  runs-on: ubuntu-latest
  needs: [build]
  if: always()

Next, we will need to setup Node and run yarn install to install NPM packages as Scully needs both to run.

steps:
  - uses: actions/checkout@v1
  - name: Setup Node
    uses: actions/setup-node@v1
    with:
      node-version: 12.x
  - name: yarn install
    run: yarn install

After that, we are going to download our build artifact that we uploaded to GitHub release - webapp.zip - and unzip the content to the dist/webapp directory. To download the artifact from GitHub release, we will be using the dsaltares/fetch-gh-release-asset action.

- uses: dsaltares/fetch-gh-release-asset@master
  with:
    repo: "USERNAME/REPOSITORY"
    version: "latest"
    file: "webapp.zip"
    target: "webapp.zip"
    token: ${{ secrets.GITHUB_PAT }}

NB: For private repository, you will need a GitHub Personal Access Token (PAT) with at least the org:hook scope. Learn more here.

Next, we will create a directory to put the angular webapp build artifacts in and then unzip webapp.zip which we downloaded from GitHub releases.

- name: create dist directory
  run: mkdir -p dist/webapp

- name: Decompress
  uses: TonyBogdanov/zip@1.0
  with:
      args: unzip -qq ./webapp.zip -d ./dist/webapp

And finally, run yarn scully for statically site generation of our Angular app:

- name: Run scully
  run: yarn scully

Now we can deploy the Scully build artifact to your website. In this case we will use firebase hosting, which you can do as shown below.

- name: deploy firebase webapp
  uses: w9jds/firebase-action@master
  with:
    args: deploy --only hosting
  env:
    FIREBASE_TOKEN: ${{ secrets.FIREBASE_TOKEN }}

And now our final GitHub Action Workflow looks like this:

name: Publish Blog

on:
  push:
    tags:
      - "*"
 
  repository_dispatch:
    types:
      - publish_blog
      - build_site

jobs:
  build:
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1

      - name: Setup Node
        uses: actions/setup-node@v1
        with:
          node-version: 12.x

      - name: yarn install
        run: yarn install
        
      - name: yarn build
        run:  yarn build:prod

      - uses: papeloto/action-zip@v1
        with:
          files: "./dist/webapp/"
          dest: webapp.zip
          
      - name: Push Build to Releases
        uses: ncipollo/release-action@v1
        with:
          artifacts: "webapp.zip"
          token: ${{ secrets.GITHUB_TOKEN }}


  publish:
    runs-on: ubuntu-latest
    needs: [build]
    if: always()

    steps:
      - uses: actions/checkout@v1

      - name: Setup Node
        uses: actions/setup-node@v1
        with:
          node-version: 12.x

      - name: yarn install
        run: yarn install
        
      - uses: dsaltares/fetch-gh-release-asset@master
        with:
          repo: "[USERNAME]/[REPO]"
          version: "latest"
          file: "webapp.zip"
          target: "webapp.zip"
          token: ${{ secrets.GITHUB_PAT }}

      - name: create dist directory
        run: mkdir -p dist/webapp

      - name: Decompress
        uses: TonyBogdanov/zip@1.0
        with:
            args: unzip -qq ./webapp.zip -d ./dist/webapp
            
      - name: Run scully
        run: yarn scully

      - name: deploy firebase webapp
        uses: w9jds/firebase-action@master
        with:
          args: deploy --only hosting
        env:
          FIREBASE_TOKEN: ${{ secrets.FIREBASE_TOKEN }}

Conclusion

In this article, we have looked at how we can optimize our Scully build time by splitting Angular builds and Scully builds, where we store our Angular builds and re-use the artifacts in future Scully builds.

This may not be necessary for your application if you are not using tools like purge CSS to remove unused CSS, since Angular builds are usually fast for small to medium size applications.

There are few things I skipped like caching NPM dependencies, which can shave off a few more seconds from your build time and I highly recommend you implement following instructions here.

Links

• Use Webhooks to Trigger GitHub Actions - Link.
• Getting Started with Scully - Link.
• Getting Started with GitHub Actions - Link.
• About GitHub Releases - Link.
• Angular CDK - Platform Module - Link.

For instance, in a blogging platform, you might want to run a workflow to rebuild your statically generated website when the content is updated in a headless CMS. Most headless CMSs will request webhooks which they will send requests to when various events take place. For instance, when a new article is published or an old one is updated, you might want to just trigger a rebuild of your website.

Prerequisite

• GitHub Personal Access Token (PAT) - follow instructions here

NB: Please ensure you have selected the workflow on the scope of the GitHub Personal Access Token (PAT).

Basics First

GitHub actions provides a repository_dispatch event to allow us to manually trigger a GitHub action workflow. To use this, we are going to configure our GitHub action workflow to run on repository_dispatch.

And then, we will specify the types of event upon which they will be triggered by. These event types are user defined and can be anything you wish them to be.

You can learn more about repository_dispatch here.

For instance, here is an example of a GitHub action workflow config which runs when a new blog post is published:

on:
  # publish blog using webhook
  repository_dispatch:
    types: [publish_blog]
 
 # steps

In the case above, we will make a post request to create repository dispatch action endpoint with event_type of publish_blog and that's when the GitHub Action will get triggered and not by any other event type. The event_type allows you to trigger a specific GitHub action workflow.

Triggering the Action

In order to trigger the action above, we are going to send a POST request to the GitHub API endpoint for creating a repository dispatch event. The URL follows the following format:

https://api.github.com/repos/[USERNAME]/[REPOSITORY]/dispatches

Replace the [USERNAME] with your GitHub owner i.e. your username or organization and [REPOSITORY] with the name of the repository.

To specify the GitHub Workflow to trigger, you need to provide event_type in the body. The event_type specified must be listed in the types array section of the repository_dispatch.

NodeJS Example

For this example, we are going to use Got, a Node JS library for sending HTTP requests.

const url = 'https://api.github.com/repos/[USERNAME]/[REPOSITORY]/dispatches';
const githubPAT = "GITHUB_PAT"; // keep this secret
await got.post(url, {
  json: {
    event_type: 'publish_blog',
  },
  headers: {
    Authorization: "token " + githubPAT,
  },
});

NB: Remember to substitute [USERNAME], [REPOSITORY] and GITHUB_PAT with the appropriate values.

The above request is going to trigger all GitHub Actions workflows which are listening to event type publish_blog.

Building a Webhook

Now that we have the basics out, we are going to build a Webhook which we can use to trigger our workflow. While the GitHub dispatch event does qualify to be a webhook, you might want to simplify the API being exposed. This is because some systems where you might want to use the webhook in, will not be that configurable. Some will just give you the option of entering a URL and nothing more, which makes it difficult to use the GitHub Dispatches API directly.

For the purpose of this article, we will be using Firebase Cloud Functions, but any rest endpoint will do. This will expose a public GET endpoint that we can pass an action query param, which will be the type of event we want to trigger and will default to publish_blog. We will use Firebase Functions Config to pass the GitHub PAT to the function.

export const triggerGithubActionWorkflow = https.onRequest(async (req, res) => {
  const dispatchAction = req.query?.action ?? 'publish_blog';
  const url =
    'https://api.github.com/repos/[USERNAME]/[REPOSITORY]/dispatches';
  const githubPAT = config().github.pat;
  await got.post(url, {
    json: {
      event_type: dispatchAction,
    },
    headers: {
      Authorization: "token " + githubPAT,
    },
  });
  res
    .send({
      message: `Dispatch Github action event emitted successfully!`,
    })
    .status(200);
});

NB: The above Firebase function is public and might wise to add some security measures to prevent anyone from triggering your GitHub Action workflow.

Conclusion

In this article, we looked at how we can trigger GitHub Action workflows Webhooks. We used the create repository dispatch GitHub API endpoint to trigger our GitHub Action Workflow and created our own REST Endpoint to act as a Webhook to integrate with third party APIs.

Like I pointed out above, our example could use more security measures to ensure that not just anyone with the REST Endpoint can trigger the GitHub Action Workflow. This will most depend on how the web hook is called, if it's part of a dashboard, you could ensure the user in question has permission to perform the action in question or it could be as simple as using passphrase.

This enables you to identify the platform where your app is running on and modify the behavior of your Angular app appropriately. The CDK Platform Module makes the following information available to you:

• Is Android - Whether the OS is Android
• Is iOS - Whether the OS is iOS
• Is Firefox - Whether the browser is Firefox
• Is Edge - Whether the browser is Edge
• Is Safari - Whether the browser is Safari
• Is Blink - Whether the rendering engine is Blink
• Is Webkit - Whether the rendering engine is WebKit
• Is Trident - Whether the rendering engine is Trident
• Supported Input Types - A list of input form field types supported by the browser i.e. number, password, radio, range, reset, search, submit, tel, text, time, url, etc.
• Whether the browsers supports Scroll Behavior -
• And Whether the browser supports passive event listeners.

Installation

Using yarn:

$ yarn add @angular/cdk

Using NPM:

$ npm install @angular/cdk

Usage

First, we will need to import the PlatformModule from @angular/cdk/platform inside our app module, as shown below:

// other imports
import { PlatformModule } from '@angular/cdk/platform';

@NgModule({
  declarations: [
    AppComponent,
    // ... components
  ],
  imports: [
  	// ... other modules
    PlatformModule,
  ],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

NB: If you are using feature or shared modules, you will need to import PlatformModule inside the module where the component using it is located.

Then, we are going to inject the Platform service into the component where we want to use the platform information.

import { Platform } from '@angular/cdk/platform';
// ... other imports

@Component({
 // ... component metadata
})
export class Component  {
  constructor(private platform: Platform) {}
}

And finally, we can determine the browser platform information as shown below.

this.platform.ANDROID; // check if OS is android
this.platform.FIREFOX // check if Browser is Firefox
this.platform.IOS; // check if OS is iOS
this.platform.BLINK; // check if render engine is Blink
this.platform.isBrowser; // check if the app is being rendered on the browser

For an up-to-date reference for the API, please refer to the official docs here.

Example

We are going to implement a share functionality for our web app, where on mobile devices i.e. iOS and Android, we will use native share while on Desktop, we will use share buttons for each Social Media Platform.

We will use the PlatformModule to determine if the user is on iOS and Android, and then we will use the WebShare API. For other devices i.e. On the desktop, we will just show a simple twitter share button instead. Here is what our component looks like:

import { Platform } from '@angular/cdk/platform';

// ... component metadata
export class CustomSocialShareComponent implements OnInit {
  @Input()
  shareUrl: string;

  @Input()
  title: string;

  @Input()
  text: string;

  @Input()
  hashtags: string;

  tweetShareUrl: string;

  isNativeShareSupported = false;

  constructor(private platform: Platform) {}

  ngOnInit(): void {
    // show native share if on Android and IOS and if it is supported
    this.isNativeShareSupported =
      navigator.share && (this.platform.ANDROID || this.platform.IOS);
    const baseUrl = 'https://twitter.com/intent/tweet';
    this.tweetShareUrl =
      baseUrl +
      '?url=' +
      this.shareUrl +
      '&via=mwycliffe_dev&text=' +
      this.title +
      '&hashtags=' +
      this.hashtags;
  }

  async nativeShare() {
    if (navigator.share) {
      await navigator.share({
        title: this.title,
        text: this.text.substr(0, 200),
        url: this.shareUrl,
      });
    }
  }
}

Our share component above, has a property named isNativeShareSupported - which is a boolean. We are checking whether the current browser supports native share, and the platform is iOS or Android before setting that property to true. And then we can use this property to show the correct UI, as shown below:

<ng-container *ngIf="isNativeShareSupported; else showSocialShareButton">
  <a (click)="nativeShare()" class="space-x-2">
    <span>Share this article</span>
  </a>
</ng-container>

<ng-template #showSocialShareButton>
  Share on this article: <a target="_blank" [href]="tweetShareUrl">Twitter</a>
</ng-template>

Conclusion

In this article, we have learned how to use CDK Platform Module to check the platform details in which our app is running on. This is a simple and quite useful way of modifying the behavior of your Angular app based on the platform being used. This can lead to an improved UX as you can enable enhanced features to users with access to them while providing a decent fallback to users without access to the enhanced features.

Links

• CDK Documentation on Platform Module - Link.
• Integrate with the OS sharing UI with the Web Share API - Link.
• Does not use passive listeners to improve scrolling performance - Link.
• scroll-behavior - Link.
• How to build a reusable Modal Overlay/Dialog Using Angular CDK - Link.
• Building a Custom Stepper using Angular CDK - Link.

Where to start? Let's start by looking at the stack that went into building this blog.

The Stack

To easily manage the content, I went with Ghost CMS, which gives me an effortless way to add, update content. My previous blog was built with Hugo, which uses markdown and as much that was fun to work with initially, the process from writing a post all the way to publishing got exceedingly long and quite tiresome. I found myself posting less and less.

For the frontend, I decided to go with Angular and use Scully to generate static version website for the blog, with Tailwind for the UI. And then, the website itself is hosted on Firebase Hosting.

If you think that's it, then you clearly didn't read the title of this post. Since the website is statically generated, it means the content is fetched at build time instead of REST API request on load. This means that the website doesn't serve live updates or new articles unless it's rebuilt. To solve this problem, I am using web hooks to trigger a CI to do a rebuild and deploy the new site.

Why?

I know what is going on your mind, why go into all the trouble for a simple blog. I could have easily gotten the same or even better results on Medium or WordPress. I don't know what to say, but I enjoy building stuff. Working on this gave me an opportunity to create something and have fun at the same time.

In this case, I got interested in trying out some innovative technologies that otherwise I wouldn't get a chance at work or anywhere else to work with. So, having already an existing blog - codinglatte.com - I had a few requirements I need for a blog.

The first was, I needed an effortless way to add and manage blog posts, a UI quite like what is provided by WordPress or Medium. Ghost CMS provides an easy-to-use UI that's quite intuitive, on top of that, I can easily manage when posts go live via their schedule feature.

The second requirement I had was I needed to be able to add new features on top of the blog. I have dreams for this to evolve beyond a blog to a platform where I can interact and provide move value to my readers. For this I turned to Angular, with Scully for SSG, but this could have easily been Gatsby or Next.JS. The biggest benefit of this is having all the blogs posts and pages, progenerated to static HTML, which would allow the website to load fast and be responsive, while being cost effective.

And lastly, I needed to be able to hit publish and the blog would be re-built, and the recent changes push lived without me having to do anything extra. For this, I turned to GitHub Actions to handle the build process and Ghost CMS Webhooks to trigger the build GitHub Action.

As you can see, this gave me an opportunity to work with a few tools that I could not resist. This was my first foray into Scully, and I could not turn down the opportunity of learning how it works with a real project with potential of being used by thousands of people down.

Conclusion

So, after going through that process, would I do it again? The simple answer for me yes. I have learned a great deal from this, and I am looking to share what I have learned here, among other stuff on this blog. It was fun, challenging and gave me an opportunity to learn and improve my skills.

Would I recommend you do the same? The answer is it depends, as I stated earlier, you can easily get a blog up and learning with medium or some other platform with excellent results, and all you have to think about are the posts themselves.

On the other hand, building out your platform presents you with a lot of flexibility and is quite rewarding when everything is working. It also gives you the opportunity to experiment and learn while working on project that will be used by quite a few people, probably thousands if your blog posts are great.

Improved Stability

I know, this sounds like a moot point but the RxJS team has made some changes on how they release new versions to improve stability.

The RxJS team is partnering with Google, thus ensuring smooth and stable releases. Google will run pre-release versions of RxJS against their mono-repo build targets where RxJS is used widely.

If anything breaks, they work together with RxJS core team to resolve the issues. The goal here is to ensure that releases are as stable as possible especially patch and minor releases which should be safe to update to.

Latest Typescript Version Support

RxJS is adopting features from the latest versions of Typescript. By supporting the latest version of Typescript, we get the following benefits:

Type Inference

Type inference around n-argument is being improved, by allowing TypeScript to do all the type inference. Before, there was a limit of around 8 argument before RxJS could not infer the type anymore, but thanks to TypeScript, this limit no longer exists. This allows RxJS to return an observable whose types closely match the arguments passed.

Union Types Improvements

Unions types are also being improved, ensuring type inference around return types are accurate without needing to explicitly type things.

Fixing Bad Types

Another fix that will be coming along in v7 is for bad types. A good example is the toPromise operator, in v7, it will also return union type alongside the actual type, since if an observable completes without emitting anything, it returns undefined instead of throwing an error. From v7, you will need to check if the returned promise value is undefined before using it.

toPromise Operator is being deprecated

The toPromise operator is getting deprecated in RxJS 7 and will get removed completely in v8. In its place, there are two operators – lastValueFrom() and firstValueFrom(). The lastValueFrom() waits from the last value of an observable before resolving the promise. On the other hand, the firstValueFrom() resolves on the first value from an observable before unsubscribing and resolving the promise.

There are two reasons the operator is being deprecated, the first being, it is unclear to users when the promise resolve and returns undefined instead of throwing an error. The two replacement operators will throw an empty error if the observable completes without a value. The toPromise() operator would have returned undefined instead of throwing an error. The second reason is that they are more explicit on when the promise resolves i.e. whether it is the first value or the last value that will be resolved.

Before:

const numbers$ = of(1,2,3,4,5)

// toPromise() will return the last value of the observable
numbers$.toPromise().then(n => console.log("toPromise(): " + n))

After:

const numbers$ = of(1,2,3,4,5)

// lastValueFrom() will return the last value just like to promise
lastValueFrom(numbers$).then(n => console.log("lastValueFrom(): " + n))

// firstValueFrom() will return the first value of the observable
firstValueFrom(numbers$).then(n => console.log("firstValueFrom(): " + n))

new animationFrame() method

animationFrame() is a new static method that fires an observable that gives the amount of time elapsed in milliseconds since the start of the observable. This provides a method to measure the progress of an observable without the need of a deeper understanding of how RxJS works under the hood. With animationFrame(), you can control the animation of an object using RxJS.

Consuming AsyncIterable Support

AsyncIterable objects are now fully supported in an array of RxJS operators and will be accepted anywhere where an observable or a promise is accepted.

Take for instance the following range object:

const range = {
  from: 1,
  to: 5,

  [Symbol.asyncIterator]() { // (1)
    return {
      current: this.from,
      last: this.to,

      async next() { // (2)
        await wait(1000);
        if (this.current <= this.last) {
          return { done: false, value: this.current++ };
        } else {
          return { done: true };
        }
      }
    }; 
  }
};

We can consume the above AsyncIterable object as follows:

from(range).subscribe(x => console.log(x))

Example:

NB: You can use the rxjs-for-await library by Ben Lesh to make your observables compatible with AsyncIterables.

Renamed Operators

Some of the legacy operators including deprecated ones that has the same names as their creation methods, have been renamed to reduce collision. This has been done by adding with at the end of the operators. For instance, the following operators: zip, combineLatest, merge, concat have been renamed to zipWith, combineLatestWith, mergeWith, concatWith.

NB: The Deprecated operators with be removed in the next major version of RxJS.

new resetOnSuccess option for retry

A new option called resetOnSuccess has been added to the retry options, which lets you reset the counter back to zero whenever it’s successful. In version 6, the counter is never reset and if the retries becomes successful for a while and then start failing, it would pick up where it left. This would lead the retries being exhausted faster in subsequent retries.

retry({
  count: 5, 
  resetOnSuccess: true 
})

Reducing Scheduler Footprint

Some operators include the Scheduler which means the Scheduler ends up within your final bundle even if you are not using it. The goal is to ensure that extra code from the Scheduler ends up in your final bundle when you explicitly need it.

To Achieve this, a new TimeStampProvider has been added that has a now method in it. This allows the third argument of the replaySubject to be defaulted to the date objected, which is native and does not need to be shipped. You can override this by passing any object that has a now method. RxJS will continue over the course of v7 to try and reduce the bundle size that is shipped with your application in non-breaking ways.

Scheduler Arguments are being Deprecated

Passing Scheduler arguments is being deprecated, instead you should switch to scheduled() or observeOn() APIs. The Scheduler arguments are not going to disappear completely but will be retained in operators that still need them such as timer and interval.

Removing Subscription and Tap Callback Options

Passing multiple callback methods when subscribing or tapping to an observable will be deprecated. From v7 onwards, you can use a single callback or an object with data, error, and complete fields for respective callbacks. By removing the multiple callback option, most of the logic that goes to determine which callback method you used can be removed. This will lead to a leaner and faster RxJS library.

Deprecated:

source$.pipe(tap(
  data => console.log(data),
  error => console.log(error)
)).subscribe(
  data => console.log(data),
  error => console.log(error)
)

The following are acceptable:

Passing a single callback:

source$.pipe(tap(
  data => console.log(data)
)).subscribe(
   data => console.log(data)
)

Passing an object with multiple callbacks:

source$.pipe(
  tap({ 
    next: data => console.log(data),
    error: e => console.log(e)
  })
).subscribe(
  {
    next:  data => console.log(data), 
    error:  err => console.log(err),
  }
)

subscription.add() returns a void

subscription.add() is used to put together multiple subscriptions so that you can unsubscribe to all of them together. in v6, you could chain subscription.add() when adding multiple subscription. The API for chaining is being removed as it led to inconsistent un-subscription behavior.

In v7, you will have to add the subscriptions one at a time.

Beyond v7.0

Version 7.1

In line with semantic versioning, v7.1 is a minor change with non-breaking features and improvements. We are likely to see the following in v7:

ESLint Rules and Transformations - This is expected in v7.1 and the goal is to help developer to gradually remove and replace deprecated operators that will be removed. There will also be minor improvements and a lot of preparation for version 8.

Version 8

In v8, we will see the deprecations where the team was able to add ESLint code transformations removed. This is to ensure that developers have an uncomplicated way of replacing deprecated APIs and are following the best practices. On top of that, there are some experiments being done by the RxJS team in progress and the impact is a smaller bundle size, in some cases, as small as 40% of the current size. RxJS is also going try and keep up with the latest versions of Typescript and JavaScript, whenever it is possible.

Additional Resources

• Rxjs + For + Await… What? - RxJS inDepth
• Async iteration and generators
• for await...of
• The State of RxJS by Ben Lesh

This is going to be the first of a few articles, focusing on ways you can
utilize Angular CDK to implement common interaction patterns within your
application.

Demo and Source Code

You can find the link to the demo here and the GitHub repo for this post here.

Prerequisites

Install Angular CLI and create a new Angular project – link.

Setup Bulma inside your Angular Project.

Install Angular CDK – npm i @angular/cdk or yarn add @angular/cdk

The article is divided into two sections:

• The Basics - a Quick look at how to use Angular CDK Overlay
• Building a Reusable Modal Overlay - A detailed guide into building a reusable
  modal overlay.

The Basics

Let us get the basics out of the way first. Assuming you have installed Angular CDK you will need to import OverlayModule into your app module.

import {OverlayModule} from '@angular/cdk/overlay';

And then, inject the Overlay service and ViewContainerRef into your component.

constructor(private overlay: Overlay, private viewContainerRef: ViewContainerRef) {}

To show a modal overlay, you need either a Template or an Angular Component holding the content you would like to show. Let’s look at how you can use both below:

Using a Template

Inside the template of our component, let’s define a new template and add our overlay content:

<ng-template #tpl>
  <div class="modal-card">
  <header class="modal-card-head">
    …
  </header>
  <section class="modal-card-body">
    …
  </section>
  <footer class="modal-card-foot">
    …
  </footer>
 </div>
</ng-template>

Then, add a method to show the overlay and it accepts an ng-template reference as the parameter.

openWithTemplate(tpl: TemplateRef<any>) {}

Then, Inside the above method, we are going to create an overlay. We will start by defining the configs of the overlay – OverlayConfig. In our case, we will just set the hasBackdrop and backdropClass properties. For backdropClass we are using modal-background a Bulma CSS Framework class. You can find all the Overlay Configurations you can add here.

const configs = new OverlayConfig({
 hasBackdrop: true,
 panelClass: ['modal', 'is-active'],
 backdropClass: 'modal-background'
});

NB: For backdrop click to dismiss the modal overlay to work, you might need
to disable pointer-events for your modal, for some CSS Frameworks like
Bulma. This is because CDK Overlay doesn't add them to DOM in the nested order
of modal ➡ modal-background ➡ modal-content, but rather modal ➡ modal-content, while the backdrop is a separate div tag not nested under
modal, but on a level above modal class div tag.

For Bulma CSS framework case, you can override the default behavior like this:

.modal {
  pointer-events: none !important;
}

.modal-content {
  pointer-events: all !important;
}

Then, let’s create an OverlayRef, by using the create method of the Overlay service and pass the configs we just created above:

const overlayRef = this.overlay.create(configs);

And then we can attach our template, using TemplatePortal, passing our template and ViewContainerRef which we injected into our component:

overlayRef.attach(new TemplatePortal(tpl, this.viewContainerRef));

Now, we can trigger the method with a click of a button:

<button (click)="openWithTemplate(tpl)" >
 Show
</button>

Using a Component

The difference between the two is that we will be using ComponentPortal instead of TemplatePortal to attach the component to the OverlayRef.

this.overlayRef.attach(
 new ComponentPortal(OverlayComponent, this.viewContainerRef)
);

NB: The component must be added to the list of entryComponents in your App Module.

Closing Modal Overlay on Backdrop Clip

You can close the overlay when the backdrop is clicked by subscribing to the backdropClick() and then calling the dispose method.

overlayRef.backdropClick().subscribe(() => overlayRef.dispose());

Making a Re-usable Modal Overlay

Building modal overlays as shown above works very well if you are building one or two of them, however, it does not really scale very well. Wouldn’t it be nice if you could build a re-usable modal overlay that you can then use across your Angular project or projects? Wouldn’t it also be nice if we could be able to pass data to and receive data from the modal?

Objective

A service to open the modal, than can be injected into any component

A way to subscribe to when the modal is closed and access the response.

Pass data to the modal

Pass data as a String, Template or Component.

Overlay Ref Class

We are going to start by extending the OverlayRef. We will create a custom OverlayRef, creatively named MyOverlayRef, which is going to accept the OverlayRef, content and the data to pass to our modal overlay. The content can be of type string, TemplateRef or Component.

// R = Response Data Type, T = Data passed to Modal Type
export class MyOverlayRef<R = any, T = any> {
 …
 constructor(public overlay: OverlayRef, public content: string | TemplateRef<any> | Type<any>, public data: T ) {
  …
 }
 …
}

Then, Inside the MyOverlayRef class, we are going to add a BehaviorSubject property named afterClosed$ which we can subscribe to get data once the overlay is closed.

afterClosed$ = new Subject<OverlayCloseEvent<R>>();

The behavior subject is going to pass back an OverlayCloseEvent, which contains the data from modal and how the modal was closed. Feel free to modify this to cover your needs.

export interface OverlayCloseEvent<R> {
 type: 'backdropClick' | 'close';
 data: R;
}

Next, we need to add a private method to close the overlay. The method will dispose off the overlay, pass the OverlayCloseEvent back to the subscriber and complete the afterClosed$ Observable.

private _close(type: 'backdropClick' | 'close', data: R) {
  this.overlay.dispose();
  this.afterClosed$.next({
   type,
   data
  });

  this.afterClosed$.complete();
 }

And then, we are going to add a second public close method. It will only accept data as a parameter and will call the private _close method, to close the modal.

close(data?: R) {
 this._close('close', data);
}

And finally, we are going to subscribe to backdropClick and close the modal when clicked. We are adding this subscriber to the MyOverlayRef constructor.

overlay.backdropClick().subscribe(() => this._close('backdropClick', null));

Overlay Component

Next, we are going to add a special component that we will use to show our modal content. If it is a simple string, we will bind it to a div, while we can use either ngTemplateOutlet and ngComponentOutlet to load the template and component respectively.

Component Class

We are going to start by injecting an instance of our MyOverlayRef into the component.

constructor(private ref: MyOverlayRef) {}

And then, let’s define 3 more properties inside our component class:

contentType: 'template' | 'string' | 'component' = 'component';
content: string | TemplateRef<any> | Type<any>;
context;

Then, OnInit, we need to determine the content type and set the above properties appropriately.

ngOnInit() {
  if (typeof this.content === 'string') {
   this.contentType = 'string';
  } else if (this.content instanceof TemplateRef) {
   this.contentType = 'template';
   this.context = {
    close: this.ref.close.bind(this.ref)
   };
  } else {
   this.contentType = 'component';
  }
}

And finally, we are going to be adding a global close button, so let’s add a close method:

close() {
 this.ref.close(null);
}

And finally, remember to add the Overlay component as an entryComponent in your app module.

Component Template

In the template, we are going to use ngSwitch to switch between content type and add a global close button for our modal.

<div class="modal-content">
 <ng-container [ngSwitch]="contentType">
  <ng-container *ngSwitchCase="'string'">
      <div class="box">
        <div [innerHTML]="content"></div>
   </div>
  </ng-container>
  
  <ng-container *ngSwitchCase="'template'">
   …
  </ng-container>

  <ng-container *ngSwitchCase="'component'">
   …
  </ng-container>
 </ng-container>
</div>

<!-- You can also add a global close button -->
<button (click)="close()" class="modal-close is-large" aria-label="close"></button>

For template content type, we will use ngTemplateOutlet, passing the template, which is the content and then pass the context:

<ng-container *ngTemplateOutlet="content; context: context"></ng-container>

And while for component content type, we will use ngComponentOutlet, passing the Component, which is the content:

<ng-container *ngComponentOutlet="content"></ng-container>

The Overlay Service

Next, we are going to create an Overlay service, which we can inject into any component we want to use our modal overlay. Where we are going to inject Overlay Service and the Injector.

export class OverlayService {
  constructor(private overlay: Overlay, private injector: Injector) {}
}

Then, add an open method, which will accept content and data. The data param, in this case, is the data you would like to pass to your modal.

open<R = any, T = any>(
 content: string | TemplateRef<any> | Type<any>,data: T): MyOverlayRef<R> {
 …
}

Inside the method, first, we need to create an OverlayRef object by using the Overlay create method. Feel free to customize the configs to suit your needs.

const configs = new OverlayConfig({
 hasBackdrop: true,
 panelClass: ['modal', 'is-active'],
 backdropClass: 'modal-background'
});

const overlayRef = this.overlay.create(configs);

Then, let’s instantiate our MyOverlayRef Class passing the OverlayRef object we created above, then content and the data, both from the method parameters.

const myOverlayRef = new MyOverlayRef<R, T>(overlayRef, content, data);

Create an injector using PortalInjector, so that we can inject our custom MyOverlayRef object to the overlay component, we created above.

const injector = this.createInjector(myOverlayRef, this.injector);

And finally use ComponentPortal, to attach the OverlayComponent we created above and the newly created injector and return a MyOverlayRef object.

overlayRef.attach(new ComponentPortal(OverlayComponent, null, injector));
return myOverlayRef;

And here is the method for creating a custom injector using PortalInjector:

createInjector(ref: MyOverlayRef, inj: Injector) {
 const injectorTokens = new WeakMap([[MyOverlayRef, ref]]);
 return new PortalInjector(inj, injectorTokens);
}

And that’s it, we now have a re-usable modal overlay, that we can use anywhere inside our application.

Usage

First, inject the Overlay Service in the component where you would like to open a new modal overlay.

constructor(private overlayService: OverlayService) {}

Then, inside the method you would want to trigger the modal overlay, you just
use the open method and pass the content and any data you want to pass to the
modal overlay.

const ref = this.overlayService.open(content, null);

ref.afterClosed$.subscribe(res => {
 console.log(res);
});

The content can be a simple string or a Template or a Component.

String

const ref = this.overlayService.open("Hello World", null);

Template

<ng-template #tpl let-close="close">
  <div class="modal-card">
  <section class="modal-card-body">
   A yes no dialog, using template
  </section>
  <footer class="modal-card-foot">
   <div class="buttons">
    <button (click)="close('yes')" type="button" class="button is-success">Yes</button>
    <button (click)="close('no')" type="button" class="button is-danger">No</button>
   </div>
  </footer>
 </div>
</ng-template>

And a button to open the modal:

<button (click)="open(tpl)" class="button is-small is-primary">
 Show
</button>

And then open the overlay with an open method:

open(content: TemplateRef<any>) {
 const ref = this.overlayService.open(content, null);
 ref.afterClosed$.subscribe(res => {
  console.log(res);
 });
}

Component

open() {
 const ref = this.overlayService.open(YesNoDialogComponent, null);
 ref.afterClosed$.subscribe(res => {
  console.log(res);
 });
}

You can also inject the MyOverlayRef inside the component to access data and the close method.

constructor(private ref: MyOverlayRef) {}

This allows you to pass data to the component and trigger the closing of the modal from within the component.

close(value: string) {
 this.ref.close(value);
}

NB: Please remember to add the component as an entryComponent inside your App Module.

You can find all of the above code here and the demo here.

Additional Resources

• Angular Component Development Kit (CDK)
• Creating Powerful Components with Angular CDK
• API reference for Angular CDK overlay
• Angular ng-template, ng-container and ngTemplateOutlet - The Complete Guide To Angular Templates

Infinite scrolling is a technique where loading of content is done continuously as the user scrolls down, without any action from the user. This has popularized by social media sites and apps such as Twitter, where Twitter loads more tweets as you scroll down. This is a form of pagination but requires no user input to load the next page but instead watches scroll position. When they get close to the end, the next bunch of tweets gets loaded, as shown below:

Prerequisite

• Flutter Installation and Setup – Link.

Creating a ListView

We are going to start by creating a ListView to display GitHub Repositories. We will use the GraphQL package for flutter and will load then in bunches of 20. We are also going to display a loading animation when adding fetching new GitHub repositories.

ListView(
  children: <Widget>[
    for (var repository in repositories)
      // .. list of widgets
    if (result.loading)
      Row(
        mainAxisAlignment: MainAxisAlignment.center,
        children: <Widget>[
          CircularProgressIndicator(),
        ],
      ),
  ],
),

Use ScrollController to Detect Scroll Position

Next, we need to determine when to load more GitHub Repositories, i.e. when we are at or near the bottom of the list view. To achieve this, we are going to use ScrollController – Link. We are going to listen to ScrollController, which will let us know whenever we scroll. We can then check if we are at the end or near the end of ListView, and in that case, we load more Repositories.

We will start by declaring a new widget property, named _scrollController.

class Widget extends StatelessWidget {
  // ...
  
  ScrollController _scrollController = new ScrollController();

  @override
  Widget build(BuildContext context) {
    // ...
  }
}

Then, we need to attach our ScrollController to our ListView above.

ListView(
  controller: _scrollController,
  children: <Widget>[
    // ... widgets
  ],
),

And finally, we need to listen to ScrollController and check where the user is at scrolling.

_scrollController
  ..addListener(() {
    if (_scrollController.position.pixels ==
        _scrollController.position.maxScrollExtent) {
      // ... call method to load more repositories
    }
  });

From the above code, we are waiting until the scroll position is at the very end. This might not be convenient for you and you might want to trigger the method to fetch more items earlier, let’s say at 90%.

_scrollController
  ..addListener(() {
    var triggerFetchMoreSize =
        0.9 * _scrollController.position.maxScrollExtent;

    if (_scrollController.position.pixels >
        triggerFetchMoreSize) {
      // call fetch more method here
    }
  });

Final Thoughts

This is a simple way to implement infinite scrolling inside a ListView in flutter. You can find the above demo in my GitHub account here.

Additional Resource

• GraphQL Package for Flutter – Link.
• ListView API Reference – Link.
• ScrollController API Reference – Link.
• GitHub GraphQL Explorer – Link.