DEV Community: Praveen Puglia

White-labeling, Vue CLI & PWA

Praveen Puglia — Sun, 18 Jul 2021 08:43:20 +0000

Original Post : https://praveenpuglia.com/blog/white-labeling-vue-cli-pwa/

At Voicezen, I have been fortunate enough to work on a platform that has to be white-labelled. But what does it mean to be white-labelled?

A white-label product is a product or service produced by one company (the producer) that other companies (the marketers) rebrand to make it appear as if they had made it. - Wikipedia

We serve the same product to multiple clients with various needs and to their users, it should look like as if the client company made it. This requires paying attention to a bunch of things like

Brand colors.
Typography.
Logos.
Other aspects of theming.
Nomenclature customization.
Sitle title / PWA installer customization etc

Today, I am briefly going to touch upon how we achieve the last one. I'll probably write more about the other points in later posts.

We chose to tackle the last point first because that's the immediate and persistent thing that users notice when they open any app on browser. The title stays on the tab as long as they are on the app so it makes sense to start there.

If the app is a PWA, it becomes necessary to get the illusion right by making sure that the browser prompt for the app installer reflects the client's title and logo.

On the engineering side, it means that we have to dynamically generate the manifests for our PWA, the logos, the title etc.

We use Vue CLI and along with that the Vue CLI PWA Plugin. The first step is to have the assets / app-icons for each client in a separate, public directory. With a Vue CLI project we get a root level public directory. Here's what that looks like after our changes.

.
├── img
│   └── icons
│       ├── batman
│       │   ├── android-icon-144x144.png
│       │   ├── android-icon-192x192.png
│       │   ├── android-icon-36x36.png
│       │   ├── android-icon-48x48.png
│       │   ├── android-icon-72x72.png
│       │   ├── android-icon-96x96.png
│       │   ├── apple-icon-152x152.png
│       │   ├── favicon-16x16.png
│       │   ├── favicon-32x32.png
│       │   └── favicon.ico
│       ├── superman
│       │   ├── android-icon-144x144.png
│       │   ├── android-icon-192x192.png
│       │   ├── android-icon-36x36.png
│       │   ├── android-icon-48x48.png
│       │   ├── android-icon-72x72.png
│       │   ├── android-icon-96x96.png
│       │   ├── apple-icon-152x152.png
│       │   ├── favicon-16x16.png
│       │   ├── favicon-32x32.png
│       │   └── favicon.ico
│       └── default
│           ├── android-icon-144x144.png
│           ├── android-icon-192x192.png
│           ├── android-icon-36x36.png
│           ├── android-icon-48x48.png
│           ├── android-icon-72x72.png
│           ├── android-icon-96x96.png
│           ├── apple-icon-152x152.png
│           ├── favicon-16x16.png
│           ├── favicon-32x32.png
│           └── favicon.ico
├── index.html
└── robots.txt

We have 2 clients and then the default client which is a fallback. We'll talk about that in a bit.

The next piece of the puzzle is to identify which client are we building the dist for. For that, we use .env files. When we build our application, we specify the client by adding the following in our .env.production file.

VUE_APP_CLIENT_ID=batman

For convenience, we have created a bunch of .env.CLIENT.local files so we can build client specific dists without having to modify .env.production again and again.

.env.batman.local
.env.superman.local

In each of these we set NODE_ENV=production and the VUE_APP_CLIENT_ID to their respective IDs. This allows us to do something like this.

# generate production dist for batman
yarn build --mode=batman

Note that our icon directory name matches the VUE_APP_CLIENT_ID variable.

The next part is to use this ID to resolve things like

What should be the human readable title for this client?
Which icons should be put into the manifest?
Which colors to use? etc.

For this, we use a simple map that gives us all the necessary information.

// client-metadata.js
export const clientMetadata = {
  batman: {
    title: "The Dark Knight!",
    colors: {
      primary: "#080808",
      accent: "#AE8875"
    }
  },
  superman: {
    title: "Man of Steel",
    colors: {
      primary: "#bb070e",
      accent: "#0099f7"
    }
  },
  default: {
    title: "Voicezen",
    colors: {...}
  }
}

