Using in OmniWeb

Since we are gradually onboarding the design system in OmniWeb, we use a technique where you have to declare that your package is using the components from the design system. This is will change when we have onboarded a "critical mass" of the OmniWeb-packages 😉

Preparing for production

To use components from the design system, you have to do two things in addition to installing the components. One; enable purging (remove unused CSS in production-builds¹) and two; tell OmniWeb to include the TailwindCSS-file for that module.

1) Install the component(s)

Install the component(s) you are going to use along with the @ntds/core package, like so:

yarn add @ntds/core @ntds/button

2) Enable CSS-purging on your package

We need to tell OmniWeb that we are expecting the package of interest to use TailwindCSS util-classes and that the purging-process need to look for usage in certain files.

We do this by adding a tailwind.purge.js file with the following content in the root of the OmniWeb-package you want to add support in, like so:

// Place this file here: packages/MY_OMNIWEB_PACKAGE/tailwind.purge.js

module.exports = {
  /**
   * Used in the Webpack plugin "TailwindCustomPurgePlugin" to determine if any of the BUNDLED components in the package
   * should be used in the purging of the Tailwind-css-file or not.
   *
   * (CSS) Purging = remove unused class-names based on usage
   *
   * The plugin mention over uses the same process described here: https://tailwindcss.com/docs/optimizing-for-production
   *
   * @param {string} filepath The relative path (to the __dirname of this file)
   * @param {function} defaultTest Matches all components starting with a Capital letter (file types: js|jsx|tsx)
   * @returns {boolean}
   */
  test: (filepath, defaultTest) => defaultTest(filepath),
};

For most packages there should be no need to use any other than the standard test. This test (as stated in the code-comments over), are considering every component that starts with a capital letter and have .js, .jsx or .tsx extension.

Only bundled files gets considered

OmniWeb only pass files to the test-function that actually are part of the production build. That is to say, only files that is imported somewhere in the Webpack dependency tree gets considered. This prevents tests, jumpstart-files and any other support-files to affecting what util-classes gets purged or not.

Not active in development

It's worth mentioning that when you start OmniWeb in development-mode using yarn dev, no purging will be performed. Purging is only used to optimize for production.

In development ALL Tailwind-classes are included in the CSS.

Debugging the purging-process

To see what files are being used and ignored in the purging-process, enable the DEBUG flag ntds:tailwind-purge-plugin before you run yarn build, like so:

export DEBUG="ntds:tailwind-purge-plugin"

yarn build

Example output:

ntds:tailwind-purge-plugin ⦿ match: packages/nt-mygames/src/views/ListView/ListView.tsx
ntds:tailwind-purge-plugin 𝗑 match: packages/nt-mygames/src/index.tsx

⦿ match → the file was included and the purge-process will look for TailwindUtil-classes
𝗑 miss → the file was ignored

Whether we get a miss or a match, is the result of the test in the tailwind.purge.js-files returns true or false.

3) Tell OmniWeb to include the CSS-file

Lastly (and temporarily) wee need ensure that the TailwindCSS-file gets severed alongside the package when needed. Include the following import in the root-point of your package, typically the Routes-file.

// Activate Tailwind
import '@ntds/core/css/ntds-tailwind.css';

Using with jumpstart

Jumpstart have built-in support for the TailwindCSS-configuration of the design system and does require any further steps (just make sure that you are using the latest version).

How to update jumpstart

You can update jumpstart to the latest version running this command:

yarn global upgrade jumpstart

When you start jumpstart your component, it can be a good idea to reset the jumpstart-cache by using the --clear-cache flag:

jumpstart MyComponent.tsx --clear-cache

This will make sure that you get the latest CSS generated from the latest @ntds/core Tailwind-configuration.

Purging is a technique used in PostCSS that searches all of your code for usage of classes and removes any CSS-class from the production build that it does not find.⤴