css-in-js-preprocessor

Preprocess your css-in-js files to replace references to design system tokens with actual values

Hello friend.

CSS-in-JS is awesome and powerful, but do you miss the ability to preprocess your styles with your token values (like .less & .sass) without having to have your tokens as a dependency?

Well, that's where css-in-js-preprocessor is here to save the day!

With css-in-js-preprocessor, you can use your design system tokens to build your styles while also auto-MAGICALLY replacing the references to them with the actual values! Thus, eliminating the need for a dependency on a tokens package and ensuring that your values are up to date on every compile.

Version: 1.0.0

preprocessor

Preprocesses your css-in-js file by replacing references to design system tokens with actual values

Since v1.0.0

Param	Type
file The string contents of the file	string
tokens Object containing the key/value pairs representing the token/value	Record<string, unknown>
tokensImport The string path of the package or file imported for the tokens	string
custom Array of custom processors	Array<(file: string) => string>

Returns: {(file: string) => string}

Import

import { preprocessor } from 'css-in-js-preprocessor';

Examples

Note

These examples overwrite the original files. I recommend that you preprocess your compiled files as part of your compile process so that you always have reference to the tokens in source. That way if the token value ever changes, the values in your js styles will be updated with the next compile. If you are operating on the compiled files, you will want to overwrite the file you're preprocessing with the updated version which is why the examples are shown the way they are.

Here's an example of how you might add it to your compile process. In this case, I'm running a TypeScript compile and then executing a node script that uses css-in-js-preprocessor:

"scripts": {
  "compile": "tsc && node bin/style-preprocess.js"
}

Basic Example

my-tokens.json

{
  "backgroundAccentColor": "#ccc",
  "fontSizeMedium": 12,
  "paddingMedium": 16
}

styles.js

import tokens from './my-tokens';

export const someStyle = {
  backgroundColor: tokens.backgroundAccentColor,
  fontSize: tokens.fontSizeMedium,
  padding: tokens.paddingMedium,
};

style-preprocess.js

This file should be executed at the end of your compile or build process.

const { preprocessor } = require('css-in-js-preprocessor');
const fs = require('fs');
const path = require('path');
const tokens = require('./my-tokens');

// Setup preprocessor:
const preprocess = preprocessor(tokens, './my-tokens');

// Read the file:
let file = fs.readFileSync('./styles.js', 'utf8');

// Preprocess the file:
file = preprocess(file);

// Save the file:
// Note that this example overwrites the original file which 
// should be the compiled version of the file and not the 
// original source file. 
fs.writeFileSync(path.join('./styles.js'), file, 'utf8');

styles.js

This is the updated version after the preprocessor has run.

export const someStyle = {
  backgroundColor: '#fff',
  fontSize: 12,
  padding: 16,
};

Custom Preprocessors

If you have additional preprocessing work that you'd like to do, you can pass in an array of functions that take in the preprocessed file where you can do your additional work and return the new string version of the file:

style-preprocess.js

This file should be executed at the end of your compile or build process.

Modify the above example with this:

const changePaddingToMargin = file => file.replace('padding: ', 'margin: ');
const addTimeStamp = file => `${file}\n\n// Compiled: ${(new Date()).toString()}`;

// Setup preprocessor:
const preprocess = preprocessor(tokens, './my-tokens', [changePaddingToMargin, addTimeStamp]);

styles.js

This is the updated version after the preprocessor has run.

export const something = {
  backgroundColor: '#fff,
  fontSize: 12,
  margin: 16,
};

// Compiled: Tue Mar 16 2021 06:15:06 GMT-0500 (Central Daylight Time)

Multiple Files

preprocessor conveniently returns a function so you can setup your base preprocessor one time and loop through the files you want to preprocess:

const { preprocessor } = require('css-in-js-preprocessor');
const fs = require('fs');
const path = require('path');
const tokens = require('./my-tokens');

// Setup preprocessor:
const preprocess = preprocessor(tokens, './my-tokens');

const files = (fs.readdirsync(pathToDir) || []).filter(file => file.endsWith('.js'));

for (const fileName of files) {
  // Read the file:
  let file = fs.readFileSync(path.join(pathToDir, fileName), 'utf8');

  // Preprocess the file:
  file = preprocess(file);

  // Save the file:
  // Note that this example overwrites the original files which 
  // should be the compiled versions of the files and not the 
  // original source files. 
  fs.writeFileSync(path.join(pathToDir, fileName), file, 'utf8');
}

Imports

For your token imports, you may use:

• default import
• named import
• default require
• named require

You may also name your tokens anything you wish:

import tokens from './my-tokens';
import { myTokens } from './my-tokens';
const tokenObj = require('./my-tokens');
const { tokenzzz } = require('./my-tokens');

css-in-js-preprocessor will pick up the name of your tokens object and get to work.

---

Package Contents

Within the module you'll find the following directories and files:

package.json
CHANGELOG.md -- history of changes to the module
LICENSE
README.md -- this file
/lib
  └───/es5
      └───index.d.ts - 48 Bytes
      └───index.js - 289 Bytes
    └───/preprocessor
      └───index.d.ts - 679 Bytes
      └───index.js - 1.29 KB
    └───/_private
      └───preprocessTokens - 2.16 KB
      └───removeImport - 1.23 KB
      └───utils - 1.16 KB
  └───/es6
      └───index.d.ts - 48 Bytes
      └───index.js - 48 Bytes
    └───/preprocessor
      └───index.d.ts - 679 Bytes
      └───index.js - 1.12 KB
    └───/_private
      └───preprocessTokens - 1.98 KB
      └───removeImport - 1.08 KB
      └───utils - 942 Bytes

License

MIT