Sheetify CSS Bundler

8.0.0 · active · verified Tue Apr 21

Sheetify is a modular CSS bundler designed primarily for use with Browserify. It allows developers to import and namespace CSS directly within JavaScript files, treating CSS as a first-class module similar to how JavaScript modules are handled via npm. The current stable version is 8.0.0. While not following a strict frequent release cadence, it receives updates for dependency maintenance and feature enhancements. Key differentiators include its ability to automatically namespace CSS classes based on content hashes, eliminating the need for complex BEM-like naming schemes, and its extensibility through transforms. It enables importing CSS packages from npm, inlining CSS directly into views for transparency, and offers a minimal API surface. It specifically targets client-side bundling workflows where Browserify is the primary tool for module resolution and bundling.

Common errors

```
Error: Cannot find module 'sheetify' from '<path>'
```
cause The `sheetify` package is not installed in the project's `node_modules`, or the Browserify command is incorrectly configured and cannot resolve it.

fix Ensure `sheetify` is installed: `npm install sheetify --save-dev`. Verify your `browserify` command includes `-t sheetify` and that `index.js` correctly `require`s `sheetify`.
```
SyntaxError: Unexpected token import (or similar for ESM syntax)
```
cause Attempting to use ES module `import` syntax (`import css from 'sheetify'`) in a CommonJS context or without proper transpilation/bundler configuration for ES Modules.

fix Sheetify is a CommonJS module. Use `const css = require('sheetify')` instead of `import`. If targeting modern Node.js or browser ESM, ensure your build setup correctly transforms CommonJS `require` to ES `import` for dependencies.

Warnings

breaking Sheetify v8.0.0 and higher require Node.js version 6 or greater. Projects running on older Node.js versions will encounter compatibility issues.
Fix: Upgrade your Node.js environment to version 6 or higher. Consider using a Node.js version manager like `nvm` to manage multiple Node.js installations.
gotcha When importing CSS from external files or npm packages (e.g., `css('./my-file.css')` or `css('normalize.css')`), `sheetify` does NOT apply namespacing by default. Namespacing is primarily for CSS defined directly within tagged template literals.
Fix: For external CSS that needs namespacing, consider wrapping its content within a tagged template literal or using a custom transform that applies namespacing logic.
gotcha Sheetify does not support dynamic CSS variables or values directly within its tagged template literals. The CSS it processes is static.
Fix: For dynamic styling, you must use inline styles on the HTML elements or manipulate CSS properties directly via JavaScript after the initial render.

Install

npm install sheetify npm
yarn add sheetify yarn
pnpm add sheetify pnpm

Imports

css (inline/external)
wrong:
```
import css from 'sheetify'
```
correct:
```
const css = require('sheetify')
```
The primary API for defining modular CSS in JavaScript files, which takes a tagged template literal or a path to an external CSS file/npm package. Sheetify is a CommonJS module, so `require` is the standard import mechanism. Direct ESM `import` is not natively supported without a transpilation step.
SheetifyTransform (CLI)
wrong:
```
import sheetify from 'browserify-sheetify-transform'
```
correct:
```
browserify -t sheetify index.js > bundle.js
```
While `sheetify` provides a programmatic API, its most common 'import pattern' is as a Browserify transform. It's applied via the command line using the `-t` flag, integrating it directly into the Browserify bundling process. There is no separate module to `require` for the transform itself.
css (npm package)
wrong:
```
import 'normalize.css'
```
correct:
```
const css = require('sheetify'); css('normalize.css')
```
When consuming CSS from npm packages via Sheetify, the `css` function is used. Note that by default, CSS from npm packages is NOT namespaced by Sheetify, only local or inline CSS. The import mechanism for the `css` function itself remains `require`.

Quickstart

This example demonstrates how to use `sheetify` with Browserify to namespace inline CSS defined using tagged template literals and append the resulting HTML to the document body, including setup instructions.

const css = require('sheetify');
const html = require('nanohtml'); // Example: nanohtml is a common pairing for DOM manipulation

// Define inline CSS using sheetify's tagged template literal
const prefix = css`
  :host {
    background-color: #f0f0f0;
    padding: 20px;
    border-radius: 8px;
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
  }
  :host > h1 {
    text-align: center;
    color: #333;
    font-family: sans-serif;
  }
  :host > p {
    color: #666;
    text-align: justify;
  }
`;

// Create HTML using nanohtml, applying the namespaced CSS class
const tree = html`
  <section class=${prefix}>
    <h1>My Modular Section</h1>
    <p>This paragraph demonstrates how Sheetify namespaces CSS rules to prevent global style conflicts. The styles defined above are scoped to this section element.</p>
  </section>
`;

// Append the generated HTML to the document body
document.body.appendChild(tree);

// To run this example:
// 1. Install dependencies: npm install sheetify nanohtml browserify
// 2. Save the code above as `index.js`.
// 3. Run the Browserify command: browserify -t sheetify index.js -o bundle.js
// 4. Create an `index.html` file with: <script src="bundle.js"></script> and open in browser.

view raw JSON →