Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including generate-atomic-css with all npm packages installed. Try it out:

var generateAtomicCss = require("generate-atomic-css")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

generate-atomic-css v1.2.35

Generate Atomic CSS

generate-atomic-css

Generate Atomic CSS

Repository is on GitLab Coverage View dependencies as 2D chart Downloads/Month Test in browser Code style: prettier MIT License

Other siblings of this package:

Table of Contents

Install

npm i generate-atomic-css

Consume via a require():

const {
  genAtomic,
  version,
  headsAndTails,
  extractFromToSource,
} = require("generate-atomic-css");

or as an ES Module:

import {
  genAtomic,
  version,
  headsAndTails,
  extractFromToSource,
} from "generate-atomic-css";

or for web pages, as a production-ready minified script file (so-called "UMD build"), straight from CDN:

<script src="https://cdn.jsdelivr.net/npm/generate-atomic-css/dist/generate-atomic-css.umd.js"></script>
// in which case you get a global variable "generateAtomicCss" which you consume like this:
const {
  genAtomic,
  version,
  headsAndTails,
  extractFromToSource,
} = generateAtomicCss;

This package has three builds in dist/ folder:

TypeKey in package.jsonPathSize
Main export - CommonJS version, transpiled to ES5, contains require and module.exportsmaindist/generate-atomic-css.cjs.js23 KB
ES module build that Webpack/Rollup understands. Untranspiled ES6 code with import/export.moduledist/generate-atomic-css.esm.js20 KB
UMD build for browsers, transpiled, minified, containing iife's and has all dependencies baked-inbrowserdist/generate-atomic-css.umd.js22 KB

⬆ back to top

API

Three methods are exported:

const {
  genAtomic,
  version,
  headsAndTails,
  extractFromToSource,
} = require("generate-atomic-css");
// or
import {
  genAtomic,
  version,
  headsAndTails,
  extractFromToSource,
} from "generate-atomic-css";
NameWhat it does
genAtomicIt's the main function which generates CSS
versionExports version from package.json, for example, string 1.0.1
headsAndTailsExports a plain object with all heads and tails
extractFromToSourceExtracts "from" and "to" from source in rows, separated by pipes

⬆ back to top

genAtomic() - input API

It's a function, takes two arguments: input string and optional options object:

genAtomic(str[, originalOpts])

For example:

import {
  genAtomic,
  version,
  headsAndTails,
  extractFromToSource,
} from "generate-atomic-css";
const source = `a

/* GENERATE-ATOMIC-CSS-CONFIG-STARTS
.pb$$ { padding-bottom: $$px !important; } | 5 | 10

.mt$$ { margin-top: $$px !important; } | 1
GENERATE-ATOMIC-CSS-CONFIG-ENDS
GENERATE-ATOMIC-CSS-CONTENT-STARTS */

tralala

/* GENERATE-ATOMIC-CSS-CONTENT-ENDS */

z`;
const result = genAtomic(source, {
  includeConfig: false,
  includeHeadsAndTails: false,
});
console.log(`result:\n${result}`);
// => "a
//
// .pb5  { padding-bottom:  5px !important; }
// .pb6  { padding-bottom:  6px !important; }
// .pb7  { padding-bottom:  7px !important; }
// .pb8  { padding-bottom:  8px !important; }
// .pb9  { padding-bottom:  9px !important; }
// .pb10 { padding-bottom: 10px !important; }
//
// .mt0 { margin-top:   0 !important; }
// .mt1 { margin-top: 1px !important; }
//
// z
// "

⬆ back to top

genAtomic() - Optional Options Object

It's a plain object which goes into second input argument of the main function, genAtomic(). Here are all the keys and their values:

