DEV Community: Quan Pham

Create your own React icons library and publish to NPM automatically

Quan Pham — Thu, 16 Sep 2021 18:33:16 +0000

Cover photo by Harpal Singh on Unsplash

You have a set of SVG icons in your React project. And you want to separate them out from your current codebase, make them a standalone library so you can reuse these icons later in another projects. This tutorial of mine can help you easily create your own icon library and automatically publish it to the npm.

Fact: I’ve learnt this from watching tailwindlabs/heroicons

TLDR: If you want to skip this post and want to check the final work instead, please click here react-icon-boilerplate. Feel free to clone my repo and create you own lib.

Setup

First, you create an empty folder and initialize a new package.json file.

mkdir react-icons-boilerplate && cd react-icons-boilerplate
yarn init -y
yarn add -D svgo rimraf

We will use svgo to optimize our SVG icon files since:

SVG files, especially those exported from various editors, usually contain a lot of redundant and useless information. This can include editor metadata, comments, hidden elements, default or non-optimal values and other stuff that can be safely removed or converted without affecting the SVG rendering result.

You create a raw folder which contains all your SVG icon files that need to be optimized.

mkdir raw

This is my SVG sample file, I will place it in the raw folder raw/plus-outline.svg

<?xml version="1.0" encoding="UTF-8"?>
<svg width="24px" height="24px" viewBox="0 0 24 24" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
    <title>CC3942F2-90B2-4E94-AADC-715CECF64617</title>
    <defs>
        <rect id="path-1" x="0" y="0" width="24" height="24"></rect>
    </defs>
    <g id="200720" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
        <g id="TP.io---Documentation---Icons" transform="translate(-444.000000, -181.000000)">
            <g id="Small---24-x-24px" transform="translate(208.000000, 141.000000)">
                <g id="Icons/Guideline-Preview" transform="translate(176.000000, 0.000000)">
                    <g id="Add" transform="translate(60.000000, 40.000000)">
                        <mask id="mask-2" fill="white">
                            <use xlink:href="#path-1"></use>
                        </mask>
                        <use id="Mask" fill-opacity="0" fill="#FFFFFF" xlink:href="#path-1"></use>
                        <path d="M12,2.25 C17.3847763,2.25 21.75,6.61522369 21.75,12 C21.75,17.3847763 17.3847763,21.75 12,21.75 C6.61522369,21.75 2.25,17.3847763 2.25,12 C2.25,6.61522369 6.61522369,2.25 12,2.25 Z M12,3.75 C7.44365081,3.75 3.75,7.44365081 3.75,12 C3.75,16.5563492 7.44365081,20.25 12,20.25 C16.5563492,20.25 20.25,16.5563492 20.25,12 C20.25,7.44365081 16.5563492,3.75 12,3.75 Z M12.75,7.46052632 L12.75,11.249 L16.5394737,11.25 L16.5394737,12.75 L12.75,12.749 L12.75,16.5394737 L11.25,16.5394737 L11.25,12.749 L7.46052632,12.75 L7.46052632,11.25 L11.25,11.249 L11.25,7.46052632 L12.75,7.46052632 Z" id="Combined-Shape" fill="#00497A" mask="url(#mask-2)"></path>
                    </g>
                </g>
            </g>
        </g>
    </g>
</svg>

It does looks really long and noisy. Let’s optimize it!

Optimize SVG files

To easily run svgo command with some options, you add a script into the package.json like below. Every time you run the command, it will re-create a folder named optimized which contains all icons that are optimized from the raw folder.

{
  "name": "react-icons-boilerplate",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "scripts": {
    "optimize": "rimraf ./optimized & svgo -q -p 8 -f ./raw -o ./optimized"
  },
  "devDependencies": {
    "rimraf": "^3.0.2",
    "svgo": "^2.6.1"
  }
}

You can run yarn optimize to see the result. Also, you need to have a svgo configuration file in order to add as many plugins as possible that help us to clear all the redundant data. Here is my svgo.config.js for example:

module.exports = {
  multipass: true,
  js2svg: {
    indent: 2,
    pretty: true,
  },
  plugins: [
    { name: 'preset-default' },
    'sortAttrs',
    'removeScriptElement',
    'removeDimensions',
    'removeScriptElement',
    'removeDimensions',
  ],
};

Before come up with these plugins, I tried to mess around on this website SVGOMG - SVGO’s Missing GUI

This is my optimized result file.

Build React icons

We need some packages in order to transform our SVG files into React SVG components and then convert JSX syntax into CJS and ESM module format. We use babel and svgr.

