{"id":12098,"library":"styleq","title":"StyleQ Atomic CSS Runtime","description":"styleQ is a compact and efficient JavaScript runtime designed for merging HTML class names generated by Atomic CSS compilers. It provides high-performance merging capabilities for initial renders, incorporates built-in memoization to optimize updates, and seamlessly handles both static compiled styles and dynamic inline styles. The library is currently at version 0.2.1 and is actively maintained, though specific release cadence (e.g., weekly, monthly) is not explicitly stated but typically follows an as-needed pattern for utility libraries. Its key differentiators include its small gzipped size (0.7 KB), robust support for various CSS compiler designs, and its focus on performance for critical render paths. It contrasts with traditional CSS-in-JS solutions by operating on pre-compiled class names, acting as a final merging step.","status":"active","version":"0.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/necolas/styleq","tags":["javascript","typescript"],"install":[{"cmd":"npm install styleq","lang":"bash","label":"npm"},{"cmd":"yarn add styleq","lang":"bash","label":"yarn"},{"cmd":"pnpm add styleq","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"styleq is an ESM-first module. While some bundlers might handle CJS require, explicit ESM import is recommended.","wrong":"const styleq = require('styleq');","symbol":"styleq","correct":"import { styleq } from 'styleq';"},{"note":"The `factory` method is accessed as a property of the named import `styleq`.","symbol":"styleq.factory","correct":"import { styleq } from 'styleq'; const customStyleq = styleq.factory({ disableCache: true });"},{"note":"When importing types, use `import type` for clarity and to ensure they are stripped out in compilation.","wrong":"import { Options } from 'styleq';","symbol":"Options (type)","correct":"import type { Options } from 'styleq';"}],"quickstart":{"code":"import { styleq } from 'styleq';\n\n// Example compiled styles from an Atomic CSS compiler\nconst compiledStyles = {\n  root: {\n    $$css: true, // Required for production compiled styles\n    display: 'display-flex-class',\n    alignItems: 'alignItems-center-class',\n    justifyContent: 'justifyContent-spaceBetween-class',\n  },\n  button: {\n    $$css: 'button.ts:15', // String for dev debugging\n    backgroundColor: 'bg-blue-500-class',\n    padding: 'p-4-class',\n    borderRadius: 'rounded-md-class',\n  },\n};\n\n// Example inline styles (without $$css)\nconst dynamicStyles = {\n  opacity: 0.8,\n  color: 'red',\n};\n\n// Merge compiled and inline styles\nconst [className, inlineStyle] = styleq(\n  compiledStyles.root,\n  compiledStyles.button,\n  dynamicStyles,\n  // Conditional styles\n  true && { cursor: 'pointer' },\n  false && { display: 'none' }\n);\n\nconsole.log('Generated className:', className);\nconsole.log('Generated inlineStyle:', inlineStyle);\n\n// Using styleq.factory for custom configurations\nconst styleqNoCache = styleq.factory({ disableCache: true });\nconst [classNameNoCache, inlineStyleNoCache] = styleqNoCache(compiledStyles.root);\n\nconsole.log('Generated className (no cache):', classNameNoCache);","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure all style objects generated by your CSS compiler include `$$css: true` or a descriptive string.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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' }`).","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Consider profiling with and without `disableCache` if initial render performance is a critical bottleneck, especially in scenarios with infrequent component updates.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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`.","message":"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 })`.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use `import { styleq } from 'styleq';` instead of `const styleq = require('styleq');` for modern JavaScript modules.","cause":"Attempting to use `require()` for importing `styleq` in an environment that expects ESM imports, or trying to destructure a CommonJS module incorrectly.","error":"TypeError: styleq is not a function"},{"fix":"Ensure all compiled style objects explicitly include `$$css: true` (for production) or `$$css: 'debug-info'` (for development).","cause":"Passing an object to `styleq` that is intended to be a compiled style but lacks the mandatory `$$css` property.","error":"Property '$$css' is missing in type '{ ... }' but required in type 'CompiledStyle'."},{"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.","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' }`).","error":"The 'values' argument must be of type string. Received type object"}],"ecosystem":"npm"}