With this, we now move to our final setup which is to instruct Vue CLI to genreate all the stuff necessary for a particular client.

// vue.config.js

// we use this package to get the current git hash.
const { gitDescribeSync } = require("git-describe");

const allClientsMetadata = require("./src/assets/client-metadata.json");
const clientId = process.env.VUE_APP_CLIENT_ID ?? "default";

// get the metedata.
const clientMetadata = allClientsMetadata[clientId];

// notify which client we are working with
console.log(`🚀 Building for Client : ${clientMetadata.title}`);

module.exports = {
  // setup pwa plugin options
  pwa: {
    name: clientMetadata.title,
    workboxPluginMode: "InjectManifest",
    workboxOptions: {
      // since we use InjectManifest option, we provide our own
      // service worker to start with.
      swSrc: "./src/sw.js",
      swDest: "service-worker.js",
    },
    manifestOptions: {
      short_name: clientMetadata.title,
      icons: [
        {
          src: `img/icons/${clientId}/android-icon-36x36.png`,
          sizes: "36x36",
        },
        {
          src: `img/icons/${clientId}/android-icon-48x48.png`,
          sizes: "48x48",
        },
        {
          src: `img/icons/${clientId}/android-icon-72x72.png`,
          sizes: "72x72",
        },
        {
          src: `img/icons/${clientId}/android-icon-96x96.png`,
          sizes: "96x96",
        },
        {
          src: `img/icons/${clientId}/android-icon-144x144.png`,
          sizes: "144x144",
        },
        {
          src: `img/icons/${clientId}/android-icon-192x192.png`,
          sizes: "192x192",
        },
      ],
      background_color: "#ffffff",
      display: "standalone",
    },
    themeColor: clientMetadata.colors.primary,

    iconPaths: {
      favicon32: `img/icons/${clientId}/favicon-32x32.png`,
      favicon16: `img/icons/${clientId}/favicon-16x16.png`,
      appleTouchIcon: `img/icons/${clientId}/apple-icon-152x152.png`,
    },
    assetsVersion: gitDescribeSync().hash, // this allows easy cache-busting
  },
};

Here's what the input service worker file looks like.

// src/sw.js

/* eslint-disable */
// This is the code piece that GenerateSW mode can't provide for us.
// This code listens for the user's confirmation to update the app.
self.addEventListener("message", (e) => {
  if (!e.data) {
    return;
  }

  switch (e.data) {
    case "skipWaiting":
      self.skipWaiting();
      break;
    default:
      // NOOP
      break;
  }
});

workbox.core.clientsClaim(); // Vue CLI 4 and Workbox v4, else
// workbox.clientsClaim(); // Vue CLI 3 and Workbox v3.

// The precaching code provided by Workbox.
self.__precacheManifest = [].concat(self.__precacheManifest || []);
// workbox.precaching.suppressWarnings(); // Only used with Vue CLI 3 and Workbox v3.
workbox.precaching.precacheAndRoute(self.__precacheManifest, {});

This setup ensures that our PWA manifests and assets are generated for the client we are building the dist. You can tweak the PWA plugin configuration to add more details for different browsers and platforms.

How to use AVIF today!

Praveen Puglia — Thu, 08 Jul 2021 17:24:08 +0000

Original Post: https://praveenpuglia.com/blog/how-to-use-avif-today/

Short one!

I am currently working on revamping my website, which I am hoping will be up soon! I am taking this opportunity to move away from Jekyll and choosing to go with Eleventy. To be honest, I am enjoying it quite a bit. Hopefully a post on that will soon be up.

One of the interesting things that I wanted to try out is to serve AVIF images because boy it compresses! Hoof! You can literally get the same quality in less than half the size.

Here' the thing though. AVIF support is pretty flaky at the moment. That means I would have to serve AVIF image to browsers that do support it and serve a diff format to those who don't.