yarn add -D @babel/core @babel/preset-react @svgr/cli @svgr/core camelcase terser

You get this build script from here: script/build.js. Basically, this script read the optimize folder, get all icons and convert them into JSX by using svgr and then transform the React code into CJS and ESM module format by babel.

The original icon filename will become the component’s name in CamelCase plus suffix Icon. For example with plus-outline.svg file we will have component name PlusOutlineIcon.

The package supports for Typescript by generate a declare file .d.ts for each icons.

This is the usage of the icon component when the packages is installed and used by other project

import { PlusOutlineIcon } from 'react-icons-boilerplate'

Since this build script I created to fit my icons set so these line are little special, but you can change them to fit yours icons set.

// line 12 to 23
const svgReactContent = await svgr(
  content,
  {
    icon: false,
    replaceAttrValues: { '#00497A': "{props.color || '#00497A'}" },
    svgProps: {
      width: 24,
      height: 24,
    },
  },
  { componentName }
);

Now, we add this build script to our package.json

...
"scripts": {
    "optimize": "rimraf ./optimized & svgo -q -p 8 -f ./raw -o ./optimized",
    "build": "yarn optimize && node scripts/build.js"
},
...

If you run yarn build you will have a dist folder as the result. You see something similar to this

And don’t forget to add these lines in your package.json before publishing it.

{
  // ...
  "main": "./dist/cjs/index.js",
  "module": "./dist/esm/index.js",
  "files": [
    "dist"
  ],
  // ...
}

Git

Now you can push all your work to your GitHub repository. I won’t go through this since I assume we all know how to do it.

Publish

When you have the final dist folder as the result now you can publish this to npm.
It can be easily done by login into the npm account via NPM CLI npm login and run the npm publish --access public after that. But I want to leverage GitHub Actions and atlassian/changesets to do this automatically for me.

changesets

To install and init changesets:

yarn add -D @changesets/cli @changesets/changelog-github
yarn changeset init

You will have .changeset folder and its configuration file config.json inside. Here is my config:

