Axil Shared Components Library

Getting started

In this directory, first run:

yarn install

Once a yarn lock file is generated, then you can write TypeScript components in the src directory.

Writing components

Each component will be a directory that includes an index.tsx and a styles.module.css.

index.tsx

This is a standard TS component with one exception.

The styles must be imported like import cssClasses from "./styles.module.css".

Then, you can apply styles like className={cssClasses['css-className']}.

Icons

Notice in the src directory, there is a folder called icons.

These are components that directly implement SVG's/images to work-around issues with importing them through Rollup.JS.

For example if you want to add an SVG icon, you would make a new Functional Component file in the icons directory that looks something like this:

export default function SomeIcon() {
  return (
    <svg
      width='24'
      height='24'
      viewBox='0 0 24 24'
    >
      <path id='Path_245' d='M0,0H24V24H0Z' fill='none' />
      <path
        id='Path_246'
        d='M12,8,6,14l1.41,1.41L12,10.83l4.59,4.58L18,14Z'
        fill='#fff'
      />
    </svg>
  );
}

Note: You can edit the styles directly SVG in this file directly by adding the style={{ }} attribute to the svg tag.

Once the SVG component is saved, you can import and use the SVG Component like:

import SomeIcon from "../icons/SomeIcon"

export default function ExampleWithIcon() {
  return (
    <div>
      <h1>Icon Example</h1>
      <SomeIcon />
    </div>;
  )
}

Once you have added your component to the src directory, then make sure you update the index.ts file to export it properly.

export { default as NewComponent } from './new-component';
export * from './new-component';

Bundling Components

Using Rollup.JS (https://rollupjs.org/guide/en/) we are able to bundle files together and publish them to NPM.

In package.json there is the script "build": "rollup -c".

This bundles our src directory into a compiled lib folder.

After running yarn build, we can update the version of the package accordingly.

Publishing Components

First: Make sure you have an NPM account AND are a listed maintainer of the NPM package.

Login in to NPM using npm login.

Run npm publish.

Note: If you didn't update the version in the package it will fail with an authentication error and cancel publishing.

How this works

In this directory, you will notice:

Folders: lib and src,
Package file: package.json,
Rollup config: rollup.config.js,
TS config: tsconfig.json,

Rollup.JS

In order to use Rollup.JS, we need to provide a rollup.config.js file.

import { nodeResolve } from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';

import typescript from 'rollup-plugin-typescript2';
import postCSS from 'rollup-plugin-postcss';

import pkg from './package.json';

export default {
  input: 'src/index.ts',
  output: [
    {
      file: './lib/cjs/index.js',
      format: 'cjs',
    },
    {
      file: './lib/esm/index.js',
      format: 'es',
    },
  ],
  external: [...Object.keys(pkg.peerDependencies || {})],
  plugins: [
    commonjs(),
    typescript({
      typescript: require('typescript'),
    }),
    postCSS({
      plugins: [require('autoprefixer')],
    }),
    nodeResolve(),
  ],
};

This config file takes in our input then we can specify the output to which Rollup outputs our code as a usable JS module.

Notice we are using dependencies nodeResolve, commonjs,typescript, and postcss.

These plugins help process various file types, such as css and typescript, which aren't supported by default.

TypeScript

In order to properly use TypeScript, our tsconfig.json file looks like:

{
  "compilerOptions": {
    "outDir": "lib/esm",
    "module": "esnext",
    "target": "es5",
    "lib": ["es6", "dom", "es2016", "es2017"],
    "jsx": "react-jsx",
    "declaration": true,
    "moduleResolution": "node",
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "esModuleInterop": true,
    "noImplicitReturns": true,
    "noImplicitThis": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "suppressImplicitAnyIndexErrors": true,
    "allowSyntheticDefaultImports": true
  },
  "include": ["src/**/*.ts*"],
  "exclude": ["node_modules", "lib"],
}

Note: In order to use CSS files, we have to make sure our module can interpret the file.

To solve this we add a global.d.ts file to our src directory and in it we have:

declare module '*.module.css' {
  const classes: { readonly [key: string]: string };
  export default classes;
}

This is where we can also define any other types our library may need.