Tuanddd-sajari-ui NPM

Sajari UI

This is a work in progress of the Sajari UI component library, based on Tailwind.

The approach

We're going to build components using Tailwind but rather than expose the className prop on all components and let it be a free-for-all, we're going to go for an approach similar to styled system using style props but rather than m={4} we have to use the full className so purgeCSS works correctly so our version of that would be margin="m-4". We're also using TypeScript so all classNames have to be in their own type - e.g. a Margin type would contain all possible margin classNames, including any variants.

Adding it to a project

1. Install the packages

To install the production package run yarn add @sajari-ui/core.

To develop locally, you can link the package using yarn:

Run yarn link in this folder (/packages/sajari-ui). This will link all local installs to this package.
In the consuming project run yarn link "@sajari-ui/core" and then yarn add @sajari-ui/core@link:0.1.0 to install the package.

Peer dependencies

yarn add -D postcss postcss-clean postcss-cli autoprefixer
yarn add tailwindcss

2. Create stylesheet

Create the base stylesheet. Later this will be included in the package.

/* purgecss start ignore */
@tailwind base;

@tailwind components;
/* purgecss end ignore */

@tailwind utilities;

3. Setup PostCSS

Create a postcss config with this as the content:

const { tailwindConfig } = require("@sajari-ui/core");

tailwindConfig.purge = {
  mode: "all",
  content: ["./src/**/*.tsx", "../../node_modules/@sajari-ui/core/dist/*.js"],
};

module.exports = {
  plugins: [
    require("tailwindcss")(tailwindConfig),
    require("autoprefixer"),
    require("postcss-clean")({
      level: 2, // Merge duplicated declarations
    }),
  ],
};

🚨 NOTE: The tailwindConfig.purge.content paths need to be updated to suit your application.

🚨 NOTE: The CSS will be purged for production builds only. To enable it always, you can set tailwindConfig.purge.enabled to true. Unfortunately we have to set mode to all to allow for the classNames in our package to stay in the CSS.

4. Add scripts to package.json for build

Preact CLI and Next come with PostCSS already setup so all you need to do is import the CSS file in your app and it'll get processed via PostCSS. Sadly Create React App isn't so awesome so you need to create an npm script to do it.

Before:

"scripts": {
  "start": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject"
}

After:

"scripts": {
  "build:css": "postcss src/styles/index.css -o src/index.css",
  "watch:css": "postcss -w src/styles/index.css -o src/index.css",
  "prestart": "npm run prebuild",
  "prebuild": "npm run build:css",
  "start": "run-p watch:css start:react",
  "start:react": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject"
}

🚨 NOTE: You need to adjust the paths to the CSS file depending on your application. You'll also need to import the processed CSS - /src/index.css in the example above in your app.

Example

See examples/create-react-app for using it in a React application.

Props & Prop Categories

The types created can be used in props as-is or as categorized sets.

CommonProps - display, margin, padding
LayoutProps - display, width, height, minWidth, minHeight, maxWidth, maxHeight
PositionProps - position, zIndex, offset (top, right, bottom, left)
FlexProps - flexDirection, flexWrap, alignItems, alignContent, justifyContent, order
FlexItemProps - alignSelf, flex, flexGrow, flexShrink

The index.ts file in /src/types also exports the relevant keys for the categories. These are useful for mapping the props to classNames.

Generating ClassNames

When consuming the prop categories, you can use two helpers to generate the classNames:

mapClassNames (/src/utils/styles/map-classnames.ts) - The arguments are props and keys. Keys needs to contain the keys for the props you wish to convert to classNames.
filterObject (/src/utils/object/filter.ts) - Filter out keys from props - useful for doing {...rest} type stuff where you don't want the props to bleed to the DOM element.

Creating types

We've created a build script to build the TypeScript types based on the Tailwind config. In /scripts/types there are two files:

types.js - An array of objects containing all the types we want to build.
build.js - The actual build script to parse the config and create the types.

If you need to add a missing type or update them, you can run yarn build:types. The types are committed to source control so this shouldn't need to be run often - only when a change is made to the Tailwind config or we upgrade Tailwind and they add features.

TODO

Better docs
Create remaining Types that are missing
Create more prop categories that are missing
Decide which prop categories apply to all components (e.g. FlexItemProps)