CSS-in-JS Utilities

Common errors

• TypeError: [functionName] is not a function

  cause Attempting to use CommonJS `require()` syntax (e.g., `const { assignStyle } = require('css-in-js-utils')`) in an environment where the package's primary export is ESM, or if using a build setup that doesn't correctly transpile ESM imports.
  fix Ensure your project is configured for ESM and use `import { functionName } from 'css-in-js-utils'` syntax. If using CommonJS, verify your build configuration or check the `package.json` `exports` field for CJS compatibility.

• TS2305: Module '"css-in-js-utils"' has no exported member 'default'.

  cause Attempting to use a default import (e.g., `import StyleUtils from 'css-in-js-utils'`) when the library exclusively provides named exports.
  fix All utilities are named exports. Use named imports: `import { assignStyle, cssifyObject } from 'css-in-js-utils'`.

• TypeError: Cannot read properties of undefined (reading 'property') or 'value'

  cause Passing `undefined`, `null`, or an incorrect data type to a utility function that expects a string or object, such as `cssifyDeclaration(property, value)` where `property` or `value` is not a string/number as expected.
  fix Always ensure that the arguments passed to `css-in-js-utils` functions match the expected types (e.g., string property names, string or number values, plain objects for style maps). Refer to the specific function's documentation for its required input types.

Warnings

• gotcha This package is explicitly designed for CSS-in-JS *library authors* and not for direct use in application development. Using it directly in your application code might lead to unnecessary complexity or unexpected behavior, as its APIs are low-level and optimized for library integration.
  Fix: Consider using a full-fledged CSS-in-JS library like Emotion, Styled Components, or Fela for application development, which often internally utilize similar utilities.
• breaking While specific breaking changes for v3.0.0 are not extensively documented in public release notes for `robinweser/css-in-js-utils`, a major version increment from 1.x.x to 3.x.x typically indicates potentially incompatible API changes. Users upgrading from v1.x.x should thoroughly review their usage and test for regressions, especially concerning argument signatures, return types, or edge case handling in utility functions.
  Fix: Consult the official GitHub repository's commit history or issues for more granular details on changes between major versions if encountering unexpected behavior after upgrading.

Install

• npm install css-in-js-utils npm
• yarn add css-in-js-utils yarn
• pnpm add css-in-js-utils pnpm

Imports

• assignStyle
  wrong:

  const { assignStyle } = require('css-in-js-utils')

  correct:

  import { assignStyle } from 'css-in-js-utils'

  This library primarily uses named exports. While older versions or specific build setups might support CommonJS `require`, modern usage (especially with TypeScript) favors ESM named imports. The package ships with TypeScript types.
• cssifyObject
  wrong:

  import CssUtils from 'css-in-js-utils'; CssUtils.cssifyObject(...)

  correct:

  import { cssifyObject } from 'css-in-js-utils'

  All utilities are named exports; there is no default export for the entire module.
• camelCaseProperty
  wrong:

  import * as Utils from 'css-in-js-utils'; Utils.camelCaseProperty(...)

  correct:

  import { camelCaseProperty } from 'css-in-js-utils'

  While star imports (`import * as Utils from 'pkg'`) work, direct named imports are generally preferred for clarity and tree-shaking benefits.

Quickstart

This quickstart demonstrates how several `css-in-js-utils` functions can be combined to merge style objects, convert them to CSS strings, and inspect CSS property characteristics.

import { assignStyle, cssifyObject, hyphenateProperty, isUnitlessProperty } from 'css-in-js-utils';

// Define some base styles and overrides
const baseStyles = {
  backgroundColor: 'red',
  paddingTop: '10px',
  ':hover': {
    color: 'white',
    fontSize: '16px'
  }
};

const overrideStyles = {
  backgroundColor: 'blue',
  margin: '8px',
  ':hover': {
    fontSize: '18px',
    fontWeight: 'bold'
  }
};

console.log('--- Demonstrating css-in-js-utils ---');

// 1. Merge styles deeply using assignStyle
const mergedStyles = assignStyle(baseStyles, overrideStyles);
console.log('Merged Styles:', mergedStyles);
/*
Output:
Merged Styles: {
  backgroundColor: 'blue',
  paddingTop: '10px',
  margin: '8px',
  ':hover': {
    color: 'white',
    fontSize: '18px',
    fontWeight: 'bold'
  }
}
*/

// 2. Convert the top-level merged style object into a CSS string
// Note: cssifyObject only processes direct properties, not nested ones like ':hover'
const cssString = cssifyObject(mergedStyles);
console.log('CSS String (top-level):', cssString);
// Output: CSS String (top-level): background-color:blue;padding-top:10px;margin:8px

// 3. Demonstrate hyphenateProperty
const camelCaseProp = 'WebkitAppearance';
const hyphenatedProp = hyphenateProperty(camelCaseProp);
console.log(`Hyphenated property for "${camelCaseProp}":`, hyphenatedProp);
// Output: Hyphenated property for "WebkitAppearance": -webkit-appearance

// 4. Demonstrate isUnitlessProperty (e.g., for 'zIndex')
console.log('Is "zIndex" unitless?', isUnitlessProperty('zIndex')); // true
console.log('Is "width" unitless?', isUnitlessProperty('width'));   // false