Good'ol <picture> element comes to rescue. We declare multiple sources pointing to the same image in diff formats. The browsers pickup the best image they support. So Chrome and Opera end up serving AVIF to us and others serve the WEBP version.

<picture>
  <source srcset="home-banner.avif" type="image/avif" />
  <source srcset="home-banner.webp" type="image/webp" />
  <img
    class="home-banner"
    decoding="async"
    loading="lazy"
    src="home-banner.webp"
    alt="Home Banner"
  />
</picture>

If you are wondering why we are using that <img> tag inside <picture>, please head over to MDN.

That's it!

How to Import Markdown Files in Vue CLI + TypeScript Projects

Praveen Puglia — Wed, 17 Feb 2021 04:55:34 +0000

Recently, I came across the need to import a markdown file in a Vue component and realized that the internet is full of confusing solutions. Fiddled around for a few hours and found out that it's really quite simple.

Here's a little bit about the setup I have.

Vue CLI
TypeScript

I am also using the Vue Markdown component. What I wanted to do is

Write the content in a .md file.
Import it in my component.
Pass it to Vue Markdown as the source prop.

So I imported the markdown file in my component and the first thing I saw is the squiggly telling me this.

TS2307: Cannot find module './query-guide.md'.

That's because TypeScript doesn't know where to find this module or is it even a module. To fix this, I went to shims-vue.d.ts and declared any markdown file as a module.

declare module "*.md";

...and the squiggly was gone.

NOTE: You can do this do any kind of file. In my project I also declare all scss files to be module so I can import them directly in my component. Read more on why I do that.

Once that's sorted, I came across this.

Module parse failed: Unexpected character '#' (1:0)

You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders

Which means that Webpack has no idea about how to load a markdown file as a module. Quick googling pointed out that I need to use raw-loader to get the content of the file as is.

A loader for webpack that allows importing files as a String.

I installed raw-loader as dev dependency.

yarn add -D raw-loader

Next I needed to direct webpack to use it via vue.config.js. Here's what that configuration looks like.

module.exports = {
  configureWebpack: {
    module: {
      rules: [
        {
          test: /\.md$/i,
          loader: "raw-loader",
        },
      ],
    },
  },
};

That did it for me. I was able to import markdown file in my component just like any other module and use it.

import guideContent from "./query-guide.md";

Hope this helps you save a lot of time fiddling around.

Originally posted on praveenpuglia.com.

A better DX for GraphQL Requests

Praveen Puglia — Mon, 01 Feb 2021 18:48:26 +0000

If you have worked with GraphQL and been frustrated while skimming through the requests in the Network panel, you aren't alone.

I am talking about this.

This kills a lot of time while trying to find out the exact request you are looking for since the requests look all the same.

Some time ago, I decided to do something about this to make the debugging experience better and faster and I stumbled upon Apollo HTTP Link documentation.

When setting up Apollo, we provide a bunch of options and link is one of them. For HTTP Requests, we use apollo-link-http.

Especially this part.

uri: the URI key is a string endpoint or function resolving to an endpoint -- will default to "/graphql" if not specified.

The main focus here is that uri can be a function and that function receives the entire query object. That object contains things like variables and query and also the operationName.

Now, as you can imagine, that can come in handy in trying to distinguish the requests from each other.

While setting up link in apollo configuration, we can change he uri to include the operationName as a URL parameter and it comes up in the Network panel with the same.

import { createHttpLink } from 'apollo-link-http';

// In your configuration...
link: createHttpLink({
  uri: ({ operationName }) => {
    return `${options.httpEndpoint}/?gqlOp=${operationName}`;
  }
})

Here's the result.

Ain't that neat? Hope this helps you save some debugging time.

My GraphQL Schema & Types Generation Workflow

Praveen Puglia — Tue, 26 Jan 2021 06:08:30 +0000

At Voicezen, we use multiple GraphQL endpoints. We also use Vue with TypeScript. Naturally, we need type definitions for everything the endpoints expose.

