cnbuilder
    TypeScript icon, indicating that this package has built-in type declarations

    3.1.0 • Public • Published

    cnbuilder

    Yet another classname string builder (the fastest one)

    NPM Version NPM Downloads NPM Dependents Build Coverage Types Tree Shaking


    ❤️Please consider starring this project to show your love and support.🙌

    One more DOM classname string builder if you not enough yet 😁
    It is lightweight, fast and has no dependencies!
    Designed to be fastest full-feature drop-in replacement for classnames package.

    Install it via npm or yarn

    npm i cnbuilder
    # OR
    yarn add cnbuilder

    Use it wherever and however you want - node.js or webpack, CJS or ESM modules!

    INSTALLATION NOTE:
    This lib is written in ES6+ and delivering with both, transpiled and untranspiled versions:

    • main field of package.json is pointing to transpiled ES5 version with CJS modules resolution;
    • module field is pointing to transpiled ES5 version with ES modules resolution;
    • esnext field is pointing to the ES6+ version with ES modules resolution;

    Depending on your targets you may have to use Webpack and/or Babel to pull untranspiled version of package.
    See some tips on wiring thing up: https://2ality.com/2017/06/pkg-esnext.html

    Use it wherever and however you want - node.js or webpack, CJS or ESM modules!

    var cnb = require("cnbuilder").cnb;
    
    cnb("cnbuilder", { is: true }, ["awesome!"]); // => 'cnbuilder is awesome!'
    import { cnb } from "cnbuilder";
    
    cnb("works", { with: true }, ["ESM!"]); // => 'works with ESM!'

    Why

    cnbuilder is designed to be lighnweight and fast drop-in replacement of classnames package, so it wont be anyhow hard to migrate if you're already using classnames package. In general cnbuilder is 3-4 times faster than classnames and slightly lighter.

    Usage

    API is absolutely the same with classnames, except the moment that cnbuilder's methods are named exported.

    import { cnb, dcnb } from 'cnbuilder';
    
    cnb(); // common version
    dcnb(); // deduped version

    The cnbuilder takes any number of arguments which can be a string, array or object. Any other input will be ignored. The argument 'foo' is short for { foo: true } or ['foo']. If the value associated with a given key is falsy, that key won't be included in the output.

    cnb("foo", "bar"); // => 'foo bar'
    cnb("foo", { bar: true }); // => 'foo bar'
    cnb({ "foo-bar": true }); // => 'foo-bar'
    cnb({ "foo-bar": false }); // => ''
    cnb({ foo: true }, { bar: true }); // => 'foo bar'
    cnb({ foo: true, bar: true }); // => 'foo bar'
    
    // lots of arguments of various types
    cnb("foo", { bar: true, duck: false }, "baz", { quux: true }); // => 'foo bar baz quux'
    
    // other falsy values are just ignored
    cnb(null, false, "bar", undefined, 0, 1, { baz: null }, ""); // => 'bar 1'

    Arrays will be recursively flattened as per the rules above:

    var arr = ["b", { c: true, d: false }];
    cnb("a", arr); // => 'a b c'

    Output, as you see - pretty much the same too, but has some differences in direction of class names RFC.

    • cnbuilder does not generate useless spaces:
      classnames("test", [], { a: false }); // => "test " (5 chars with space at the end)
      cnb("test", [], { a: false }); // => "test" (just 4 chars)
    • cnbuilder skips numbers as they'te not the part of class names RFC. But it can't skip strings starting with digit and numeric object keys, cause it would impact the performance, so that part is left for the end developer
      classnames(321, "1stPlace"); // => "321 1stPlace"
      cnb(321, "1stPlace"); // => "1stPlace"

    Dynamic class names with ES2015

    If you're in an environment that supports computed keys (available in ES2015+ and Babel) you can use dynamic class names:

    let buttonType = "primary";
    cnb({ [`btn-${buttonType}`]: true });

    Dedupe version

    cnbuilder exports an alternative version which dedupes classes and ensures falsy classes specified in later arguments are excluded from the result string.

    This version is way slower so use it with caution.

    To use is simply import the dcnb method from cnbuilder package:

    import { dcnb } from 'cnbuilder';
    
    dcnb('foo foo foo', 'foo', 'foo foo');  // => 'foo'
    dcnb('foo', {foo: false, bar: true}, 'bar bar'); // => 'bar'

    Polyfills needed to support older browsers

    • Array.isArray: see MDN for details about unsupported older browsers (e.g. <= IE8) and a simple polyfill.
    • Object.create: used in dedupe version, see MDN for details about unsupported older browsers (e.g. <= IE8) and a simple polyfill.

    Performance (recent benchmarks results)

    Benchmarks results can be found in the benchmark directory.

    Related projects

    Install

    npm i cnbuilder

    DownloadsWeekly Downloads

    37,319

    Version

    3.1.0

    License

    MIT

    Unpacked Size

    25.9 kB

    Total Files

    22

    Last publish

    Collaborators

    • xobotyi