StyleQ Atomic CSS Runtime

Common errors

• TypeError: styleq is not a function

  cause Attempting to use `require()` for importing `styleq` in an environment that expects ESM imports, or trying to destructure a CommonJS module incorrectly.
  fix Use `import { styleq } from 'styleq';` instead of `const styleq = require('styleq');` for modern JavaScript modules.

• Property '$$css' is missing in type '{ ... }' but required in type 'CompiledStyle'.

  cause Passing an object to `styleq` that is intended to be a compiled style but lacks the mandatory `$$css` property.
  fix Ensure all compiled style objects explicitly include `$$css: true` (for production) or `$$css: 'debug-info'` (for development).

• The 'values' argument must be of type string. Received type object

  cause This error (or similar type mismatches) can occur if a compiled style object's value is not a class string but another type (e.g., a raw CSS property value like `{ color: 'red' }` instead of `{ color: 'text-red-500' }`).
  fix Verify that compiled style objects passed to `styleq` have values that are valid HTML class strings, as `styleq` is designed to concatenate these strings.

Warnings

• gotcha Compiled style objects *must* include the `$$css` property. For production, `$$css: true` is typical. For development, a string value like `$$css: 'path/to/file:line'` can be used for debugging. Objects without this property are treated as inline styles.
  Fix: Ensure all style objects generated by your CSS compiler include `$$css: true` or a descriptive string.
• gotcha Values within compiled style objects (those with `$$css`) must be HTML class strings, not raw CSS property values. `styleq` merges class strings, it does not process CSS properties directly for compiled styles.
  Fix: Your Atomic CSS compiler should output objects where keys map to class names (e.g., `{ display: 'display-flex-class' }`), not raw CSS properties (e.g., `{ display: 'flex' }`).
• gotcha Memoization is enabled by default. While generally beneficial for updates, disabling it via `styleq.factory({ disableCache: true })` might offer faster *initial* computations if your use case involves very few repeat merges.
  Fix: Consider profiling with and without `disableCache` if initial render performance is a critical bottleneck, especially in scenarios with infrequent component updates.
• gotcha Inline styles are merged with static styles by default. If you need to manage these merges independently for specific performance characteristics or compiler designs, use `styleq.factory({ disableMix: true })`.
  Fix: Evaluate if the default mixed merging strategy fits your performance and compiler design needs. If not, create a custom `styleq` instance with `disableMix: true`.

Install

• npm install styleq npm
• yarn add styleq yarn
• pnpm add styleq pnpm

Imports

• styleq
  wrong:

  const styleq = require('styleq');

  correct:

  import { styleq } from 'styleq';

  styleq is an ESM-first module. While some bundlers might handle CJS require, explicit ESM import is recommended.
• styleq.factory

  import { styleq } from 'styleq'; const customStyleq = styleq.factory({ disableCache: true });

  The `factory` method is accessed as a property of the named import `styleq`.
• Options (type)
  wrong:

  import { Options } from 'styleq';

  correct:

  import type { Options } from 'styleq';

  When importing types, use `import type` for clarity and to ensure they are stripped out in compilation.

Quickstart

Demonstrates basic usage of `styleq` to merge atomic CSS class names and inline styles, including dynamic and conditional styles, and shows how to use `styleq.factory` for custom configurations.

import { styleq } from 'styleq';

// Example compiled styles from an Atomic CSS compiler
const compiledStyles = {
  root: {
    $$css: true, // Required for production compiled styles
    display: 'display-flex-class',
    alignItems: 'alignItems-center-class',
    justifyContent: 'justifyContent-spaceBetween-class',
  },
  button: {
    $$css: 'button.ts:15', // String for dev debugging
    backgroundColor: 'bg-blue-500-class',
    padding: 'p-4-class',
    borderRadius: 'rounded-md-class',
  },
};

// Example inline styles (without $$css)
const dynamicStyles = {
  opacity: 0.8,
  color: 'red',
};

// Merge compiled and inline styles
const [className, inlineStyle] = styleq(
  compiledStyles.root,
  compiledStyles.button,
  dynamicStyles,
  // Conditional styles
  true && { cursor: 'pointer' },
  false && { display: 'none' }
);

console.log('Generated className:', className);
console.log('Generated inlineStyle:', inlineStyle);

// Using styleq.factory for custom configurations
const styleqNoCache = styleq.factory({ disableCache: true });
const [classNameNoCache, inlineStyleNoCache] = styleqNoCache(compiledStyles.root);

console.log('Generated className (no cache):', classNameNoCache);