Forem: Fabrizio Duroni

A Domain Driven Design dictionary for newbies

Fabrizio Duroni — Fri, 25 Jun 2021 13:31:39 +0000

In the last months, I started to hear a lot of stuff about Domain Driven Design. What is DDD? What does it try to solve? This is a post for all the newbies (like me) that are searching for a definition of what DDD is, which are its main parts and what is its main goal.

In the last months the main focus of my daily job at lastminute.com group was the existing refund process development in order to support our customer hit by the COVID-19 pandemic. While I’m still working (a lot 😆)on it, I also had the opportunity to participate in the start up of a new project (anyway, still related to the refund stuff 😅). In this new project we decided to take leverage of the power of DDD to approach the problem we need to solve. In my mind I said: ”Ok, let’s do it”, but then I started to think: ”What the f%*§ is this DDD? I do know nothing about it” 😅.

This is why I recently attended the video course “Domain Driven Design Distilled”by Vaughn Vernon, one of the top expert about DDD. In this post I will try to share with you what I learnt about DDD and I will try to give you the best (opinionated) definition of DDD and of all its parts.

DDD

So let’s start from the basis. What is DDD? DDD is a set of tools that help an organisation to model software around its business model. Generally speaking a company CAN’T be the best at everything. The DDD tools help organizations to better understand their business and to choose at what they should excel. In this way through DDD an organization can implement
what is usually called Effective Design to develop its software. Its main features are:

The final design meets the needs of the business to distinguish itself from the the other competitors.
Force the organization where it should excel.

For the second point, I would like to quote a phrase from the Vernon DDD distilled course:

..An organization that works in the insurance industry, should try to be the best insurance company in that particular insurance area it operates. But it can’t be the best database company as well, or it can’t be the framework company, it can’t be the best accounting comparing as well an so on…

I think the statement above describes the needs of about 99% percent of the business I worked for in the last 13 years 😳.

The DDD tools that will let you implement effective design are divided in two main phases:

Strategic design
Tactical design

Let’s see each one of them in details.

Strategic design

Strategic design is the first phase of DDD. With a set of specific tool strategic design will let you highlight what is better important for your business. In this phase your domain models will be divided into smaller units, and they will be prioritized in terms of analysis/development efforts based on their importance. Strategic design is based primarily on two tools:

Bounded context
Ubiquitous language

Let’s see them in details.

Bounded Context and Ubiquitous language

Let’s start from the definition of Bounded Context from the Vaughn Vernon course:

…a Bounded Context is a semantic contextual boundary. This means that within the boundary each component of the software model has a specific meaning and does specific things. The components inside a Bounded Context are context specific and semantically motivated…

From the definition (and also from the name itself 😆 ) a bounded context is a specific limit boundary within a software model. Inside a bounded context everything is explicit about the model. The software model inside a bounded
context is created using terms from a language developed but the team working on the it. This language is called Ubiquitous language and its main features are:

It should be rigorous and non ambiguous
It should be understood by all the team members

Usually the team that is working on a bounded context should work strictly with a business domain expert to better define the ubiquitous language and to avoid mixing up concepts from different Bounded Context. Below you can find Vernon definition of what a Ubiquitous languages is.

…The software model inside the context boundary reflects a language that is developed by the team working in the Bounded Context and is spoken by every member of the team that creates the software model that functions within that Bounded Context. The language is called the Ubiquitous Language because it is both spoken among the team members and implemented in the software model…

How many bounded context will your project have? How do they map to your business domain parts. Let’s answer to these question with Subdomain

Subdomains

Let’s start as always from the Vernon definition of what a subdomain is.

…a Subdomain is a sub-part of your overall business domain. You can think of a Subdomain as representing a single, logical domain model. Most business domains are usually too large and complex to reason about as a whole, so we generally concern ourselves only with the Subdomains that we must use within a single project. Subdomains can be used to logically break up your whole business domain so that you can understand your problem space on a large, complex project.

Another way to think of a Subdomain is that it is a clear area of expertise, assuming that it is responsible for providing a solution to a core area of your business. This implies that the particular Subdomain will have one or more Domain Experts who understand very well the aspects of the business that a specific Subdomain facilitates. The Subdomain also has greater or lesser strategic significance to your business...

In DDD, a subdomain maps tot a single bounded context. The domain expert of a particular subdomain are an active part of the team in charge of the related bounded context. There are 3 types of subdomains:

Core domain: the most important subdomain of your organization. This is what differentiate your company from the competition in terms of business features. This is the domain where an organization will invest most of its energy and resources.
Supporting subdomains: this is a subdomain where the organization should invest in terms of development effort because there isn’t an existing software solution that covers the business needs. Anyway this subdomain is not as important as the Core Domain from a strategical point of view. This is way this kind of development are usually outsourced to external companies in order to avoid putting too much effort and resources on it.
Generic subdomains: this kind of subdomains includes needs where a software solution is already available to be purchased without the needs for any development efforts.

From the definition above it should be clear that every software project will have multiple subdomains and bounded
context. How do you integrate them together?

Context mapping

Context mapping lets you integrate different bounded contexts. It is the translation between them. It is important to evaluate the “translation” trade off when a context mapping is required. This is usually related to the type of relation between bounded context we would like to achieve. In particular its important to consider the real needs of a relationship two bounded contexts. There are various types of context mapping:

Partnership: two teams of two different bounded context have a partnership relation. The teams are synchronized on goals and schedules. Usually a Partnership context mapping is defined for a limited time period.
Shared Kernel: the teams share a common model. It is not easy to be successful in this kind of context mapping. It requires an high commitment in terms of shared agreement between the teams.
Customer-Supplier: as the name implies, the teams work in a “customer supplier” way. It’s important that the supplier understand the real needs of its customer in order to avoid an evolution of the model not needed by the customer.
Conformist: one of the team from in a relation conforms to the existing model of another team in another bounded context.
Anticorruption layer: a translation layer is created between the communication of teams from different bounded context. In this way the teams that receive the information could adapt them based on the their specific business needs. It should be used whenever possible.
Open Host Service: similar to Anticorruption layer but without the translation layer. In this case a team A uses the APIs from a team B, and the business model inside it, without any translation.
Published language: a well defined language is defined in order to enable the consumption of a model from a bounded context from the other bounded contexts. Usually you can use some well know format like XML, JSON, Avro, Protobuf etc. to defined the published language.
Separate ways: last but not least, you can use decide to not integrate with another bounded context and create your own specialized solution (eg. a new solution in your own bounded context is much more simple to create than the integration with another bounded context).

Tactical design

In the previous paragraph we explored all the details of Strategic Design. At this point I think it’s clear that Strategic Design is an high level design phase, because it lets you define the subdivision of your domain and of your software model without entering into details. In particular, at this point with strategic design we defined all our bounded contexts but not what live inside them. All the details of the bounded contexts are defined in the Tactical Design phase.

What are the details we want to define during the Tactical Design? We would like to define the concepts contained in a bounded context. This are usually represented as Aggregates.

Aggregates

An aggregate is a set of domain objects, usually called Entities and Value Objects, that are considered as a single item inside our bounded context. One of the entities that make up the Aggregate is called the Aggregate Root or Root Entity. This entity owns all the others inside the aggregate. Value objects are used, as the name implies, to represent values.
We can have a look at Vernon definition that I think is enough clear.

A Value Object, or simply a Value, models an immutable conceptual whole. Within the model the Value is just that, a value. Unlike an Entity, it does not have a unique identity, and equivalence is determined by comparing the attributes encapsulated by the Value type. Furthermore, a Value Object is not a thing but is often used to describe, quantify, or measure an Entity.

The most important feature of aggregates is that they represents transactional boundaries. Again let’s quote Vernon to understand the meaning of this concept.

…Aggregate forms a transactional consistency boundary. This means that within a single Aggregate, all composed parts must be consistent, according to business rules, when the controlling transaction is committed…

Simple and clear. All the parts of an aggregate must be consistent when saved. So they should be saved in a single “transaction”. In this case the concept of transaction is much more broader than the one usually related to database. In fact the type of transaction used to save your aggregate is an implementation details. It could be a database transaction, or could be something implemented using Reactive programming events/messaging.

There are 4 rules of thumb reported by Vernon to be considered when you’re creating aggregates:

Let’s try to analyze them. The first one refer to the fact that is the business should determine Aggregate anatomy based on what should be consistent when a transaction is committed.

The second one is easy (and common in computer science 😆): keep your aggregates small in order to reduce memory footprint and complexity. The third one also is simple and clear: aggregates should reference each other by identity fields in order to (again) reduce memory footprint but also, and more important in this case, enforce the transactional boundary that each aggregate represents.

Last but not least the eventual consistency update rule. As we already said, aggregates are transactional boundaries.
How do we signal that another aggregate should be updated when another one finished its update transaction. We can use a messaging mechanism in order to guarantee that after the transaction on one aggregates, others should be updated too.
For this scope Domain Events come to rescue us.

Domain Events

Let’ quote (again 😆) the Vernon definition of Domain Events.

A Domain Event is a record of some business-significant occurrence in a Bounded Context.

So domain events are the fundamentals of communication between aggregates in order to keep them eventual consistent between each other. When creating domain events we should put a lot of attention to decide its name: should be a statement of a past occurrence, that is, a verb in the past tense, that describe what happened in the aggregate that originated the event. The combination of the Domain Event’s name and its properties are the record of what happened in the domain model. Domain events are usually stored with its aggregate. It’s important to save them together in the same transaction. Should domain events contain additional data? Yes, but as Vernon says we must be careful to not fil them with too much data

…there are times when a Domain Event can be enriched with additional data. This can be especially helpful to consumers that don’t want to query back on your Bounded Context to obtain additional data that they need. Even so, you must be careful not to fill up a Domain Event with so much data that it loses its meaning…

As we said above domain events should be saved while updating aggregates. This is useful in order to have a clear understand of what happened to an aggregates. We can also use them to implement event sourcing.

Event sourcing

Event sourcing is a technique where an aggregate current state is reconstructed by applying in temporal order all the domain events related to an aggregate. Let’s take a look at the explanation from Vernon:

Event Sourcing can be described as persisting all Domain Events that have occurred for an Aggregate instance as a record of what changed about that Aggregate instance. Rather than persisting the Aggregate state as a whole, you store all the individual Domain Events that have happened to it. Let’s step through how this is supported.

All of the Domain Events that have occurred for one Aggregate instance, ordered as they originally occurred, make up its event stream. The event stream begins with the first Domain Event that ever occurred for the Aggregate instance and continues until the last Domain Event that occurred. As new Domain Events occur for a given Aggregate instance, they are appended to the end of its event stream. Reapplying the event stream to the Aggregate allows its state to be reconstituted from persistence back into memory. In other words, when using Event Sourcing, an Aggregate that was removed from memory for any reason is reconstituted entirely from its event stream.

Event sourcing has a lot of advantages, from a business point of view and from the developer point of view. One of the greatest advantages of using it from the business point of view is that you have historical data that you can use for many reasons, ones that you can imagine today, such as compliance and analytics, and ones that you won’t realize until later. For developers it can enable them to use event streams to examine usage trends and to debug their source code.

Conclusion

If you came until here I hope you enjoyed the read, but more important that you found the answers you were searching for. If this post didn’t clarify your doubts, let me know in the comments, so that I can try to add what is missing and improve it. 😘

Originally published at https://www.fabrizioduroni.it on June 6, 2021.

Swift Package Manager: bundling resources with a Swift Package

Fabrizio Duroni — Mon, 14 Dec 2020 18:28:36 +0000

Recently I upgraded my ID3TagEditor swift package to the latest Swift tools version (5.3). During the upgraded I discovered that now you can bundle reources with your Swift package. In this post I will show you how you can do this, and also a interesting trick in order to be able to build a project as a Swift Package and as a standard project from Xcode.

In the last weeks I started to work again on my ID3TagEditor library. Before starting to add new interesting features (do you wanna see the roadmap? check the kanban board or the milestones) I did the usual upgrade to the latest build tools released in the new Xcode 12. One new interesting feature included in this release ( Swift tools version 5.3) is the ability to bundle resources with a Swift package. Before this release to bundle resources in a Swift package you had to use weird tricks and hackings. So let's see how you can add the suppport for bundling resources by using my ID3TagEditor library as example.

Specifically, I will show you how I can execute all my test suite, including some acceptance tests that uses mp3 and images resources to check the correctness of the ID3 tag added by ID3TagEditor.

Implementation

To support the bundling of resources, the first thing to do is to upgraded the swift tools used to build your package. To do this, you just need to change the comment at the top of the Package.swift.

// swift-tools-version:5.3

//...other code

In my ID3TagEditor I have some acceptance tests that uses some mp3 files and some images that I use to check that ID3TagEditor works as expected. Before the Swift tools 5.3 I was disabling these tests on the Linux platform (that supports only the SwiftPM way to bundle libraries). Now there's a new Swift package targets(...) and testTargets(...) function parameter called resources that you can use to load resources.

The resources parameter takes as value a list of resource process rules as input. You can choose between two type of rules:

process rule. You can create this rule by using the static func process(_ path: String, localization: Resource.Localization? = nil) -> Resource function (you can find the offical documentation here). This rule let you process the resource according to the platform you’re building the package for. This basically means that the build tools will optimize some files based on the type and the platform (e.g. images will be optimized if the target platform is iOS). You can also support different rules based on different locale/languages.
copy rules. You can create this rule by using the static func copy(_ path: String) -> Resource function (you can find the offical documentation here). This rule let you bundle your resources as they are without any optimization.