Options Object's keyThe type of its valueDefaultDescription
{
includeConfigbooleantrueShould config be repeated, wraped with GENERATE-ATOMIC-CSS-CONFIG-STARTS and GENERATE-ATOMIC-CSS-CONFIG-ENDS? Enabling this enables includeHeadsAndTails as well (if not enabled already).
includeHeadsAndTailsbooleantrueShould the generated CSS be wrapped with GENERATE-ATOMIC-CSS-CONFIG-STARTS and GENERATE-ATOMIC-CSS-CONFIG-ENDS?
padbooleantrueShould the numbers be padded
configOverridenull (off) or stringnullThis is override, you can hard-set the config from outside. Handy when input contains old/wrong config.
reportProgressFuncfunction or nullnullHandy in worker setups, if you provide a function, it will be called for each percentage done from reportProgressFuncFrom to reportProgressFuncTo, then finally, with the result.
reportProgressFuncFromnatural number0reportProgressFunc() will ping unique percentage progress once per each percent, from 0 to 100 (%). You can skew the starting percentage so counting starts not from zero but from this.
reportProgressFuncTonatural number100reportProgressFunc() will ping unique percentage progress once per each percent, from 0 to 100 (%). You can skew the starting percentage so counting starts not from zero but from this.
}

Here it is, in one place, in case you want to copy-paste it somewhere:

{
  includeConfig: true,
  includeHeadsAndTails: true,
  pad: true,
  configOverride: null,
  reportProgressFunc: null,
  reportProgressFuncFrom: 0,
  reportProgressFuncTo: 100
};

⬆ back to top

genAtomic() - output API

The main function genAtomic() exports a plain object where result string is under key result:

For example, here's the format of the main function's output:

{
  log: {
    count: 1000
  },
  result: "<bunch of generated CSS>"
}

You tap the result like this:

import {
  genAtomic,
  version,
  headsAndTails,
  extractFromToSource,
} from "generate-atomic-css";
const source = `.mt$$ { margin-top: $$px; }|3`;
const { log, result } = genAtomic(source, {
  includeConfig: true,
});
console.log(`total generated classes and id's: ${log.count}`);
// => 4
console.log(`result:\n${result}`);
// => <bunch of generated CSS>

⬆ back to top

version

It's a string and it comes straight from package.json. For example:

import {
  genAtomic,
  version,
  headsAndTails,
  extractFromToSource,
} from "generate-atomic-css";
console.log(`version = v${version}`);
// => version = v1.0.1

⬆ back to top

headsAndTails

It's a plain object, its main purpose is to serve as a single source of truth for heads and tails names:

{
  CONFIGHEAD: "GENERATE-ATOMIC-CSS-CONFIG-STARTS",
  CONFIGTAIL: "GENERATE-ATOMIC-CSS-CONFIG-ENDS",
  CONTENTHEAD: "GENERATE-ATOMIC-CSS-CONTENT-STARTS",
  CONTENTTAIL: "GENERATE-ATOMIC-CSS-CONTENT-ENDS"
}

For example,

import {
  genAtomic,
  version,
  headsAndTails,
  extractFromToSource,
} from "generate-atomic-css";
console.log(`headsAndTails.CONTENTTAIL = ${headsAndTails.CONTENTTAIL}`);
// => headsAndTails.CONTENTTAIL = GENERATE-ATOMIC-CSS-CONTENT-ENDS

⬆ back to top

extractFromToSource()

It's an internal function which reads the source line, for example:

.pb$$ { padding-bottom: $$px !important; } | 5 | 10

and separates "from" (5 above) and "to" (10 above) values from the rest of the string (.pb$$ { padding-bottom: $$px !important; }).

The challenging part is that pipes can be wrapping the line from outside, plus, if there is only one number at the end of the line, it is "to" value.

| .mt$$ { margin-top: $$px !important; } | 1 |

Here's an example how to use extractFromToSource():

const {
  genAtomic,
  version,
  headsAndTails,
  extractFromToSource,
} = require("generate-atomic-css");
const input1 = `.pb$$ { padding-bottom: $$px !important; } | 5 | 10`;
const input2 = `.mt$$ { margin-top: $$px !important; } | 1`;

// second and third input argument are default "from" and default "to" values:
const [from1, to1, source1] = extractFromToSource(input1, 0, 500);
console.log(`from = ${from1}`);
// from = 5
console.log(`to = ${to1}`);
// from = 10
console.log(`source = "${source1}"`);
// source = ".pb$$ { padding-bottom: $$px !important; }"