We end up needing both the schema from an Introspection Query and the types to use in TypeScript land. The schema is used to build a tool that dynamically builds a UI for running queries / mutations from the UI itself based on the parameters they accept. More on the tool may be in a later post.

We have an opinionated setup and like to have our types generated in a certain way. Examples -

Enums should be UPPERCASE and separated by underscores.
We prefer interfaces over types.

We keep the generated types & schema at /src/graphql/types directory.

We use .env file to store the endpoint details in environment variables. This not only helps us with schema generation but also with the Vue Apollo setup.

GraphQL Code Generator helps us with all of this. Here are the packages we use & for convenience we have a script to run the generator.

"devDependencies": {
  "@graphql-codegen/cli": "^1.7.0",
  "@graphql-codegen/introspection": "^1.18.0",
  "@graphql-codegen/typescript": "1.7.0"
},
"scripts": {
  "gql:setup": "node ./scripts/gen-gql-types.js"
}

The actual generator is the gen-gql-types.js. You can keep it anywhere but we prefer to keep it in the project root inside scripts directory.

Here's what the .env file looks like.

VUE_APP_GRAPHQL_SAMURAI=http://localhost:8001/samurai
VUE_APP_GRAPHQL_NINJA=http://localhost:8001/ninja
VUE_APP_GRAPHQL_DORAEMON=http://localhost:8001/doraemon

Finally, the generator script.

// Imports
const generate = require('@graphql-codegen/cli').generate;
const dotenv = require('dotenv-flow');
const chalk = require('chalk');

// We use dotenv to get access to the current environment variables.
const envVars = dotenv.config().parsed;
if (envVars.error) {
  throw envVars.error;
}

// From the variables, we pick all the variables that start with
// VUE_APP_GRAPHQL
const gqlEndpoints = Object.keys(envVars).filter((key) =>
  key.startsWith('VUE_APP_GRAPHQL')
);

function generateTypes() {
  const dir = `${process.cwd()}/src/graphql/types`;
  console.log(
    chalk.bgBlueBright(chalk.black(`Output directory set to : ${dir}`))
  );

  gqlEndpoints.forEach((entry) => {
    const endpoint = entry.substring(16).toLowerCase();

    const typesPath = `${dir}/${endpoint}.ts`;
    const schemaPath = `${dir}/${endpoint}.json`;

    console.log(
      `Generating GraphQL Types for ${endpoint} in - ${chalk.bold.blue(
        endpoint
      )}.ts`
    );
    console.log(
      `Generating GraphQL Schema for ${endpoint} in - ${chalk.bold.blue(
        endpoint
      )}.json`
    );
    generate(
      // GraphQL Codegen Configuration
      {
        overwrite: true,
        schema: `${envVars[entry]}/graphql`,
        config: {
          declarationKind: 'interface',
          skipTypename: true,
          namingConvention: {
            typeNames: 'change-case#pascalCase',
            enumValues: 'upper-case#upperCase',
            transformUnderscore: true
          }
        },
        generates: {
          [typesPath]: {
            plugins: ['typescript']
          },
          [schemaPath]: {
            plugins: ['introspection']
          }
        }
      },
      true
    )
      .then(() => {
        console.log(
          chalk.green(
            `Finished types & schema generation for ${chalk.bold.greenBright(
              endpoint
            )} endpoint.`
          )
        );
      })
      .catch(() => {
        console.log(
          chalk.red(
            `Types & schema generation failed for ${chalk.bold.redBright(
              endpoint
            )} endpoint.`
          )
        );
      });
  });
}

generateTypes();

Every time we build the project, we run the gql:setup script as a prerequisite and it fetches the latest schema and types for us to work with.

This setup gives us good control over what sort of code we want to generate. It plays nice with multiple graphql endpoints as well since all we have to do to is add an entry in .env file and re-run the script.

We also use some chalk magic for colorful logging in console.

Hope this helps and if it does, do let me know in the comments.

Originally posted at praveenpuglia.com.
Cover Courtesy : Photo by Luca Bravo on Unsplash