Both rule functions above accept a _ path: String parameter. This could be:

a path to a specific file
a path to a specific folder

Given all this information I was ready to add the resources to my test target and enable the acceptance tests for the SwiftPM build (so now they were available on Linux too ☺️). So I added the resources parameter to the testTarget call of my ID3TagEditor. The input value is a an array with just 1 rule: a process rule that takes as parameter the Examples folder, that is the place where I have all the resources (mp3 and images) used by the ID3TagEditor acceptance tests. Below you can find the complete Packages.swift file.

// swift-tools-version:5.3

import PackageDescription

let package = Package(
    name: "ID3TagEditor",
    products: [
        .library(
            name: "ID3TagEditor",
            targets: ["ID3TagEditor"]
        )
    ],
    dependencies: [],
    targets: [
        .target(
            name: "ID3TagEditor",
            dependencies: [],
            path: "./Source",
            exclude: ["Info.plist"]
        ),
        .testTarget(
            name: "ID3TagEditorTests",
            dependencies: ["ID3TagEditor"],
            path: "./Tests",
            exclude: ["Utils/PathLoaderXcodeProj.swift", "Info.plist"],
            resources: [.process("Examples")]
        )
    ],
    swiftLanguageVersions: [.v5]
)

Now the question is: how do you use/load the resources bundled with your target? When you build a Swift Package the build tools will automatically generate a resource_bundle_accessor file. This file exposes a new Bundle.module property that contains the bundle available for the package based on the environment you're building the source code:

if you build the package when is linked to the app, Bundle.module will contain the Bundle.main.resourceURL
if you build the package when is linked to a framework, Bundle.module will contain the Bundle(for: BundleFinder.self).resourceURL
if you build the package from the command line, Bundle.module will contain the Bundle.main.bundleURL

import class Foundation.Bundle

private class BundleFinder {}

extension Foundation.Bundle {
    /// Returns the resource bundle associated with the current Swift module.
    static var module: Bundle = {
        let bundleName = "ID3TagEditor_ID3TagEditorTests"

        let candidates = [
            // Bundle should be present here when the package is linked into an App.
            Bundle.main.resourceURL,

            // Bundle should be present here when the package is linked into a framework.
            Bundle(for: BundleFinder.self).resourceURL,

            // For command-line tools.
            Bundle.main.bundleURL,
        ]

        for candidate in candidates {
            let bundlePath = candidate?.appendingPathComponent(bundleName + ".bundle")
            if let bundle = bundlePath.flatMap(Bundle.init(url:)) {
                return bundle
            }
        }
        fatalError("unable to find bundle named ID3TagEditor_ID3TagEditorTests")
    }()
}

So in the case of ID3TagEditor, when I open and build it as a Swift Package from Xcode or build it from the command line the Bundle.module will contain the correct bundle. As a consequence I can call Bundle.module.path(forResource: <resource name>, ofType: <file type>) to get the path to the resources bundled with the ID3TagEditor test target and load/use them in my tests. In fact I created a PathLoader class that I use in my acceptance tests to load my test resources.

import Foundation

class PathLoader {
    func pathFor(name: String, fileType: String) -> String {
        return Bundle.module.path(forResource: name, ofType: fileType)!
    }
}

Below you can find a screenshot that shows the successful execution of the tests after opening the ID3TagEditor as a Swift Package from Xcode.

There's still one problem with this setup. ID3TagEditor is configured also as a Xcode workspace, because there are some related demo app that are contained in the repository and I need a way to manage them while developing the library. If I try to build the ID3TagEditor from the workspace view it will not compile. Why? Because resource_bundle_accessor file (the one I shown you above) is not automatically generated if you build the swift package as project of a workspace and the PathLoader class I shown you above contains the error Type 'Bundle' has no member 'module'. What can I do? I simply created a new version of the PathLoader class that gets the bundle correctly using the Bundle(for: type(of: self)) constructor where self is the test class that is calling the PathLoader. Then I removed the from the tests target the file that contains the PathLoader implementation for the SwiftPM build tools and I added to them only the new implementation, that I putted in a separated file called PathLoaderXcodeProj.swift. On the contrary in the Packagkage.swift above you can see that I excluded from the test target the implementation used by Xcode (see exclude: ["Utils/PathLoaderXcodeProj.swift", "Info.plist"],). In this way I'm able to run all my tests without any error. Below you can find some screenshot with the setup I have just described to you.

Conclusion

You can find more details about SwiftPM and bundling resources with it in the official Apple documentation. As you can see Apple is investing a lot of resources in improving its build tools ecosystem and make the life of developers easier. Even if I still hope that Apple will finally fully embrace PWA (so that a lot of useless shitty apps that can be web apps can disappear 😏), it's good to see that developers (of true useful native apps 😁) will enjoy in using these new tools to build their apps 😍.

Originally published at https://www.fabrizioduroni.it on October 19, 2020.

Create a service worker with Workbox, Webpack and TypeScript

Fabrizio Duroni — Mon, 14 Dec 2020 18:21:35 +0000

Recently I migrated my website to Webpack and TypeScript. I decided also to give a try to Workbox, a set of Google libraries to improve the creation of a Progressive Web App. Let's see how easy it is to create a PWA with this tools.

I already talked extensively in some previous post about what a progressive web app is and how it can improve the user experience of your website. In the first development iteration I create the service worker that runs on this website without any kind of library or framework to support. This enabled me to learn the fundamental of PWAs: how they work, their lifecycle and limits. Now that I gained enough experience it's time to move on. Recently I migrated this website to Webpack and TypeScript. So I thought: "it's time also to improve my PWA codebase by leveraging some professional tool". This is the reason why I chose to rewrite my service worker in Workbox. What is workbox?

JavaScript Libraries for adding offline support to web apps...Welcome, Workbox is a set of libraries and Node modules that make it easy to cache assets and take full advantage of features used to build Progressive Web Apps.

As the official description says, Workbox a TypeScript library that enable developers to build PWAs in a fast way by giving to them the ability to have some already prepared component to manage all the aspects of a PWA: routing, caching, tracking etc. As reported on the official website Workbox is subdivided into modules, where each one of them covers a different PWA feature.

workbox-background-sync, use background sync to reliably make a network request even if the user is offline.

workbox-broadcast-update, to send messages to pages (via Broadcast Channels) when a cache is updated with a new response.

workbox-cacheable-response, to restrict which requests are cached based on a response's status code or headers.

workbox-core, to alter log levels and change cache names via workbox-core. Contains shared code used by all Workbox libraries.

workbox-expiration, removed cached requests based on the number of items in a cache or the age of the cached request.

workbox-google-analytics, see how users are interacting with your site when they are offline.

workbox-navigation-preload, enable navigation preload, to get a network response for navigation requests faster.

workbox-precaching, easily precache a set of files and efficiently manage updates to files.

workbox-range-request, this modules provides support for responding to a Range: request using a slice of previously cached data.

workbox-routing, routes requests in your service worker to specific caching strategies or callback functions.

workbox-strategies, a set of runtime caching strategies that will handle responding to a request, normally used with workbox-routing.

workbox-streams, this modules provides support for composing a response from a series of streaming sources.

So let's see how I used it and how I took advantage of some of its major features, including the full integration with Webpack.

Implementation

As I already said, Workbox is written in TypeScript. So let's start by creating a new file called sw.ts. The first thing we need to do is call some service worker lifecycle method, skipWaiting and clientsClaim. When you install an update of a service worker, the new one will not be used until you close all the tabs already controlled by the service worker and relaunch the web app. If you don't need that feature, you can make your new service worker activate sooner by calling the skipWaiting function. In case you want to force all the tabs open to be immediately controller by a new updated version of your service worker you can call clientsClaim. Both this lifecycle functions are contained in the workbox-core module, so we can just import and call them.

import { skipWaiting, clientsClaim } from "workbox-core"

//...other code...

skipWaiting()
clientsClaim()

//...other code...

Now we are ready to setup it's time to understand and setup caches with Workbox. All the caches inside the framework are based on the concept of routes and strategies. Service worker can intercept network requests for a page and can respond to the browser with cached content, content from the network or content generated in the service worker. To define which request must be intercepted and served by the service worker, you must define its routes. The way the service worker handle the routes (for example cache only, network first etc.) are the strategies. Usually when you write your own service worker you define some files to precache during the service worker installation process and then for the routes you want to serve from it their related strategies.