const [from2, to2, source2] = extractFromToSource(input2, 0, 100);
console.log(`from = ${from2}`);
// from = 0 <--- default
console.log(`to = ${to2}`);
// from = 1 <--- comes from pipe, "} | 1`;"
console.log(`source = "${source2}"`);
// source = ".mt$$ { margin-top: $$px !important; }"

⬆ back to top

Idea

On a basic level, you can turn off heads/tails (set opts.includeHeadsAndTails to false) and config (set opts.includeConfig to false).

Each line which contains $$ will be repeated, from default 0 to 500 or within the range you set:

.pb$$ { padding-bottom: $$px !important; } | 5 | 10

Above instruction means generate from 5 to 10, inclusive:

.pb5 {
  padding-bottom: 5px !important;
}
.pb6 {
  padding-bottom: 6px !important;
}
.pb7 {
  padding-bottom: 7px !important;
}
.pb8 {
  padding-bottom: 8px !important;
}
.pb9 {
  padding-bottom: 9px !important;
}
.pb10 {
  padding-bottom: 10px !important;
}

If you're happy to start from zero, you can put only one argument, "to" value:

.w$$p { width: $$% !important; } | 100

Above instruction means generate from (default) 0 to (custom) 100, inclusive:

/* GENERATE-ATOMIC-CSS-CONTENT-STARTS */
.w0p {
  width: 0 !important;
}
.w1p {
  width: 1% !important;
}
.w2p {
  width: 2% !important;
}
.... .w98p {
  width: 98% !important;
}
.w99p {
  width: 99% !important;
}
.w100p {
  width: 100% !important;
}

⬆ back to top

Config

What happens if you want to edit the generated list, to change ranges, to add or remove rules?

You need to recreate the original "recipe", lines .pb$$ { padding-bottom: $$px !important; } and so on.

Here's where the config comes to help.

Observe:

/* GENERATE-ATOMIC-CSS-CONFIG-STARTS
.pb$$ { padding-bottom: $$px !important; } | 5 | 10

.mt$$ { margin-top: $$px !important; } | 1
GENERATE-ATOMIC-CSS-CONFIG-ENDS
GENERATE-ATOMIC-CSS-CONTENT-STARTS */
.pb5 {
  padding-bottom: 5px !important;
}
.pb6 {
  padding-bottom: 6px !important;
}
.pb7 {
  padding-bottom: 7px !important;
}
.pb8 {
  padding-bottom: 8px !important;
}
.pb9 {
  padding-bottom: 9px !important;
}
.pb10 {
  padding-bottom: 10px !important;
}

.mt0 {
  margin-top: 0 !important;
}
.mt1 {
  margin-top: 1px !important;
}
/* GENERATE-ATOMIC-CSS-CONTENT-ENDS */

If opts.includeConfig setting is on (it's on by default), your original config will be placed on top of generated content.

Furthermore, if generator detects content heads and tails placeholders, it will wipe existing contents there, replacing them with newly generated CSS.

The idea is you should be able to keep your config in your master email template, only remove config like regular CSS comment when deploying to production. But you'd still keep the master template with config. Later you could reuse it.

⬆ back to top

Contributing

  • If you see an error, raise an issue.
  • If you want a new feature but can't code it up yourself, also raise an issue. Let's discuss it.
  • If you tried to use this package, but something didn't work out, also raise an issue. We'll try to help.
  • If you want to contribute some code, fork the monorepo via GitLab, then write code, then file a pull request on GitLab. We'll merge it in and release.

In monorepo, npm libraries are located in packages/ folder. Inside, the source code is located either in src/ folder (normal npm library) or in the root, cli.js (if it's a command-line application).

The npm script "dev", the "dev": "rollup -c --dev" builds the development version retaining all console.logs with row numbers. It's handy to have js-row-num-cli installed globally so you can automatically update the row numbers on all console.logs.

⬆ back to top

Licence

MIT License

Copyright (c) 2015-2020 Roy Revelt and other contributors

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free