{
  "$schema": "https://unpkg.com/@changesets/config@1.6.1/schema.json",
  "changelog": [
    "@changesets/changelog-github",
    { "repo": "mikunpham/react-icon-example" }
  ],
  "commit": false,
  "linked": [],
  "access": "restrict",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

If you want to publish your package as a public package, you have to change the “access” property from restricted to public.

For the first release, you have to run yarn changeset. It will ask what kind of Semantic Versioning you want to bump your package and write a short summary about it. It will create something like this and you now can commit this file to your repository.

GitHub Release Action

changesets has a very detailed instruction to implement their action into your GitHub workflows here https://github.com/changesets/action
Or you can get my release.yml here release.yml.

Now, commit everything and push onto Github.

If everything is OK, a github-action bot will create a PR just like this and wait for you to merge.

After merging, a release will be created

And go check your npm now.

What’s next

From now, whenever you have new icons, do these following step.

Add them to the raw folder.
yarn build
yarn changeset , select major/minor/patch bump and write summary.
Commit
…
Profit!

Final

A very long long post huh? BUT it just takes you 30’ max to get everything up and run for the first time and mostly 2-3’ to add new icons and release new version after that.

Thank you all the contributors of babel, svgo, svgr and changesets for making our dev life easier than ever.

Thank you for reading till the end 🎉

TypeScript: A Type Narrowing Story

Quan Pham — Fri, 07 May 2021 10:41:12 +0000

There is one day, you have to pull data from 2–3 APIs or even more at the same time just to render them on one little screen. The structure of data each API goes from slightly to completely different. You can’t force your Back-end developers to do a refactor on his code to make those returned data look the same.

What would you do???

My first attempt is to re-map the data from APIs into a common format. Then I realize it is really hard to unify those data. So I come up with this code.

type SomeKindOfInterfaceHere = { hello: string };
type AnotherInterface = { world: boolean };

interface MappedDataFromApi {
  id: string | number;
  data: string[] | SomeKindOfInterfaceHere | AnotherInterface;
}

function AReactComponent(props: MappedDataFromApi) {
  if (props.data.hello) {
    return <>display {props.data.hello} </>
  }

  if (props.data.world) {
    return <>display {props.data.world} </>
  }

  return props.data.map(d => (<>display array item: {d}</>));
}

It works perfectly. Things render fine. But the Typescript starts yelling and prevents me from compiling codes.

Property ‘hello’ does not exist on type >‘SomeKindOfInterfaceHere | AnotherInterface | string[]’.
Property ‘hello’ does not exist on type ‘AnotherInterface’.(2339)

To satisfy Typescript, I refactor my codes into this

interface MappedDataFromApi {
  id: string | number;
  contentVR?: SomeKindOfInterfaceHere;
  documentsInfo?: string[];
  bundleInfo?: AnotherInterface;
}

function AReactComponent(props: MappedDataFromApi) {
  if (props.contentVR) {
    return <>display {props.contentVR.hello} </>
  }

  if (props.bundleInfo) {
    return <>display {props.bundleInfo.world} </>
  }

  return props.documentsInfo && props.documentsInfo.map(d => (<>display array item: {d}</>));
}

Of course, Typescript now can feel better. We’ve created another problem - some might say:

Hey mate, this interface is bad. It has so many ? It is arbitrary. How can I re-use it elsewhere? How can I maintain your code once you not here? Those properties look mysterious.

Sounds cruel but reasonable!

OK, let try once again. I separate my interface into smaller pieces. It looks neat, no more ?, but…

interface VerificationRequest {
  uuid: string;
  content: SomeKindOfInterfaceHere;
}

interface SingleVerification {
  id: number;
  documents: string[];
}

interface Bundle {
  id: number;
  info: AnotherInterface;
}

type MappedDataFromApi = VerificationRequest | SingleVerification | Bundle;

function AReactComponent(props: MappedDataFromApi) {
  if (props.content) {
    return <>display {props.content.hello} </>
  }

  if (props.info) {
    return <>display {props.info.world} </>
  }

  return props.documents.map(d => (<>display array item: {d}</>));
}

Brrrrr, Typescript yells at me again with the same problem as before.

Property ‘content’ does not exist on type ‘MappedDataFromApi’.
Property ‘content’ does not exist on type ‘SingleVerification’.(2339)

Luckily, Typescript has these gems to help us write better codes and have good typing in this case.

Using type predicates

With this method, I can add some utility functions to support Typescript detect what kind of interface I’m working on. The codes will look like this.

function isVerificationRequest(props: MappedDataFromApi): props is VerificationRequest {
  return !!(props as VerificationRequest).content;
}

function isSingleVerification(props: MappedDataFromApi): props is SingleVerification {
  return Array.isArray((props as SingleVerification).documents);
}

function isBundle(props: MappedDataFromApi): props is Bundle {
  return !!(props as Bundle).info;
}

function AReactComponent(props: MappedDataFromApi) {
  if (isVerificationRequest(props)) {
    return <>display {props.content.hello} </>
  }

  if (isBundle(props)) {
    return <>display {props.info.world} </>
  }

  return props.documents.map(d => (<>display array item: {d}</>));
}

Beautiful, right? 👏👏👏

One thing is that this style will make my final JS code size a little bigger. You can check the JS compile version on Typescript Playground.

Discriminated unions

With this method, I can add one common property with literal type into interfaces. The codes will look like this.

interface VerificationRequest {
  uuid: string;
  content: SomeKindOfInterfaceHere;
  kind: 'verification-request';
}

interface SingleVerification {
  id: number;
  documents: string[];
  kind: 'single-verification';
}

interface Bundle {
  id: number;
  info: AnotherInterface;
  kind: 'bundle';
}

type MappedDataFromApi = VerificationRequest | SingleVerification | Bundle;

function AReactComponent(props: MappedDataFromApi) {
  switch (props.kind) {
    case 'verification-request':
      return <>display {props.content.hello} </>
    case 'single-verification': 
      return props.documents.map(d => (<>display array item: {d}</>));
    case 'bundle':
      return <>display {props.info.world} </>
    default:
      return null;
  }
}

It looks neat too. You can even make Exhaustiveness checking with this style. But on the other hand, if you want to re-use the interfaces elsewhere, you have to Omit the common property or manually add it to your data collection. If not, Typescript once again yelling at you.

Here are what I’m talking about:

// drop "kind" by create a new Omit type
type NewSingleVerification = Omit<SingleVerification, "kind">
function getSingleVerification(): NewSingleVerification {
  return {
    id: 1,
    documents: ['education', 'license'],
  };
}

// OR
function getSingleVerification(): SingleVerification {
  return {
    id: 1,
    documents: ['education', 'license'],

    // manual add this
    kind: 'single-verification',  
  };
}

This is a huge downside to me since it makes UI issues involve in the business logic where they shouldn’t.

Conclusion

These are all solutions that I can come up with. Each one has its own downside, but at least the last 2 can cover almost my team's concerns about type checking and everyone can comprehend the codes easily.
If you have any other solutions, please comment below.

Thank For Reading