Let's start with the precache of some files. This is usually done manually by the developer in the install event, and usually the resource that are cached are the ones needed in order to have the PWA work offline. In my cases, and generally speaking for a blog/news website, this basically means save in the cache JavaScript and CSS files. Workbox give us the precacheAndRoute function to do this. It is possible to pass to this function a list of files to be cached and it will take care of creating an ad-hoc cache and same the files during the installation process. To build this website I'm using Webpack as JavaScript bundler. Workbox has a great support for it. In particular for the precache phase, there is the npm package workbox-webpack-plugin that contains a plugin called InjectManifest. This plugin is able to inject in the Service Worker code a variable named __WB_MANIFEST that contains a list of the entry points/generated files of the Webpack bundling process. So in my service worker I can precache the files I need by just writing precacheAndRoute(self.__WB_MANIFEST). Anyway there's a problem: I want to cache some additional files during the installation process to be used to manage errors related to content not available in the caches and that it is not possible to load due to network errors. It is possible to add these additional files with the standard way in the install event. In my case I decided to create an ad-hoc cache to save these files. Last but not least in the install event I decided also to clear all the caches. In this way on every install of a new service worker version I will initialize all the caches. All the caches that I'm using are identified by the constants CACHE_<purpose> (and we will see in a few moments how I'm using them 😏). Below you can find the code for the precache and install event.

import { precacheAndRoute } from 'workbox-precaching';

//...other code...

const CACHE_PREFIX = 'workbox-chicio-coding'
const CACHE_OFFLINE_NAME = `${CACHE_PREFIX}-offline`
const CACHE_SCRIPT_NAME = `${CACHE_PREFIX}-scripts`
const CACHE_STYLES_NAME = `${CACHE_PREFIX}-styles`
const CACHE_DOCUMENTS_NAME = `${CACHE_PREFIX}-documents`
const CACHE_FONTS_NAME = `${CACHE_PREFIX}-fonts`
const CACHE_IMAGES_NAME = `${CACHE_PREFIX}-images`

const OFFLINE_PAGE_URL = '/offline.html'
const OFFLINE_PAGE_NO_NETWORK_IMAGE_URL = '/assets/images/no-wifi.png'

//...other code...

// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore: __WB_MANIFEST is a placeholder filled by workbox-webpack-plugin with the list of dependecies to be cached
precacheAndRoute(self.__WB_MANIFEST)
googleAnalytics.initialize()

self.addEventListener('install', (event: ExtendableEvent) => {
  const offlineUrls = [
    OFFLINE_PAGE_URL,
    OFFLINE_PAGE_NO_NETWORK_IMAGE_URL
  ];
  event.waitUntil(
    Promise.all([
      caches.delete(CACHE_DOCUMENTS_NAME),
      caches.delete(CACHE_SCRIPT_NAME),
      caches.delete(CACHE_STYLES_NAME),
      caches.delete(CACHE_FONTS_NAME),
      caches.delete(CACHE_IMAGES_NAME),
      caches.open(CACHE_OFFLINE_NAME).then((cache) => cache.addAll(offlineUrls))
    ])
  );
})

//...other code...

After the precache we define the routes and strategies for the network call after the install events. In my implementation I decided to setup a cache for each one of the following assets:

styles (CSS files)
scripts (JavaScript files)
documents (HTML files)
fonts
images

Each route is registered in the service worker with the registerRoute function. It expects 3 parameters: a regex that defines the URLs intercepted by the route, a strategy handler and eventually the HTTP method expected on the route (the last two parameters are optional and could be substituted by a Route object that contains this 3 params). In our case, as a consequence of the fact that I decided that all the routes must be served with a CacheFirst strategy, we can define a registerRoute function that defines a route with a cache first strategy given the regex of the route, the cache name and the ExpirationPlugin. What is an ExpirationPlugin? It is a class that define the retention policy of the cache to which it is assigned. In our case I defined different ExpirationPlugin instances based on the policy I chosen for each media type supported by the routes we defined above:

15 days for the styles
180 days for the fonts
60 days for the images
60 days for the documents

Above you can see the implementation for the routes and strategies.

import { registerRoute, Route } from 'workbox-routing';
import { ExpirationPlugin } from 'workbox-expiration';
import { CacheFirst } from 'workbox-strategies';

//...other code...

const stylesScriptsExpirationPlugin = new ExpirationPlugin({ maxEntries: 10, maxAgeSeconds: 15 * 24 * 60 * 60, purgeOnQuotaError: true })
const fontsExpirationPlugin = new ExpirationPlugin({ maxEntries: 5, maxAgeSeconds: 180 * 24 * 60 * 60 })
const imagesExpirationPlugin = new ExpirationPlugin({ maxEntries: 100, maxAgeSeconds: 60 * 24 * 60 * 60 })
const documentExpirationPlugin = new ExpirationPlugin({ maxEntries: 50, maxAgeSeconds: 60 * 24 * 60 * 60, purgeOnQuotaError: true })

//...other code...

const registerCacheFirstRouteUsing = (
  destination: RequestDestination,
  cacheName: string,
  expirationPlugin: ExpirationPlugin
): Route => registerRoute(
  ({ request }) => request.destination === destination,
  new CacheFirst({
    cacheName: cacheName,
    plugins: [expirationPlugin],
  })
)

registerCacheFirstRouteUsing('style', CACHE_STYLES_NAME, stylesScriptsExpirationPlugin)
registerCacheFirstRouteUsing('script', CACHE_SCRIPT_NAME, stylesScriptsExpirationPlugin)
registerCacheFirstRouteUsing('document', CACHE_DOCUMENTS_NAME, documentExpirationPlugin)
registerCacheFirstRouteUsing('font', CACHE_FONTS_NAME, fontsExpirationPlugin)
registerCacheFirstRouteUsing('image', CACHE_IMAGES_NAME, imagesExpirationPlugin)

//...other code...

Now there's a question we didn't answer: how do we manage the requests that will fail? There are multiple possibilities to manage these cases. In our case I decided to go for a global catch handler. By calling setCatchHandler it is possible to catch all the network/cache error for all the routes defined. We can give a callback to this function where we can define an error recovery strategy for each type of error. In our case we respond with the offline page (see the offline cache defined in the precache/install event) if the error happens on a resource of type document (so an html page that can be loaded completely), and we return a generic error for all the other fail (images loading fail, scripts fail etc.). Below you can find the implementation of the cache handler.

import { setCatchHandler } from 'workbox-routing';

//...other code...

setCatchHandler((options: RouteHandlerCallbackOptions): Promise<Response> => {
  const isADocumentRequest = (options: RouteHandlerCallbackOptions): boolean =>
    !(typeof options.request === 'string') && options.request.destination == 'document';
  const isAOfflinePageImageRequest = (options: RouteHandlerCallbackOptions): boolean =>
    !(typeof options.request === 'string') &&
    options.request.destination == 'image' &&
    options.url?.pathname == OFFLINE_PAGE_NO_NETWORK_IMAGE_URL

  if (isADocumentRequest(options)) {
    return caches.match(OFFLINE_PAGE_URL) as Promise<Response>;
  }

  if (isAOfflinePageImageRequest(options)) {
    return caches.match(OFFLINE_PAGE_NO_NETWORK_IMAGE_URL) as Promise<Response>;
  }

  return Promise.resolve(Response.error());
})

//...other code...

As a consequence of the fact that I'm migrating my previous version of the service worker for my website, I needed also to migrate the part that is responsible for getting messages from the page related to the pull to refresh. In this case the previous version of the code was responsible for the clear of some caches. We can write this feature using the deleteCacheAndMetadata method of the ExpirationPlugin class. Below you can find the related code.

//...other code...

self.addEventListener('message', (event: ExtendableMessageEvent) => {
  const isARefresh = (event: ExtendableMessageEvent): boolean => event.data.message === 'refresh'
  const sendRefreshCompletedMessageToClient = (event: ExtendableMessageEvent): void => event.ports[0].postMessage({ refreshCompleted: true })

  if (isARefresh(event)) {
    Promise.all([
      imagesExpirationPlugin.deleteCacheAndMetadata(),
      documentExpirationPlugin.deleteCacheAndMetadata()
    ])
      .then(() => sendRefreshCompletedMessageToClient(event))
      .catch(() => sendRefreshCompletedMessageToClient(event))
  }
})

//...other code...

In a previous post I already talked about the fact that workbox could help us to manage the Google Analytics tracking when the PWA is offline. So for this part, we just need (as in the previous version of my service worker) to call the googleAnalytics.initialize() function and workbox will take care of:

store the analytics tracking occured while the app is offline
sync this tracking events to the server when a network connection is available again

import * as googleAnalytics from 'workbox-google-analytics';

//...other code...

googleAnalytics.initialize()

//...other code...

One important thing to be noted here is that in my project I'm using TypeScript with the strict types activated and ESLint. As a consequence of this fact I have to add two things to the code we saw above:

add a declaration in order to let TypeScript know that self is a ServiceWorkerGlobalScope
a @ts-ignore annotation to let TypeScript know that the __WB_MANIFEST will be available at compile time (Webpack bundling), and an additional eslint-disable-next-line @typescript-eslint/ban-ts-comment comment to avoid ESLint complaining about the @tsignore comment. 😆

//...other code...

// Fix self: https://stackoverflow.com/questions/56356655/structuring-a-typescript-project-with-workers
declare const self: ServiceWorkerGlobalScope;
export {};

//...other code...

// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore: __WB_MANIFEST is a placeholder filled by workbox-webpack-plugin with the list of dependecies to be cached
precacheAndRoute(self.__WB_MANIFEST)

//...other code...

Now that the service worker code has been migrated to Workbox you may ask if we can do something also for the service worker registration, and generaly speaking for all the service worker code inside the window context. The answer to this question is an additional workbox module called workbox-window. This module let the developers register their service worker and eventually use all its feature. In my case in the window context I'm doing 2 operation:

the service worker registration
I send a message to the service worker to clear some of the caches whenever a user starts a pull to refresh

We can wrote these feature by using an instance of Workbox and its two methods register and messageSW. Below you can find the two function registerToServicerWorker and sendMessageToServiceWorker that I rewrote with workbox-window.

import { Workbox } from "workbox-window";

interface ServiceWorkerMessage {
  message: string;
}

const wb = new Workbox('/sw.js')

const isServiceWorkerSupported: () => boolean = () => ('serviceWorker' in navigator)

const registerToServicerWorker = (): void => {
  if (isServiceWorkerSupported()) {
    wb.register()
      .then(() => { console.log('Service Worker registration completed') })  
      .catch((err) => { console.error('Service Worker registration failed:', err) })
  }
}

const sendMessageToServiceWorker = (message: ServiceWorkerMessage): Promise<unknown> => {
  return new Promise((resolve, reject) => {
    wb.messageSW(message).then((event: MessageEvent): void => {
      if (event.data) {
        if (event.data.error) {
          reject(event.data.error)
        } else {
          resolve(event.data)
        }
      }
    })
  })
}

export { sendMessageToServiceWorker, registerToServicerWorker, isServiceWorkerSupported }

Conclusion

As you can see, writing a service worker with Typescript and Workbox is really easy. During the last time during my daily job I'm basically doing more and more web development instead of mobile apps. I feel like I'm almost reaching the mythological status of the "fullstack developer". 😆 Let's see what the future holds for me.

Originally published at https://www.fabrizioduroni.it on August 7, 2020.

Use UIKit components in SwiftUI: UIViewControllerRepresentable and UIViewRepresentable

Fabrizio Duroni — Fri, 31 Jul 2020 14:05:44 +0000

Do you know that it is possible to use UKit components in SwiftUI? Let's see how you can use UIViewRepresentable and UIViewControllerRepresentable to use your UIKit based component or to fill the gap for missing SwiftUI API.

SwiftUI has been around for more than a year now. With its reactive paradigm approach it is a big step forward when compared to the UIKit imperative approach. But as a consequence of the fact that UIKit has been with us for almost twelve years and there are millions of apps already publish on the app store, a lot of developers have tons of UKit based library and custom components. Another interesting point is the fact that at the moment of this writing a lot of UIKit components from the iOS SDK are missing a counterpart in SwiftUI.

Anyway, you are just starting to develop a new app and you want to create it in SwiftUI (targeting only for iOS 13 and up because, you know, for compatibility reason 😆) without losing the ability to speed up you development by reusing your UIKit based libraries and components. Is there a solution to this problem? Yes!! ☺️

In this post I will show you how you can leverage the power of UIViewRepresentable and UIViewControllerRepresentable protocols to expose your UIKit views and controller as standard SwiftUI components. Before going deeper with an example let's see the definition of this two protocol from the official Apple documentation.

Let's start from UIViewRepresentable:

UIViewRepresentable. A wrapper for a UIKit view that you use to integrate that view into your SwiftUI view hierarchy...Adopt this protocol in one of your app's custom instances, and use its methods to create, update, and tear down your view. The creation and update processes parallel the behavior of SwiftUI views, and you use them to configure your view with your app's current state information...

And here we have the other one for UIViewControllerRepresentable:

UIViewControllerRepresentable. A view that represents a UIKit view controller...Adopt this protocol in one of your app's custom instances, and use its methods to create, update, and tear down your view controller. The creation and update processes parallel the behavior of SwiftUI views, and you use them to configure your view controller with your app's current state information...The system doesn't automatically communicate changes occurring within your view controller to other parts of your SwiftUI interface. When you want your view controller to coordinate with other SwiftUI views, you must provide a Coordinator instance to facilitate those interactions. For example, you use a coordinator to forward target-action and delegate messages from your view controller to any SwiftUI views.

There are a lot of concepts here: view lifecycle, notification, delegation and communication with Coordinator. 😰 But don't worry, with an example you will see how easy it is to use UIViewRepresentable and UIViewControllerRepresentable.

Implementation

In this example we will create a simple app that will let the user select a document using and instance of the UIKit based controller UIDocumentPickerViewController and we will print the name of the file selected using a customized UIKit UILabel. Let's start from the custom UIKit UILabel view. To use our custom UILabel in SwiftUI we need to wrap it in a struct that implements the first protocol we saw above: UIViewRepresentable. This protocol contains two methods:

makeUIView(context: Self.Context) -> Self.UIViewType, a method where you create the UIKit to be used in SwiftUI
updateUIView(_ uiView: Self.UIViewType, context: Self.Context) a method called when the view must be redrawn due to external changes (e.g. a State update)

The Self.UIViewType type is an associated type of the protocol and it must match the type of the UIKit view wrapped.

So for our example we can implement a DocumentNameLabel struct that implements the UIViewRepresentable protocol. In the makeUIView method we create an instance of the customized UILabel that we want to expose. In the updateUIView we will update the text shown by the label with the value contained in a @Binding var updated from the container view (do you remember what is a @Binding var, right?).

struct DocumentNameLabel: UIViewRepresentable {
    @Binding var content: String

    func makeUIView(context: Context) -> UILabel {
        let label = UILabel()
        label.backgroundColor = #colorLiteral(red: 0.721568644, green: 0.8862745166, blue: 0.5921568871, alpha: 1)
        label.layer.borderColor = #colorLiteral(red: 0.2745098174, green: 0.4862745106, blue: 0.1411764771, alpha: 1)
        label.layer.borderWidth = 2
        return label
    }

    func updateUIView(_ uiView: UILabel, context: Context) {
        uiView.text = content
    }
}

After the view, we need to take care of the UIKit controller used to select the document, UIDocumentPickerViewController. We will wrap it in a struct that implements the UIViewControllerRepresentable. This protocol contains four methods:

makeUIViewController(context: Self.Context) -> Self.UIViewControllerType, a method used to create the instance of the view controller to be used in your SwiftUI screen
updateUIViewController(Self.UIViewControllerType, context: Self.Context), a method called when the view controller must be redrawn/updated due to external changes (e.g. a State update)
makeCoordinator() -> Self.Coordinator, a method used to create the custom instance that you use to communicate changes from your view controller to other parts of your SwiftUI interface
static func dismantleUIViewController(Self.UIViewControllerType, coordinator: Self.Coordinator), a method called to clean up additional resources used by the view controller when it is dismissed

As for the previous protocol, The Self.UIViewControllerType type is an associated type of the protocol and he must match the type of the UIViewController wrapped.

Le't start from the first method reported above, where we will create the instance of the UIDocumentPickerViewController that we want to expose to SwiftUI. The delegate of this controller will be the Coordinator instance created in the makeCoodinator protocol method. So the Coordinator will be responder for all the UIDocumentPickerDelegate methods. Remember that the makeCoordinator method is called before everything else when we will create our DocumentPickerViewController instance in SwiftUI. The Coordinator receive a reference to the wrapping struct. This reference is used to trigger a custom callback contained in the var callback: (URL) -> () property that is received at DocumentPickerViewController construction time when the documentPicker(_ controller: UIDocumentPickerViewController, didPickDocumentsAt urls: [URL]) method of the UIDocumentPickerDelegate protocol is invoked. In this way we are able to send back to SwiftUI the result of the interaction with the UIDocumentPickerViewController. Last but not least there's also the updateUIViewController method, but in this case with an empty implementation because we don't need to update the status of the view controller using some SwiftUI state change.

struct DocumentPickerViewController: UIViewControllerRepresentable {
    var callback: (URL) -> ()

    func makeCoordinator() -> Coordinator {
        return Coordinator(documentController: self)
    }

    func updateUIViewController(
        _ uiViewController: UIDocumentPickerViewController,
        context: UIViewControllerRepresentableContext<DocumentPickerViewController>) {
    }

    func makeUIViewController(context: Context) -> UIDocumentPickerViewController {
        let controller = UIDocumentPickerViewController(documentTypes: [String(kUTTypeText)], in: .open)
        controller.delegate = context.coordinator
        return controller
    }

    class Coordinator: NSObject, UIDocumentPickerDelegate {
        var documentController: DocumentPickerViewController

        init(documentController: DocumentPickerViewController) {
            self.documentController = documentController
        }

        func documentPicker(_ controller: UIDocumentPickerViewController, didPickDocumentsAt urls: [URL]) {
            guard let url = urls.first, url.startAccessingSecurityScopedResource() else { return }
            defer { url.stopAccessingSecurityScopedResource() }
            documentController.callback(urls[0])
        }
    }
}

Now we are ready to use our UIKit controller and our custom UIView in a SwiftUI view. We can just add them to the body field of our view and use them as a standard SwiftUI component. One thing to be noted is the set of the frame on the DocumentNameLabel component. This is a consequence of the fact that sometimes the UIKit views wrapped with the UIViewRepresentable protocol take as much space as they can in a VStack component. This means that if we don't set the frame in our example the label would take the majority of the screen space (leaving only the space for button to be shown).

struct ContentView: View {
    @State var isDocumentPickerPresented: Bool = false
    @State var documentUrl: String = ""

    var body: some View {
        VStack{
            Spacer()
            DocumentNameLabel(content: self.$documentUrl)
                .frame(height: 40)
            Button(action: {
                self.isDocumentPickerPresented.toggle()
            }, label: { Text("Document selection") })
                .frame(height: 40, alignment: .center)
                .sheet(isPresented: self.$isDocumentPickerPresented, content: {
                    DocumentPickerViewController { url in
                        self.documentUrl = url.lastPathComponent
                    }
                })
            Spacer()
        }
        .padding(10)
    }
}

Conclusion

You can find all the code above in this example repository on Github. Don't hesitate to clone it and start to play with the example. UIViewRepresentable and UIViewControllerRepresentable are the tools provided by Apple to let you mix the power and versatility of UIKit with the declarative reactive approach of SwiftUI. I hope that in next future releases of the iOS SDK there will be no need to write this custom wrapper components at least for all the standard UIKit components.

Originally published at https://www.fabrizioduroni.it on July 7, 2020.

Lazy loading of JavaScript modules by using dynamic imports and code splitting with Webpack

Fabrizio Duroni — Wed, 22 Jul 2020 11:04:48 +0000

Most of the time you have a big JavaScript codebase for your website but you need only a small fraction of it when a page is requested. Is it possible to load chunks of JavaScript code only when they are really needed? Yes you can with Webpack and its code splitting feature based on a syntax equal to the one of ES2020 dynamic imports.

Recently I migrated my website (this one you're seeing right now) to TypeScript + Webpack as bundling system. One of the main problem of my website was the dimension of the final JavaScript generated after the bundling for the homepage. As a consequence of the fact that this page contains a Threejs physically based scene, the size of the index.home.js script was over 600 KB 😱. This was too much, considering also that all this JavaScript was loaded without been used on the mobile version of the website, where this feature was turned off.

During the last few months of my daily job at lastminute.com I worked on a project that is using Webpack for bundling the JS code. In particular, during the development of a new part of the user personal area I encountered the code splitting with lazy loading feature of Webpack and immediately I thought: "THIS IS WHAT I NEED FOR THE HOMEPAGE OF fabrizioduroni.it". 😍

So let's start and see how I used it on my website so that you can start to optimize your site too!!

Implementation

First of all, there are two types of output file generated by Webpack:

entry files, that are the one main entry points for your application. This are usually the files that you will add with a script tag in your HTML pages (or you can let Webpack add them automatically, but this is a story for another post 😏)
chunk files, that are the one obtained after the code splitting

In a base Webpack configuration file it is usually contained the entry property that contains the list of entry files to be bundled. To enable code splitting and chunk files generation we need to add a new entry in the configuration called chunkFilename. With this configuration entry we can tell Webpack how to name the chunks file generated. In my case I defined the name as a concatenation of some Webpack built-in environment variable:

[name], the chunk name
[chunkhash], the hash generated by Webpack from the content of the chunk. If its content is changed than the chunkhash will be updated consequently. It is similar to the [hash] variable used in the entry configuration (but this one is generated from the entire build result).

{
  mode: 'production',
  entry: {
    'index.home': 'ts/index.home.ts',
    'index.blog': 'ts/index.blog.ts',
  },
  output: {
    filename: '[name].[hash].min.js',
+    chunkFilename: '[name].[chunkhash].bundle.js',
    publicPath: `dist/`,
    path: path.resolve(__dirname, dist),
  },
  module: {
    /*...modules configurations...*/
  },
  /*...other configurations...*/
}

So now we have one thing left to do: decided what in our codebase will become a chunk in the final build. To do this, Webpack leverage the ES2020 dynamic import syntax. In fact, all we need to do is to import asynchronously the module we want to load later and execute it as soon as it loaded. In my specific case I wanted to load the module scene-threejs only if some condition where respect:

the browser of the user supports WebGL (because it gives the best performance when compared to canvas drawing)
the device of the user is a computer/laptop (because I want to avoid too much mobile data usage and bad user experience on some older devices)

To do this I added an async import with the declaration import(/* webpackChunkName: "scene-threejs" */ './scene-threejs').then(module => module.sceneThreeJS()). In the resolve callback of the then method the loaded module is returned. In this case the scene-threejs contains just one exported function sceneThreeJS, that I execute as soon as the module is available. One important thing to note is the webpackChunkName comment with value "scene-threejs": this string will be assigned to the [name] Webpack environment variable and will be used as first part in the chunk file name (see the Webpack configuration discussed above). Below you can find the entire code, written using TypeScript (don't be scared by the types 😆).

/* ...other code... */

const isWebGLEnabled = (): boolean => {
  /*...implementation...*/
}

const scene3D = (): void => {
  if (isWebGLEnabled() && !isAMobileDevice()) {
    import(/* webpackChunkName: "scene-threejs" */ './scene-threejs').then(module => module.sceneThreeJS())
  }
}

export { scene3D }

This is all I need to code split my codebase and lazy load modules only when they are needed. Let's see the code above in action. If I try to access the homepage of this website from a desktop/laptop computer I will see the threejs scene and in the network inspector the scene-threejs chunk is loaded. On important thing to note is that Webpack has created two chunk. One is our module (the one with the name scene-threejs). The second one that starts with the vendor keyword contains all the third party dependencies. Yes, you understood right: Webpack extract automatically the third party dependencies from you chunk module in separated files.

If I access the same page from a mobile device the 3D scene is not loaded and consequently the chunk is not loaded. 🎉

Conclusion

Webpack is a wonderful tool. It gives you the ability to bundle your code, styles and resources with a lot of customization thanks to its powerful ecosystem of loaders and plugins. This has been another step to make this site a true professional blog platform with a strong development toolchain. 😍

Originally published at https://www.fabrizioduroni.it on June 2, 2020.

Add dark mode support on your website with SASS and prefers-color-scheme media query

Fabrizio Duroni — Wed, 03 Jun 2020 07:16:30 +0000

Dark mode support has been around for quite some time. Let's see how you can create a light theme and a dark theme for your website that will be selected automatically based on the user system preference.

Dark mode has been around for a while on all the major platforms: macOS, iOS, Android, Microsoft Windows and now also Linux. Well, aside from the discussion to decide if dark mode is better for your eyes of not, it's clear that it gives you a big style improvement on your site.

So it's a perfect time to add a Dark theme to your website that will be used as soon as your users use dark mode on their system!!! This is why I decided to add dark mode to this site. Let's see how I did this by leveraging the power of sass mixins and media queries.

Implementation

First of all I needed to understand how it was possible to detect system appearance setting. It turns our this is really simple thanks to the prefers-color-scheme media query. At the moment of this writing this media query is supported by all the major browsers. It accepts three values:

no-preference, indicates that the user has made no preference known to the system (default to light usually)
light, the user has expressed the preference for a page that has a light theme (dark text on light background).
dark Indicates that user has expressed the preference for a page that has a dark theme (light text on dark background).

So I needed to define a strategy to write the CSS in a way that the user will see the dark theme only if the system appearance is set to dark mode and fallback to the light theme for all the other cases. This is why I chose to define a media query only for the dark value of the prefers-color-scheme and keep the light theme values defined in the base CSS rules. So all the theme related rules will look like the following CSS code block.

.a-rule {
  background-color: #FFFFFF;
}

@media(prefers-color-scheme: dark) {
  .a-rule {
    background-color: #000000;
  }
}

In my project I'm using SASS, a language that extends CSS enables you to use things like variables, nested rules, inline imports and more. So I wanted to find a way to write something in which I centralized this logic. In this way I will have a theme section in my sass source code that has the only responsibility to manage the theme for the entire website. This is possible in SASS by using @mixin and @include!! 😍 Let's see the definition from the official documentation.

Mixins allow you to define styles that can be re-used throughout your stylesheet. They are defined using the @mixin at-rule. A mixin’s name can be any Sass identifier, and it can contain any statement other than top-level statements. They can be used to encapsulate styles that can be dropped into a single style rule; they can contain style rules of their own that can be nested in other rules or included at the top level of the stylesheet; or they can just serve to modify variables...Mixins are included into the current context using the @include at-rule, which is written @include <name> or @include <name>(<arguments...>), with the name of the mixin being included.

This is exactly what I needed to create my "SASS theme manager". Let's see some code. First of all I defined a list of keys that identify:

the theme names
the colors contained in each of my themes.

$dark-theme: "dark-theme";
$light-theme: "light-theme";

$primary-color-dark: "primary-color-dark";
$primary-color: "primary-color";
$primary-color-light: "primary-color-light";
$primary-color-text: "primary-color-text";
$accent-color: "accent-color";
$primary-text-color: "primary-text-color";
$secondary-text-color: "secondary-text-color";
$divider-color: "divider-color";
$general-background: "general-background";
$general-background-light: "general-background-light";
/* ...other color variable strings... */

Then I created a new variable named $themes associated with a SASS map data structure. This map contains as key the two theme name variables, $dark-theme and $light-theme, and the content is again a map with the association between color names (the variables defined above) and the color HEX value.

$themes: (
  $light-theme: (
    $primary-color-dark: #303F9F,
    $primary-color: #3F51B5,
    $primary-color-light: #DFDFF1,
    $primary-color-text: #FFFFFF,
    $accent-color: #0F67FF,
    $primary-text-color: #151515,
    $secondary-text-color: #575757,
    $divider-color: #BDBDBD,
    $general-background: #FAFAFA,
    $general-background-light: #FFFFFF,
    /* ...other color keys with HEX values... */
  ),
  $dark-theme: (
    $primary-color-dark: #303F9F,
    $primary-color: #3F51B5,
    $primary-color-light: #DFDFF1,
    $primary-color-text: #FFFFFF,
    $accent-color: #4fA7ff,
    $primary-text-color: #d7d7d8,
    $secondary-text-color: #A6A6A6,
    $divider-color: #575757,
    $general-background: #181918,
    $general-background-light: #363636,
    /* ...other color keys with HEX values... */
  )
);

Now I was ready to define the @mixin needed to apply the themes. We said in the introduction that we will apply the dark mode based on the @media (prefers-color-scheme: dark) media query and we will use the light theme as default (light theme or no user preference). This basically means that I needed to define a @mixin that let us apply a certain property in both cases. I needed also to be able to eventually apply other property attributes other than the color based on the current theme selected. For example I had rules for border styling like border: 1px solid #BDBDBD where the color must be picked up from the correct theme based on the rule discussed before.
So I created @mixin theme($themes, $property, $color, $additionalPropertiesPositionIsFront: false, $additionalProperties: '') that accepts the following properties:

$property, the property that we want to change based on the theme selected for the current user
$color, the color name to be picked up. This should be one of the variable seen above
$additionalPropertiesPositionIsFront, a boolean that is used to understand if the additional properties to be concatenated with the color values should be placed before or after the color value. This property is optional and has a default value of false
$additionalProperties, a string with the list of properties be concatenated with the color value. This property is optional and has a default value of empty string.

In this theme mixin I got the dark and light theme values by extracting theme from the $themes variable using the map-get SASS map function. Then I used another mixin @mixin themeProperty($theme, $property, $color, $additionalPropertiesPositionIsFront, $additionalProperties) to create the css rule <property>: <value> using the values received from the invocation. Inside it I did the concatenation between the additional properties and the color value (if necessary) using the + operator and the SASS unquote function to remove the string quote and have in output from the mixin a standard css rule. The themeProperty is invoked two times, one for the default value with the light time, and another one inside the @media (prefers-color-scheme: dark) query. Below you can find the code of these two new mixin.

@mixin themeProperty($theme, $property, $color, $additionalPropertiesPositionIsFront, $additionalProperties) {
  @if $additionalPropertiesPositionIsFront {
    #{$property}: unquote($additionalProperties + ' ' + map-get($theme, $color));
  } @else {
    #{$property}: unquote(map-get($theme, $color) + ' ' + $additionalProperties);
  }
}

@mixin theme($property, $color, $additionalPropertiesPositionIsFront: false, $additionalProperties: '') {
  $light: map-get($themes, $light-theme);
  $dark: map-get($themes, $dark-theme);

  @include themeProperty($light, $property, $color, $additionalPropertiesPositionIsFront, $additionalProperties);

  @media (prefers-color-scheme: dark) {
    @include themeProperty($dark, $property, $color, $additionalPropertiesPositionIsFront, $additionalProperties);
  }
}

This is all I needed two generate the CSS rules with the theme selection based on the appearance user preferences. Below you can find the entire implementation described above (I removed some color names from the list because it is too big and not so useful).

$dark-theme: "dark-theme";
$light-theme: "light-theme";

$primary-color-dark: "primary-color-dark";
$primary-color: "primary-color";
$primary-color-light: "primary-color-light";
$primary-color-text: "primary-color-text";
$accent-color: "accent-color";
$primary-text-color: "primary-text-color";
$secondary-text-color: "secondary-text-color";
$divider-color: "divider-color";
$general-background: "general-background";
$general-background-light: "general-background-light";
/* ...other color keys... */

$themes: (
  $light-theme: (
    $primary-color-dark: #303F9F,
    $primary-color: #3F51B5,
    $primary-color-light: #DFDFF1,
    $primary-color-text: #FFFFFF,
    $accent-color: #0F67FF,
    $primary-text-color: #151515,
    $secondary-text-color: #575757,
    $divider-color: #BDBDBD,
    $general-background: #FAFAFA,
    $general-background-light: #FFFFFF,
    /* ...other color keys with HEX values... */
  ),
  $dark-theme: (
    $primary-color-dark: #303F9F,
    $primary-color: #3F51B5,
    $primary-color-light: #DFDFF1,
    $primary-color-text: #FFFFFF,
    $accent-color: #4fA7ff,
    $primary-text-color: #d7d7d8,
    $secondary-text-color: #A6A6A6,
    $divider-color: #575757,
    $general-background: #181918,
    $general-background-light: #363636,
    /* ...other color keys with HEX values... */
  )
);

@mixin themeProperty($theme, $property, $color, $additionalPropertiesPositionIsFront, $additionalProperties) {
  @if $additionalPropertiesPositionIsFront {
    #{$property}: unquote($additionalProperties + ' ' + map-get($theme, $color));
  } @else {
    #{$property}: unquote(map-get($theme, $color) + ' ' + $additionalProperties);
  }
}

@mixin theme($property, $color, $additionalPropertiesPositionIsFront: false, $additionalProperties: '') {
  $light: map-get($themes, $light-theme);
  $dark: map-get($themes, $dark-theme);

  @include themeProperty($light, $property, $color, $additionalPropertiesPositionIsFront, $additionalProperties);

  @media (prefers-color-scheme: dark) {
    @include themeProperty($dark, $property, $color, $additionalPropertiesPositionIsFront, $additionalProperties);
  }
}

With all the stuff above I was ready to "themify" my web site. All I needed to do (and if you read the article until here you're ready too 😄) was to call the theme mixin in my styles definition in order to apply the theme color where I needed them. Below you can find an example where I'm setting the text color in a css class.

.blog-post-meta {
  @include theme('color', $secondary-text-color);
  /*... other rules ...*/
}

Conclusion

Nowadays it is important to give to the user the best experience when they use your software. Dark mode is another step in this direction. By leveraging the power of tools like SASS you can implement a theme component in less then a hour. Sooo now go and join the dark side (of themes). ♥️

Originally published at https://www.fabrizioduroni.it on May 20, 2020.

How to: create your SUPER simple dependency injector container in Swift

Fabrizio Duroni — Wed, 03 Jun 2020 07:12:48 +0000

There are a lot of dependency injection framework in the open source swift world with really cool features like object graph, persistence etc. But what if all you need is a lightweight dependencies container? In this post I will show you how to create it by leveraging the Metatype Type, Generics, the Hashable protocol and the Equatable protocol.

The open source Swift world is full of useful framework. You can find almost everything you need (there are rare cases where you need to write something that still doesn't exist out there). Anyway, a lot of the frameworks and libraries you will find out do more than you need. See for example the world of the dependencies injection framework. We have a lot of alternatives from which we can choose: Swinject, Weaver etc. This frameworks come with a lot of features like: object graph construction, injection with property wrappers, instance persistence etc. This are all useful feature, but if your needs are very limited (just a dependecies container register/resolver using protocol and classes) the previous frameworks gives you just a big overhead and complexity on you code. This is why for my recent project I tried to write my own very simple dependencies injector container by leveraging the power of Swift Metatype and the Hashable protocol. Let's go and see the how I created it 😏.

Implementation

The main class of dependencies injector container is composed by 2 classes: DependeciesContainer and DependencyKey.

The main one stores in the field dependecies a dictionary of all the dependencies registered using an instance of the second one. DependeciesContainer exposes two methods:

register<T>(type: T.Type, name: String? = nil, service: Any), that lets you register a new dependency in the container. It accepts 3 parameter. The first one is the Type of the dependency. The second one is a string that let's you identify different named variations of the same dependencies (e.g. you register Cat and Dog, two different implementation of an hypothetical Animal protocol). The third one is the instance saved in the dependecies dictionary.
resolve<T>(type: T.Type, name: String? = nil) -> T?, that lets you get an instance previously registered. This method accept the same first two parameter of the previous method. It will return null if none of the registered instance has a combination of type and name as the one received as parameters.

As you can see both method extensively uses generics in order to be able to accept any possible class or protocol you may want to use. This is the implementation of DependeciesContainer.

class DependeciesContainer {
    static let shared = DependeciesContainer()

    private init() {}

    private var dependecies: [DependencyKey : Any] = [:]

    func register<T>(type: T.Type, name: String? = nil, service: Any) {
        let dependencyKey = DependencyKey(type: type, name: name)
        dependecies[dependencyKey] = service
    }

    func resolve<T>(type: T.Type, name: String? = nil) -> T? {
        let dependencyKey = DependencyKey(type: type, name: name)
        return dependecies[dependencyKey] as? T
    }
}

Now, you can ask some question after seeing this code. First of all, what is a Type? Apple defines it as:

A metatype type refers to the type of any type, including class types, structure types, enumeration types, and protocol types.

A metatype is the representation of the type of an instance. It allows you to use all of class properties and methods of a type. It allows also to threat your code as a data. In this specific case we are using the Type metatype to identify an instance from its own description.

The second one question that you could ask is: how can you use the DependecyKey class instances as key in your dependecies dictionary? This is possible thanks to the Hashable and Equatable protocols. This class implements the hash(into hasher: inout Hasher) method of the Hashable protocol by using the combination of type and name received from the DependeciesContainer. In that method I'm putting in the same hasher the type and the name. In particular for the first one I'm extracting a unique identifier using the ObjectIdentifier function from the Swift Reflection package.

It also implements the Equatable protocol using the same fields in the static func == (lhs: DependencyKey, rhs: DependencyKey) -> Bool method. By implementing this two protocol a class could be used as key in a dictionary.

class DependencyKey: Hashable, Equatable {
    private let type: Any.Type
    private let name: String?

    init(type: Any.Type, name: String? = nil) {
        self.type = type
        self.name = name
    }

    func hash(into hasher: inout Hasher) {
        hasher.combine(ObjectIdentifier(type))
        hasher.combine(name)
    }

    static func == (lhs: DependencyKey, rhs: DependencyKey) -> Bool {
        return lhs.type == rhs.type && lhs.name == rhs.name
    }
}

This is all I need for my ultra light dependencies injector 😍!!! Let's see it in action in an example.

protocol Animal {
    func isAlive() -> Bool
}

class Cat: Animal {
    func isAlive() -> Bool {
        true
    }

    func miaow() -> String {
        return "miaow"
    }
}

class Dog: Animal {
    func isAlive() -> Bool {
        true
    }

    func bark() -> String {
        return "wooof"
    }
}

class Tiger: Animal {
    func isAlive() -> Bool {
        true
    }

    func roar() -> String {
        return "roar"
    }
}


protocol Person {
    func breath() -> String
}

class SickPerson: Person {
    func breath() -> String {
        return "fiuu"
    }

    func cough() -> String {
        return "cough"
    }
}

let dc = DependeciesContainer.shared

// Register using class `Type` Dog
dc.register(type: Dog.self, service: Dog())
let dog = dc.resolve(type: Dog.self)!
print(String(describing: dog)) // "__lldb_expr_7.Dog\n"
print(dog.bark()) // "wooof\n"

// Register using protocol `Type` Person
dc.register(type: Person.self, service: SickPerson())
let person = dc.resolve(type: Person.self)!
print(String(describing: person)) // "__lldb_expr_7.SickPerson\n"
print(person.breath()) // "fiuu\n"
print((person as! SickPerson).cough()) // "cough\n"

// Register using protocol `Type` Animal and variations
dc.register(type: Animal.self, name: "Cat", service: Cat())
dc.register(type: Animal.self, name: "Tiger", service: Tiger())
let cat = dc.resolve(type: Animal.self, name: "Cat")!
print(String(describing: cat)) // "__lldb_expr_9.Cat\n"
print(cat.isAlive())
print((cat as! Cat).miaow()) //"miaow\n"
let tiger = dc.resolve(type: Animal.self, name: "Tiger")!
print(String(describing: tiger)) // "__lldb_expr_9.Tiger\n"
print(tiger.isAlive())
print((tiger as! Tiger).roar()) // "roar\n"

Conclusion

You can find all the code shown in this post in this Github repo. Remember: sometimes with a couple of classes you can avoid to import big frameworks and library into your projects. You just need to study hard the languages and SDK fundamental. 💗

Originally published at https://www.fabrizioduroni.it on March 6, 2020.

Create a custom TabBar in SwiftUI

Fabrizio Duroni — Mon, 09 Mar 2020 13:14:04 +0000

SwiftUI has been introduced by Apple during the last WWDC. I started to use it for a personal project to understand its potential. Let's see how I used SwiftUI to create a custom TabBar with modal and detail navigation.

In the last week I started to develop a new personal project: a new iOS mobile app (that I will show you in the following months). As a consequence of the fact that this was a greenfield project I decided to use SwiftUI to develop all the User Interface and Combine for data binging. These frameworks are the Apple implementation of reactive programming (combine) and declarative user interface programming (SwiftUI). In this post we will focus on SwiftUI (we will see combine in another post later 😉). Even if it is still not ready for a complete production product because a lot of UIKit part are missing and you have to expose them manually and because some stuff doesn't work as expected, SwiftUI is a big step forward with respect to the old imperative UIKit approach (sometimes I still have headache about Autolayout issues and constraint definition 😲😄).

In this post I will show you how I created a custom tab bar with the ability to open a modal from a tab bar item (like some major apps, e.g. Instagram) and a customized navigation where the TabBar is shown only on the first level of navigation. Below you can find a video that shows the final result.

Implementation

Let's start by defining and enum that will identify our tabs in a more expressive way. In the custom tab bar there will be three element, but only two are real tabs (as you see from the video above the one in the middle is modal).

enum Tab {
    case Tab1
    case Tab2
}

The main view MainView contains 2 variable fields:

currentView, a @State variable that keeps the current tab selected
showModal, a @State variable that is used to manage the presentation of the modal from the central button of the TabBar

The body of the view is composed by a NavigationView that contains a VStack with main components of the custom tab bar implementation:

CurrentScreen, that contains and show the current screen selected
TabBar, that contains custom tab bar with all its logic

There are also some style customization like forcing the navigationViewStyle to StackNavigationViewStyle, in order to avoid to see a blank screen on iPad (because the NavigationView on iPad is a split view by default 😆). Last but not least, there is a sheet defined to show a ScreenModal view as a modal whenever the state variable showModal changes.

struct MainView: View {
    @State private var currentView: Tab = .Tab1
    @State private var showModal: Bool = false

    var body: some View {
        NavigationView {
            VStack {
                CurrentScreen(currentView: self.$currentView)
                TabBar(currentView: self.$currentView, showModal: self.$showModal)
            }
        }
        .background(Color(.white))
        .navigationViewStyle(StackNavigationViewStyle())
        .sheet(isPresented: self.$showModal) { ScreenModal() }
    }
}

Let's see first the implementation of the CurrentView. This view is really simple: it shows a specific screen based on the value of its currentView. As you may already noticed, currentView is a not a state variable. It is annotated with the property wrapper @Binding. What does it mean? The @Binding property wrapper lets us declare that one value actually comes from elsewhere, and should be shared in both places. This basically means that this variable will be updated as soon as the variable passed at construction time for this view will be update, and the view will be update consequently by changing the screen shown.

struct CurrentScreen: View {
    @Binding var currentView: Tab

    var body: some View {
        VStack {
            if self.currentView == .Tab1 {
                Screen1()
            } else {
                Screen2()
            }
        }
    }
}

Let's see the TabBar implementation. Also this view contains two @Binding variables:

The first one is again currentView, that will be updated by its children TabBaItem views whenever the user will tap on them.
The other one is showModal, that is a boolean modified by the ShowModalTabBarItem with the method toggle(), that invert the current value of the boolean. As you remember we defined a state variable showModal in the MainView. So as soon as the user taps on ShowModalTabBarItem the showModal state is modified and the MainView will show a modal screen ScreenModal. Beautiful!! 😍

struct TabBar: View {
    @Binding var currentView: Tab
    @Binding var showModal: Bool

    var body: some View {
        HStack {
            TabBarItem(currentView: self.$currentView, imageName: "list.bullet", paddingEdges: .leading, tab: .Tab1)
            Spacer()
            ShowModalTabBarItem(radius: 55) { self.showModal.toggle() }
            Spacer()
            TabBarItem(currentView: self.$currentView, imageName: "gear", paddingEdges: .trailing, tab: .Tab2)
        }
        .frame(minHeight: 70)
    }
}

The implementation of TabBarItem is simple. It contains the styling for the tab bar item. The important thing to notice is here is the onTapGesture modifier. Whenever a user taps on it the @Binding currentView variable will be updated and so also the @State variable currentView in the MainView and consequently also the CurrentScreen view will be update.

struct TabBarItem: View {
    @Binding var currentView: Tab
    let imageName: String
    let paddingEdges: Edge.Set
    let tab: Tab

    var body: some View {
        VStack(spacing:0) {
            Image(systemName: imageName)
                .resizable()
                .aspectRatio(contentMode: .fit)
                .padding(5)
                .frame(width: 40, height: 40, alignment: .center)
                .background(Color(self.currentView == tab ? .blue : .white).opacity(0.2))
                .foregroundColor(Color(self.currentView == tab ? .blue : .black))
                .cornerRadius(6)
        }
        .frame(width: 100, height: 50)
        .onTapGesture { self.currentView = self.tab }
        .padding(paddingEdges, 15)
    }
}

The ShowModalTabBarItem is also simple. It contains the style for the custom TabBar item and it attach the action to show the modal to the view with the onTapGestureModifier.

public struct ShowModalTabBarItem: View {
    let radius: CGFloat
    let action: () -> Void

    public init(radius: CGFloat, action: @escaping () -> Void) {
        self.radius = radius
        self.action = action
    }

    public var body: some View {
        VStack(spacing:0) {
            Image(systemName: "plus.circle.fill")
                .resizable()
                .aspectRatio(contentMode: .fit)
                .frame(width: radius, height: radius, alignment: .center)
                .foregroundColor(Color(.systemBlue))
                .background(Color(.white))
                .cornerRadius(radius/2)
                .overlay(RoundedRectangle(cornerRadius: radius/2).stroke(Color(.blue), lineWidth: 2))

        }
        .frame(width: radius, height: radius)
        .onTapGesture(perform: action)
    }
}

Screen1, Screen2 and ScreenModal are full screen VStack view that defined the content for each screen. The important part is the definition of the title on Screen1 and Screen2 to modify the navigation bar using the navigationBarTitle modifier.
In the Screen1 view there's also a NavigationLink that let us navigate to a detail/second level screen. As you remember in the MainView we defined a NavigationView as container of the custom TabBar with the current content. This let us keep the TabBar only on the first level of navigation and it when the user enters in the details screen.

struct Screen1: View {
    var body: some View {
        VStack {
            Spacer()
            HStack {
                Spacer()
                Text("Screen 1")
                    .font(.system(size: 20))
                    .bold()
                Spacer()
            }
            HStack {
                NavigationLink(destination: ScreenDetail()) { Text("Show detail") }
            }
            Spacer()
        }
        .frame(minWidth: 0, maxWidth: .infinity, minHeight: 0, maxHeight: .infinity, alignment: .topLeading)
        .background(Color(.yellow).opacity(0.2))
        .navigationBarTitle("Screen 1")
    }
}

//...

struct Screen2: View {
    var body: some View {
        VStack {
            Spacer()
            HStack {
                Spacer()
                Text("Screen 2")
                    .font(.system(size: 20))
                    .bold()
                Spacer()
            }
            Spacer()
        }
        .frame(minWidth: 0, maxWidth: .infinity, minHeight: 0, maxHeight: .infinity, alignment: .topLeading)
        .background(Color(.purple).opacity(0.2))
        .navigationBarTitle("Screen 2")
    }
}

//...

struct ScreenModal: View {
    var body: some View {
        VStack {
            Spacer()
            HStack {
                Spacer()
                Text("Screen 2")
                Spacer()
            }
            Spacer()
        }
        .frame(minWidth: 0, maxWidth: .infinity, minHeight: 0, maxHeight: .infinity, alignment: .topLeading)
        .background(Color(.red).opacity(0.2))
        .edgesIgnoringSafeArea(.all)
    }
}

Conclusion

You can find all the code shown in this post in this Github repo. Apple has done a great job with SwiftUI and I hope that the framework will receive in the future updates all the missing UIKit pieces (while still missing a lot of stuff on the web/Safari side). If you already used powerful declarative framework like React or React Native you will feel at home (seems like a copy of each other 😊). Stay tuned for other post about SwiftUI and Combine soon. ❤️.

How to: enable Hermes JavaScript engine in your React Native app

Fabrizio Duroni — Fri, 07 Feb 2020 08:59:54 +0000

React native 0.60.4 has a new cool feature for Android: a new JavaScript engine called Hermes. Let's see how you can turn it on in your React Native application to get all its benefits.

As you already may know, there has been some complains in the past related to the performance of React Native on the Android platform. One of the main reason was due to a big difference in the React Native architecture implementation between Android and iOS: the JavaScript engine used to execute your code. On iOS React Native uses the JavaScript Core engine exposed in the iOS SDK. On Android the SDK doesn't offer the same feature, so the React Native Android implementation embeds a compiled version of the JavaScript Core engine. As a consequence of this fact the engine used on Android didn't receive the regular updates that the iOS counterpart received on each system major update, and was also not optimized for React Native and generally speaking for executing JavaScript code for mobiles apps. This is the reason why the Facebook React Native team decided to create Hermes, an open source JavaScript engine optimized for mobile apps.

Which benefits does the new Engine bring to the table? As reported in the presentation blog post, there were a few key metrics kept in consideration by the Facebook React Native team:

For JavaScript-based mobile applications, user experience benefits from attention to a few primary metrics:

The time it takes for the app to become usable, called time to interact (TTI)

The download size (on Android, APK size)

Memory utilization

That seems really cool!! Hermes is available starting from React Native 0.60.4. Now the question is: how can you start to use it? Let's see how we enabled this new cool new engine in the lm group mobile apps (did you remember how much we love React Native?) while we were doing the upgrade to the latest version of React Native in order to enable AndroidX in our apps.

Implementation

The first thing to do is to set the enableHermes option to true in the React Native project configuration. This is typically done in the build.gradle app file or, if you have one, in your react.gradle custom gradle file at app level.

project.ext.react = [
  /// ...other options...
  enableHermes: true
]

Then we need to tell to ProGuard (if you're using it) to keep some Hermes classes.

-keep class com.facebook.hermes.unicode.** { *; }

In the official documentation these are all the step needed to activate Hermes. So we added these configurations to our apps and we launched our app, but we got the following error.

2020-01-17 22:04:30.194 5745-6293/it.app E/SoLoader: couldn't find DSO to load: libhermes.so
2020-01-17 22:04:30.646 5745-6293/it.app E/AndroidRuntime: FATAL EXCEPTION: create_react_context
    Process: it.app, PID: 5745
    java.lang.UnsatisfiedLinkError: couldn't find DSO to load: libhermes.so
        at com.facebook.soloader.SoLoader.doLoadLibraryBySoName(SoLoader.java:738)
        at com.facebook.soloader.SoLoader.loadLibraryBySoName(SoLoader.java:591)
        at com.facebook.soloader.SoLoader.loadLibrary(SoLoader.java:529)
        at com.facebook.soloader.SoLoader.loadLibrary(SoLoader.java:484)
        at com.facebook.hermes.reactexecutor.HermesExecutor.<clinit>(HermesExecutor.java:20)
        at com.facebook.hermes.reactexecutor.HermesExecutorFactory.create(HermesExecutorFactory.java:27)
        at com.facebook.react.ReactInstanceManager$5.run(ReactInstanceManager.java:952)
        at java.lang.Thread.run(Thread.java:761)

As the error says, the compilation is failing because gradle is not able to find one the shared libraries used by Hermes. If you think well we are also missing a part in our setup: we said that React Native contains a compiled version of Hermes, but we are not telling to gradle where it can pick the aar file that contains it. Let's fix this problem with the help of the React Native upgrade tool.

First we need to add to the repository section in the main gradle file a new maven repository (that is contained in the node_modules of the app).

//....

allprojects {
    repositories {
      //....
      maven { url("$rootDir/../node_modules/jsc-android/dist") }
      //....
    }
}

//....

Then we need to declare the Hermes compiled version as dependencies in the build.gradle file.

//...

debugImplementation files("../../node_modules/hermes-engine/android/hermes-debug.aar")
qaReleaseImplementation files("../../node_modules/hermes-engine/android/hermes-release.aar")
releaseImplementation files("../../node_modules/hermes-engine/android/hermes-release.aar")

//...

As you can see from above we needed to link the aar version of Hermes specifically for each build variant we have. We also need to rename our qa flavor to qaRelease and link it to the hermes-release.aar file. Why? Because our QA build configuration inherits from the release one, and the react.gradle contained in the React Native itself (node_modules/react-native/react.gradle) does some checks based on the flavor name and, if it contains release, it performs some additional operations for apps with Hermes enabled related to the generation of the sourcemap and the removal of the debugger libraries (not needed for a release build). Below you can find the parts that do checks on the variant name.

//...

if (enableHermes) {
  doLast {
    def hermesFlags;
    def hbcTempFile = file("${jsBundleFile}.hbc")
    exec {
      if (targetName.toLowerCase().contains("release")) {
        // Can't use ?: since that will also substitute valid empty lists
        hermesFlags = config.hermesFlagsRelease
        if (hermesFlags == null) hermesFlags = ["-O", "-output-source-map"]
        } else {
          hermesFlags = config.hermesFlagsDebug
          if (hermesFlags == null) hermesFlags = []
        }

        if (Os.isFamily(Os.FAMILY_WINDOWS)) {
          commandLine("cmd", "/c", getHermesCommand(), "-emit-binary", "-out", hbcTempFile, jsBundleFile, *hermesFlags)
      } else {
        commandLine(getHermesCommand(), "-emit-binary", "-out", hbcTempFile, jsBundleFile, *hermesFlags)
      }
    }

    //....
  }
}

//...
def isRelease = targetName.toLowerCase().contains("release")
def libDir = "$buildDir/intermediates/transforms/"
def vmSelectionAction = {
    fileTree(libDir).matching {
        if (enableHermes) {
            // For Hermes, delete all the libjsc* files
            include "**/libjsc*.so"

            if (isRelease) {
                // Reduce size by deleting the debugger/inspector
                include '**/libhermes-inspector.so'
                include '**/libhermes-executor-debug.so'
            } else {
                // Release libs take precedence and must be removed
                // to allow debugging
                include '**/libhermes-executor-release.so'
            }
        } else {
            // For JSC, delete all the libhermes* files
            include "**/libhermes*.so"
        }
    }.visit { details ->
        def targetVariant = ".*/transforms/[^/]*/${targetPath}/.*"
        def path = details.file.getAbsolutePath().replace(File.separatorChar, '/' as char)
        if (path.matches(targetVariant) && details.file.isFile()) {
            details.file.delete()
        }
    }
}

Conclusion

Hermes is one of the cool new features contained in the new version of React Native 😎. Stay tuned for more updates and see how we are using all of them here at lm group.

Originally published at https://www.fabrizioduroni.it on January 18, 2020.

Implement offline tracking with Google Analytics in your Progressive Web App

Fabrizio Duroni — Sat, 21 Dec 2019 10:39:14 +0000

PWA offer great native alike offline capabilities. But what about tracking? In this tutorial I will show you how simple it is to implement offline tracking with Google Analytics in your PWA.

As you may already understood from my previous post, I felt in love with PWA. For the ones "late to the party" of PWA, let's see the definition of what they are:

Progressive Web Apps are user experiences that have the reach of the web, and are:

Reliable - Load instantly and never show the downasaur, even in uncertain network conditions.

Fast - Respond quickly to user interactions with silky smooth animations and no janky scrolling.

Engaging - Feel like a natural app on the device, with an immersive user experience.

This new level of quality allows Progressive Web Apps to earn a place on the user's home screen.

Basically PWA brings native mobile alike experience to the web. One of the features that PWAs take from mobile apps is offline capabilities. In fact it is possible to develop a web application that works completely offline with the help of Service Workers. But what about tracking stuff when the web app is offline? The standard Google Analytics Web SDK doesn't support offline tracking out of the box. So is it possible to avoid to loose important tracking events when your user is using the PWA offline? Yes it is. Let's find out how we can do it ☺️.

Implementation

Make Google Analytics works offline is as simple as importing a script and call a function! This is possible thanks to Workbox. What is it? Let's the definition reported on its official website:

Welcome, Workbox is a set of libraries and Node modules that make it easy to cache assets and take full advantage of features used to build Progressive Web Apps.

Basically it is a JavaScript library that help developer to build full PWA. It has been developed by the some of the Google Chrome Core Member team. One if its main feature is the support for Google Analytics offline tracking. This is exactly what we need! 😍. Let's see the implementation.

In my service worker file I imported the workbox javascript script with the importScript directive. Then I setup workbox by initializing it (and I also turn the debug features). Then I just need to initialize the workbox Google Analytics plugin and that's it. This is the final implementation.

importScripts('https://storage.googleapis.com/workbox-cdn/releases/4.3.1/workbox-sw.js');

//...other service worker code....

workbox.setConfig({ debug: false })
workbox.googleAnalytics.initialize();

//...other service worker code....

How it works

How does workbox make your GA tracking working when your PWA is offline? The workbox.googleAnalytics plugin setup a new fetch handler that intercepts all the requests made with Google Analytics. These requests are basically network calls done with the Google Analytics Measurement protocol. When your PWA goes offline this handler stores the failed call into an ad-hoc IndexedDB schema called workbox-background-sync. When the network came back the the requests saved are flushed and pushed to the Google Analytics servers as measurement protocol requests. Below you can find a video that shows you the entire flow described above.

One important thing: for all my request you can see two entries in workbox-background-sync schema: one for the page the user is visiting and one for /blog, the homepage of my blog. This is a consequence of the fact that for each page on my website I use the prefetch tag to cache the homepage of the blog on every page on my website (because by watching my tracking in google analytics, I saw that the majority of the visitors of my website goes to the homepage of the blog as second page in the step of their navigation).

Conclusion

Google Analytics offline tracking is another feature that makes PWAs more similar to native mobile apps. As I already said in other posts, the gap between web and native development is closing more and more each day. You can already start to think about giving almost the same user experience to your user on all platforms (web and native). I will say prayer for this end of the year: please Apple don't stay behind your competitor and remember what you said in 2008 (when web technologies where not as advanced as of today) ❤️.

Originally published at https://www.fabrizioduroni.it on December 15, 2019.

Implement a pull to refresh component for you web application

Fabrizio Duroni — Sun, 01 Dec 2019 12:22:23 +0000

Implementing a pull to refresh component in vanilla js for your progressive web app (PWA) it's really easy using cutting edge web technology (service worker, CSS new properties). Let's do it now!

Some months ago I transformed my website into a Progressive Web App (yes, the one you're reading now). By leveraging the power of service workers (and other some cool tricks that I will discuss in other posts 😜) my website page load time is below 50 milliseconds 😮. But with "the great power of service workers comes also great responsibility" (you remember uncle Ben quote, right?), and one of this responsibility is let the user be able to refresh all the content whenever it wants (to check new/update stuff).

Which is a mechanism/UX pattern that every user in the world already know for this kind of functionality? The pull to refresh. The choice of this pattern is also a natural consequence of the fact that, as I already told you previously in another post, Progressive Web App are the technology that fill the gap between web and mobile native app. Unfortunately in the web development world there's not yet a standard component for pull to refresh. This is way in this post I will show you how to implement it from scratch without any JavaScript library/framework. I will only use vanilla JavaScript, HTML, CSS and the service worker message capabilities in combination with the MessageChannel class. The pull to refresh described in this article is available on my site in all the blog pages (go and try it now!!! 😏)
Let's start from the implementation of the UI (HTML and CSS)

UI: HTML and CSS

You already know what we would like to achieve. The pull to refresh UI component should be something that appears at the top of the page when the user scroll beyond the page borders. At some point during the drag gesture the pull to refresh should stop itself from scrolling and show a loader that explain to the user that the content is reloading.
Let's start from the HTML. I added to the page structure a new div that will act as the container of the pull to refresh.
Inside it I added two other divs:

one is used to show a loader/activity indicator that will start to rotate as soon as the user scroll to the maximum pull to refresh point (and as already explained above, at this point the reload of the content should have been started).
the other one is used to show a message to the user that explaining to him/her what it is happening (this is a nice to have that I added because I liked it! 😜)

Below you can find the entire html code snippet.

<div id="pull-to-refresh" class="pull-to-refresh start-pull hidden-pull">
    <div id="pull-to-refresh-loader" class="pull-to-refresh-loader"></div>
    <div id="pull-to-refresh-status" class="pull-to-refresh-status">
        Pull down to refresh
    </div>
</div>

Let's see what I did on the CSS side. The code reported below here is written in SASS (the preprocessor scripting language that is interpreted or compiled into Cascading Style Sheets (CSS)), but you can easily transform it in plain CSS if you need. First of all I used a new CSS property in the html rule: overscroll-behavior-y. This property let the developers change the browser behaviour when the user researches the edge of the page with a scroll gesture. This is a property supported by Chrome, Firefox and Opera (fuck you Safari!!! 😡). By setting it's value to contains, we can for example disable the native browser pull to refresh on Chrome and avoid the page bounce effect when the user starts to overflow the borders while dragging.

Then I defined a property pullable-content that I used on the entire content of the page that I want to move in parallel with the pull to refresh. The next class is pull-to-refresh and contains all the styles needed to layout the pull to refresh in all its states. As you can see I defined all the animation I needed for this UI component here except for the translation applied while dragging that will be computed on the JavaScript side (because this are simple animation and CSS is performant enough for this kind of animations). Last but not least I defined 2 classes to reset the pull to refresh layout status when the pull to refresh is started or has reached the end and starts the refresh of the content (they will be applied, like other contained here, with JavaScript DOM API).

html {
  overscroll-behavior-y: contain;
}

.pullable-content {
  margin-top: 10px
}

.pull-to-refresh {
  height: 100px; 
  background-color: $general-background; 
  margin-top: 55px;
  margin-bottom: 10px;
  box-shadow: inset 0px -2px 6px 1px $divider-color;
  display: flex;
  flex-direction: column;
  justify-content: flex-end;
  align-items: center;
  padding: 10px;

  &.visible-pull {
    visibility: visible;
  }

  &.hidden-pull {
    visibility: hidden;
  }

  .pull-to-refresh-status {
    font-weight: bold;
    font-size: 14px;
  }

  .pull-to-refresh-loader {
    border: 3px solid $primary-color-dark;
    border-top: 3px solid $primary-color-light;
    border-radius: 50%;
    width: 30px;
    height: 30px;
    margin-bottom: 10px;
    opacity: 0;

    &.animate {
      animation: spin 1.25s linear infinite;
    }

    @keyframes spin {
      0% { transform: rotate(0deg); }
      100% { transform: rotate(360deg); }
    }
  }
}

.start-pull {
  transform: translateY(-100px); 
}

.end-pull {
  transform: translateY(-100px) !important;
  transition: 0.4s ease-in-out;
}

JavaScript

On the JavaScript side, I wrote the the pull to refresh widget as a standalone widget that export one single function pullToRefresh(). The first thing that this widget does is to check the browser support for service worker. Then it checks for some HTML component that are needed by the widget by using the invariant function. This HTML components are the loader, the loader message status and the content to be refreshed. The widget will throw an error if one of this HTML component is not present on the page where the it is instantiated.

Then 3 new listener are attached to the 3 touches event on the entire document: 'touchstart', 'touchmove' and 'touchend'. In the 'touchstart' event I get the starting touches coordinates and I prepare the pull to refresh DOM by adding the CSS classes needed with the function preparePullToRefreshToStart(). The touchemove is the core of the widget. In this event I try to understand if the user is doing a drag gesture by using the function isDraggingForPullToRefresh() that does some checks using the window.scrollY property and the yMovement calculated by doing the difference between the gesture starting coordinates (that I get from the touchstart event) and the current touches coordinates.

const dragCurrentPoint = getTouchesCoordinatesFrom(event)
const yMovement = (dragStartPoint.y - dragCurrentPoint.y) * decelerationFactor

When I detect a drag gesture (so as we said above isDraggingForPullToRefresh() == true) I start to check if the pull to refresh is completed with the function isPullToRefreshDragCompleted(), that does a check to understand if the total drag gesture movement is equal to pull to refresh contained DOM element. If this function return false, then the pull to refresh DOM is updated by the function dragUpdate(), that applies some CSS transform that translate the pull to refresh into the viewport to make it more and more visible (and increase the visibility of the loader that it is still stop).

When isPullToRefreshDragCompleted() is true, the user reached the end of the pull to refresh drag gesture and the refresh of the content is started. How do I refresh the content? I send a message to the service worker using the function sendMessageToServiceWorker to refresh the content. When the service worker answers that the refresh of the content is completed we update the pull to refresh status with the message 'Refresh completed' and we close it using the functions setRefreshStatusCompleted() and closePullToRefresh(). In particular the closePullToRefresh() function launches a CSS transform transition animation to close the pull to refresh. To reload the content of the page when the animation is completed I defined a transitionend listener attached to the pullToRefreshElement container element (the one that is animated) that launches a window.location.reload() to reload the page and show the new fresh content. In all this steps I keep track that the refresh phases completed correctly by setting some status flag in a status repository that I create with the function createPullToRefreshStatusRepository().

//...other code...
const createPullToRefreshStatusRepository = () => ({
  refreshStarted: false,
  refreshCompleted: false,
  startRefresh () {
    this.refreshStarted = true
  },
  completeRefresh () {
    this.refreshCompleted = true
  }
})
//...other code...

As I said before, each flag is updated when the correct phase is completed (e.g. a touch listener is launched or the service worker warn us that the refresh is completed).

Below you can find the complete pull to refresh widget code discussed above. Inside it there are also some utilities classes that I use on my website to increase the compatibility on older browser (in this case used only to keep consistencies in the entire website JavaScript code case because a modern browser with Service Worker support is required).

import { sendMessageToServiceWorker } from '../common/service-worker'
import { addCssClass, removeCssClass } from '../common/css-class'
import { getTrackingClientId } from '../common/tracking'

const pullToRefresh = (trackingCategory) => {
  if (!('serviceWorker' in navigator)) {
    return
  }

  const pullToRefreshElement = document.querySelector('#pull-to-refresh')
  const pullToRefreshStatusElement = document.querySelector('#pull-to-refresh-status')
  const pullToRefreshLoaderElement = document.querySelector('#pull-to-refresh-loader')
  const pullableContent = document.querySelector('.pullable-content')

  invariant(pullToRefreshElement instanceof HTMLElement)
  invariant(pullToRefreshStatusElement instanceof HTMLElement)
  invariant(pullToRefreshLoaderElement instanceof HTMLElement)
  invariant(pullableContent instanceof HTMLElement)

  const pullToRefreshElementHeight = pullToRefreshElement.offsetHeight
  const pullToRefreshStatusRepository = createPullToRefreshStatusRepository()
  const decelerationFactor = 0.5
  let dragStartPoint = createTouchCoordinates(0, 0)

  const dragUpdate = (dragMovement, pullToRefreshLoaderOpacity) => {
    pullToRefreshElement.style.transform = `translateY(${dragMovement}px)`
    pullableContent.style.transform = `translateY(${dragMovement}px)`
    pullToRefreshLoaderElement.style.opacity = `${pullToRefreshLoaderOpacity}`
  }

  const isDraggingForPullToRefresh = (yMovement) => window.scrollY <= 0 && yMovement <= 0

  const closePullToRefresh = () => {
    addCssClass(pullToRefreshElement, 'end-pull')
    addCssClass(pullableContent, 'end-pull')
    pullToRefreshElement.style.transform = ''
    pullableContent.style.transform = ''
    pullToRefreshLoaderElement.style.opacity = '0'
  }

  const preparePullToRefreshToStart = () => {
    addCssClass(pullToRefreshElement, 'start-pull')
    removeCssClass(pullToRefreshElement, 'end-pull')
    addCssClass(pullableContent, 'start-pull')
    removeCssClass(pullableContent, 'end-pull')
  }

  const showPullToRefresh = () => {
    addCssClass(pullToRefreshElement, 'visible-pull')
    removeCssClass(pullToRefreshElement, 'hidden-pull')
  }

  const setRefreshingStatus = () => {
    pullToRefreshStatusElement.innerHTML = 'Refreshing'
    addCssClass(pullToRefreshLoaderElement, 'animate')
  }

  const isPullToRefreshDragCompleted = (yAbsoluteMovement) => yAbsoluteMovement >= pullToRefreshElementHeight

  const setRefreshStatusCompleted = () => {
    pullToRefreshStatusElement.innerHTML = 'Refresh completed'
    addCssClass(pullToRefreshElement, 'hidden-pull')
    removeCssClass(pullToRefreshElement, 'visible-pull')
  }

  const resetPullToRefreshStatus = () => {
    pullToRefreshStatusElement.innerHTML = 'Pull down to refresh'
    removeCssClass(pullToRefreshLoaderElement, 'animate')
  }

  document.addEventListener('touchstart', (event) => {
    dragStartPoint = getTouchesCoordinatesFrom(event)
    preparePullToRefreshToStart()
  }, { passive: false })

  document.addEventListener('touchmove', (event) => {
    const dragCurrentPoint = getTouchesCoordinatesFrom(event)
    const yMovement = (dragStartPoint.y - dragCurrentPoint.y) * decelerationFactor
    const yAbsoluteMovement = Math.abs(yMovement)

    if (isDraggingForPullToRefresh(yMovement) && !pullToRefreshStatusRepository.refreshStarted) {
      event.preventDefault()
      event.stopPropagation()
      showPullToRefresh()

      if (isPullToRefreshDragCompleted(yAbsoluteMovement)) {
        pullToRefreshStatusRepository.startRefresh()
        dragUpdate(0, 1)
        setRefreshingStatus()
        sendMessageToServiceWorker({ message: 'refresh', url: window.location.href, clientId: getTrackingClientId(), trackingCategory }).then(() => {
          pullToRefreshStatusRepository.completeRefresh()
          setTimeout(() => {
            setRefreshStatusCompleted()
            closePullToRefresh()
          }, 1500)
        })
      } else {
        dragUpdate(yAbsoluteMovement - pullToRefreshElementHeight, yAbsoluteMovement / pullToRefreshElementHeight)
      }
    }
  }, { passive: false })

  document.addEventListener('touchend', () => {
    if (!pullToRefreshStatusRepository.refreshStarted) {
      closePullToRefresh()
    }
  }, { passive: false })

  pullToRefreshElement.addEventListener('transitionend', () => {
    if (pullToRefreshStatusRepository.refreshCompleted) {
      window.location.reload()
    } else {
      resetPullToRefreshStatus()
    }
  })
}

const createTouchCoordinates = (x, y) => ({ x, y })

const createPullToRefreshStatusRepository = () => ({
  refreshStarted: false,
  refreshCompleted: false,
  startRefresh () {
    this.refreshStarted = true
  },
  completeRefresh () {
    this.refreshCompleted = true
  }
})

const invariant = (statement) => {
  if (!statement) {
    throw new Error('Pull to refresh invariant failed')
  }
}

const getTouchesCoordinatesFrom = (event) => {
  return createTouchCoordinates(
    event.targetTouches[0].screenX,
    event.targetTouches[0].screenY
  )
}

export { tryToActivatePullToRefresh }

The widget above is instantiated the blog main js file index.blog.js file. Below you can find the startup code that I placed inside a load event listener (that on my website code does also other things).

import { pullToRefresh } from './blog/pull-to-refresh'

//...other code...

window.addEventListener('load', () => {
  //...other code...
  pullToRefresh(trackingCategory)
  //...other code...
})

Service Worker

One thing I didn't show in detail is how we can achieve the communication between the JavaScript code that runs on the web page and the service worker. In the code above I shown you the function sendMessageToServiceWorker(). What does this function do? Inside it I create a new MessageChannel and bind its port1.onmessage listener to a new one created ad-hoc to return the response that this function will receive from the service worker. The port2 of the MessageChannel is sent to the service worker along with the message string label using the function postMessage on the service worker container controller property. This property contains the current instance of the service worker. If you already worker in the past on some IFrame communication, postMessage is not something new (it's the same function actually 😏).

const sendMessageToServiceWorker = (message) => {
  return new Promise((resolve, reject) => {
    const messageChannel = new MessageChannel()
    messageChannel.port1.onmessage = (event) => {
      if (event.data) {
        if (event.data.error) {
          reject(event.data.error)
        } else {
          resolve(event.data)
        }
      }
    }
    if (navigator.serviceWorker && navigator.serviceWorker.controller) {
      navigator.serviceWorker.controller.postMessage(message, ([messageChannel.port2]))
    }
  })
}

Then In the service worker I added a new message listener that receive all the messages sent with the function above. At the moment I have only the refresh message. This is why all the code to manage this message is contained inside it (just to explain the reason to the clean code fluffy evangelist 😅). In the listener I check for the correctness of the event label, and then I start to clean up the cache from all the assets and pages of the blog with (this is why for example the createDeleteOperationsForImages checks that the url contains the posts path, in order to avoid the deletion of home images). This delete cache function are all execute in a Promise.all call. When this function completes the execution of all the delete operation, I call sendRefreshCompletedMessageToClient() to warn the original JavaScript code (the port1.onmessage listener we saw above) that the refresh operation has been completed.

//...other service worker code...

self.addEventListener('message', (event) => {
  const isARefresh = (event) => event.data.message === 'refresh'

  const createDeleteOperationFor = (url, siteCache, requests) => siteCache
    .delete(requests
    .find((request) => request.url === url))

  const createDeleteOperationsForImages = (siteCache, requests) => requests
    .filter((request) => request.url.endsWith('.jpg') && request.url.includes('posts'))
    .map((request) => siteCache.delete(request))

  const sendRefreshCompletedMessageToClient = (event) => event.ports[0].postMessage({refreshCompleted: true})

  if (isARefresh(event)) {
    caches.open(siteCacheName).then((siteCache) => {
      siteCache.keys().then((requests) => {
        const deleteRequestToBeRefreshed = createDeleteOperationFor(event.data.url, siteCache, requests)
        const deleteRequestsForImagesToBeRefreshed = createDeleteOperationsForImages(siteCache, requests)
        Promise.all([
          deleteRequestToBeRefreshed, 
          ...deleteRequestsForImagesToBeRefreshed, 
          sendAnalyticsEvent(event.data.clientId, '{{ site.data.tracking.action.pull_to_refresh }}', event.data.trackingCategory, '{{ site.data.tracking.label.body }}')
        ])
          .then(() => sendRefreshCompletedMessageToClient(event))
          .catch(() => sendRefreshCompletedMessageToClient(event))
      })
    }) 
  }
})

//...other service worker code...

Conclusion

All the code above is everything needed to implement your own pull to refresh widget.
As you can see, it is not too difficult to create a pull to refresh UX that almost matches the experience given by a mobile native app. Service Workers, modern CSS and HTML and vanilla JavaScript let you create beautiful native alike experience that can make you user fall in love with you web product before they install your app ❤️ (or maybe they will just stick to your site because they hate mobile apps or because you hate mobile apps and you don't want to develop a new one 😃).

Originally published at https://www.fabrizioduroni.it on November 16, 2019.

React Native + Typescript, love at first sight. Setup in an existing app

Fabrizio Duroni — Mon, 23 Sep 2019 12:50:33 +0000

In this post I will show you how to setup React Native + Typescript in an existing app.

In the last few months at lastminute.com group I worked on
the following project: rebuild the native mobile apps of the main brands lastminute.com, Volagratis and Rumbo with a new interface and new features.
Let's compare the old and the new home of the lastminute.com app. The changes are quite impressive 😎.

For this "app relaunch" project we decided to use React Native (I already talked about this framework in some previous posts that you can find in the archive section). We didn't rewrite the apps from scratch. We decided to integrated React Native in the existing code base and:

use Native Modules to reuse some native code we already had in place for some features (for example the login).
write the new stuff completely in React Native whenever possible.

We also took another important decision when we started the project: we choose TypeScript instead of Javascript as main language to write our React Native stuff. What is TypeScript? It is an open-source programming language developed and maintained by Microsoft. They describe it on its official website with the following definition:

Typescript is a typed superset of Javascript that compiles to plain Javascript. Any browser. Any host. Any OS. Open
source.

What does it means? It means that TypeScript is basically "Javascript on steroid": it provides optional, static type checking at compile time. Since it is a superset of JavaScript, all JavaScript code is valid TypeScript code.
TypeScript is helpful if you are a developer that comes from other strongly typed language and with you have a strong knowledge of Object Oriented programming because it let you reuse a lot of the programming technique you already know.

React Native officially supports Javascript. How can we setup React Native + Typescript? In this post we will see how to integrate React Native and Typescript in an existing app and we will add a new screen done in React Native where we will show the photo of the day that we will read from the Nasa open API. Below you can find what we will achieve. The first screen is a standard native screen. The second one is a React Native screen.

Let's start to setup our project for React Native and TypesScript. First, React Native integration. For this task we can just follow the React Native documentation regarding the integration with existing app.
Then we can start to integrate TypeScript. We will use yarn as dependencies manager instead of npm (you can use it also to install the dependencies needed to setup React Native in an existing app). Yarn is a fast, reliable and secure dependencies manager released by Facebook in October 2016.
Our project directories structure will be the one contained in the screenshots below. The existing native codebase is contained inside the ios and android folders.

So let's start by installing TypeScript and the types for React Native. We can do it with the following commands from the root of our project:

yarn add --dev typescript
yarn add --dev @types/react @types/react-native

After that we need to configure TypeScript in our project. We can start to do that by running the following command:

yarn tsc --init --pretty --jsx react

Now we have a new file in the root of our project: the tsconfig.json file. This file is the configuration file for the tsc, the TypeScript compiler. We can customize it for our needs (React). In particular, we need to enable the option allowSyntheticDefaultImports to allow default imports from modules with no default export. We also customized the baseUrl and paths options. By settings them in this way and by adding a package.json file inside the app folder with name: "app", we can place all our source code in the app folder and when we need to import a class we will set the path starting from the app base folder (so basically we are defining the root of our source code in a nice way for our imports).

Below you can find the complete tsconfig.json file configured for our needs.

{
  "compilerOptions": {
    "target": "es2015",
    "module": "es2015",
    "allowJs": true,
    "checkJs": true,
    "jsx": "react-native",
    "removeComments": true,
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "moduleResolution": "node",
    "baseUrl": "app",
    "paths": {
      "app/*": [ "./*" ]
    },
    "allowSyntheticDefaultImports": true
  },
  "typeRoots": [
    "./node_modules/@types"
  ],
  "types": [
    "react",
    "react-native",
    "jasmine",
    "jest"
  ],
  "exclude": [
    "node_modules",
    "app/__tests__",
    "rn-cli.config.js"
  ]
}

After that we need to install the React Native TypeScript Transformer.
This transformer will allow the React Native cli to automatically transpile our TypeScript code into Javascript on demand. This is the command to install the transformer:

yarn add --dev react-native-typescript-transformer

After that we need to configure the React Native cli to actually use the transformer by adding the following configuration to the rn-cli.config.js file (create it in the project root directory). This file is the React Native configuration file.

module.exports = {
  getTransformModulePath() {
    return require.resolve('react-native-typescript-transformer');
  },
  getSourceExts() {
    return ['ts', 'tsx'];
  },
};

That's all for the main source code setup. Now we can start to set up also the testing infrastructure. We will use jest, a testing framework from Facebook, and typemoq, a TypeScript specific mocking library.
To use Jest with Typescript we will install ts-jest, a TypeScript preprocessor with source map support for Jest that lets us use Jest to test projects written in TypeScript.

yarn add --dev ts-jest
yarn add --dev typemoq

As you remember from the directory structure I show you above, the __tests__ folder is not in the usual React Native project position. It is placed inside the app folder. To be able to put our test in this folder we need to add to it a jest.config.js file and set some custom option for related to the module resolution. Below you can find the entire file with all the details.

module.exports = {
    'preset': 'react-native',
    'moduleFileExtensions': [
        'ts',
        'tsx',
        'js',
    ],
    'rootDir': '../..',
    'transform': {
        '^.+\\.(js)$': '<rootDir>/node_modules/babel-jest',
        '\\.(ts|tsx)$': '<rootDir>/node_modules/ts-jest/preprocessor.js',
    },
    'testMatch': ['**/__tests__/**/*.(ts|tsx|js|jsx)?(x)', '**/?(*.)(spec|test).(ts|tsx|js|jsx)?(x)'],
    'testPathIgnorePatterns': [
        '\\.snap$',
        '<rootDir>/node_modules/',
        'jest.config.js',
    ],
    'moduleDirectories': [
        'node_modules',
        '../',
    ],
};

We are now ready to write our app. Basically the screen that shows the nasa photo is the NasaPhotoViewerScreen. This component uses NasaPhotoInformationComponent and some React Native standard component to show the information that comes from the API. The informations are fetched using the NasaPhotoService. The NasaPhotoViewerScreen and the NasaPhotoService are glued together using the Model-View-Presenter architecture in the NasaPhotoComponentPresenter. As you can see from the code below, TypeScript has a syntax that is similar to other language like Java, C# (and many other 😎).

export class NasaPhotoService {
  async retrieve(): Promise<any> {
    return fetch('https://api.nasa.gov/planetary/apod?api_key=1cygunHJsSwDug6zJjF3emev3QAP8yFLppohLuxb')
      .then((response) => response.json())
  }
}

...

export class NasaPhotoComponentPresenter {
  private nasaPhotoRepository: NasaPhotoRepository
  private nasaPhotoView: NasaPhotoView

  constructor(nasaPhotoView: NasaPhotoView, nasaPhotoRepository: NasaPhotoRepository) {
    this.nasaPhotoRepository = nasaPhotoRepository
    this.nasaPhotoView = nasaPhotoView
  }

  async onStart(): Promise<void> {
    try {
      const nasaPhoto = await this.nasaPhotoRepository.load();
      this.nasaPhotoView.showValid(nasaPhoto);
    } catch (_) {
      this.nasaPhotoView.showAn("Network error")
    }
  }
}

...

export class NasaPhotoViewerScreen extends React.Component<Props, State> implements NasaPhotoView {
  private readonly presenter: NasaPhotoComponentPresenter

  constructor(props: Props) {
    super(props)
    this.state = {
      photo: NasaPhoto.empty()
    }
    this.presenter = new NasaPhotoComponentPresenter(
      this,
      new NasaPhotoRepository(new NasaPhotoService(), new NasaPhotoAdapter())
    )
  }

  componentWillMount() {
    this.presenter.onStart()
  }

  showAn(error: string): void {
    alert(error)
  }

  showValid(photo: NasaPhoto): void {
    this.setState({photo})
  }

  render() {
    return (
      <ScrollView style={styles.container}>
        <Image
          style={styles.image}
          {% raw %}source={{uri: this.state.photo.url}}{% endraw %}
        />
        <NasaPhotoInformationComponent
          title={this.state.photo.title}
          date={this.state.photo.date}
          description={this.state.photo.description}
        />
      </ScrollView>
    );
  }
}

interface Props {
  name: string
}

interface State {
  photo: NasaPhoto
}

const styles = StyleSheet.create({
  container: {
    width: "100%",
    height: "100%"
  },
  image: {
    width: "100%",
    height: 220,
    resizeMode: "cover",
  }
});

You can check all the code of the sample described above in this github repository and see all the TypeScript components I created for the app I shown you above. That's it!!! React Native + TypeScript: ♥️ love at first sight ♥️.

Originally published at https://www.fabrizioduroni.it on July 4, 2018.