csx

library1.0.0jsnpmunverified

CSX (CSS eXpressions) is a utility library designed to simplify the creation of strongly typed CSS values and functions within TypeScript environments, primarily serving as a companion to the TypeStyle library. It offers a comprehensive set of helpers for common CSS properties and units, such as `color`, `rgb`, `hsl`, `px`, `em`, `percent`, as well as shorthand properties like `margin` and `padding`. The current stable version, 10.0.2, reflects ongoing development with a recent focus on aligning its output more closely with the CSS Object Model (CSSOM) for improved consistency and testability across different browsers and testing setups. This includes changes to color function spacing and the addition of optional alpha parameters for `rgb()` and `hsl()`. CSX maintains an active release cadence, delivering continuous enhancements and bug fixes. Its core differentiator lies in providing a robust, type-safe API for dynamic CSS value generation, significantly reducing runtime errors and improving code maintainability compared to raw string concatenation or less-typed approaches.

serialization

npm install csx

github ↗package ↗

INSTALL

IMPORT

SIG · CSX

csx

serializationjavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

color

✓ import { color } from 'csx'

✗ const color = require('csx').color;

CSX is primarily designed for TypeScript and ES module environments. CommonJS `require()` is not officially supported and may lead to issues with type inference or bundling in modern projects.

rgb

✓ import { rgb } from 'csx'

✗ import rgb from 'csx/lib/rgb'

Named exports are the standard for all utility functions. Direct imports from subpaths are discouraged and may break with future updates.

✓ import { px } from 'csx'

✗ import { px } from 'csx/dist/units'

All core utilities should be imported directly from the top-level 'csx' package. Importing from internal paths ('dist', 'lib') is unstable and not recommended.

margin

✓ import { margin } from 'csx'

✗ import * as csx from 'csx'; const m = csx.margin;

While `import * as csx` works, it's generally better practice to destructure specific utilities for tree-shaking and clarity, especially with many functions available.

Demonstrates defining various CSS values and shorthands using CSX helpers like colors, units, margins, and then integrating them into a TypeStyle stylesheet.

import { color, rgb, hsl, px, em, rem, percent, viewHeight, viewWidth, margin, padding, url, quote } from 'csx'; import { style } from 'typestyle'; // Assuming TypeStyle is used as recommended // Define some CSS values using CSX helpers const brandColor = color('#1E90FF'); // Dodger Blue const semiTransparent = rgb(30, 144, 255, 0.7); // RGB with alpha const lightAccent = hsl(200, 80, 95); // HSL color // Unit helpers const defaultPadding = px(16); const headingFontSize = em(2.5); const bodyFontSize = rem(1.1); const viewportWidth = viewWidth(100); const elementHeight = viewHeight(50); const responsiveWidth = percent(75); // Shorthand properties const cardMargin = margin(px(20), 'auto'); // Top/Bottom 20px, Left/Right auto const elementPadding = padding(defaultPadding, px(10)); // Top/Bottom 16px, Left/Right 10px // URL and quoting helpers const backgroundImage = url('/assets/background.jpg'); const fontFaceName = quote('My Custom Font'); // Example of integrating with TypeStyle const myStyledElement = style({ color: brandColor.toString(), backgroundColor: semiTransparent.toString(), border: `${px(1)} solid ${lightAccent.toString()}`, padding: elementPadding.toString(), margin: cardMargin.toString(), width: responsiveWidth.toString(), height: elementHeight.toString(), fontSize: bodyFontSize.toString(), fontFamily: fontFaceName.toString(), backgroundImage: backgroundImage.toString(), $nest: { '& > h1': { fontSize: headingFontSize.toString(), textAlign: 'center', }, '@media (max-width: 768px)': { width: viewportWidth.toString(), margin: margin(px(10)), }, }, }); console.log('CSX Brand Color:', brandColor.toString()); console.log('CSX Element Padding:', elementPadding.toString()); console.log('CSX Card Margin:', cardMargin.toString()); console.log('CSX Background Image:', backgroundImage.toString()); console.log('CSX Font Face Name:', fontFaceName.toString()); console.log('Generated TypeStyle class name:', myStyledElement);

Debug

Known issues

breakingCSS color functions (e.g., `rgb()`, `hsl()`) now include spaces after commas in their output to match the CSS Object Model (CSSOM). This changes the exact string output of color functions.

fix

Update any snapshot tests or assertions that directly compare the string output of CSX color functions. No code change is typically required for runtime behavior unless specific string comparisons are in place.

affects: >=10.0.0

breakingThe behavior of `background-size` helper was fixed in `v9.0.2` to correctly use `/` between position and size. Code relying on the incorrect pre-`v9.0.2` output will produce different CSS.

fix

Verify `background-size` usage. If you were implicitly relying on incorrect output, ensure your code now explicitly passes position and size, e.g., `backgroundSize('center', '50%')` to get `'center / 50%'`.

affects: >=9.0.2

gotchaIn `v9.0.2`, a more specific type definition was added for `background-size` that throws a type error if `size` is provided but `position` is undefined. This improves type safety but can break existing code that was implicitly passing `undefined` for position.

fix

Ensure that when providing a `size` argument to `backgroundSize()`, a valid `position` argument (even if 'initial' or '0 0') is also provided to satisfy the type definition.

affects: >=9.0.2

breakingStarting with `v5.0.0`, all styles generated by CSX are vendor prefixed by default and are explicitly meant to be used in conjunction with TypeStyle. Using CSX independently of TypeStyle or in other styling solutions may lead to unexpected behavior or incomplete CSS output.

fix

Ensure that CSX is used alongside TypeStyle, as it's designed to complement its functionality. If you need vendor prefixing control, manage it via TypeStyle's configuration.

affects: >=5.0.0

Errors

Common errors & fixes

Expected `rgb(0, 0, 0)` but got `rgb(0,0,0)` in CSS output.

Difference in color function string output due to new spacing introduced in v10.0.0 to align with CSSOM.

fix

This is an intended breaking change in output formatting. Adjust any tests or code that performs exact string comparisons on color function outputs to reflect the new spaced format. No functional code change is needed.

Type error: Argument of type 'string' is not assignable to parameter of type 'CssLength'.

Attempting to pass a raw string where a `csx` unit helper (like `px()`, `em()`) is expected, or providing an invalid value type to a CSX function.

fix

Always use the appropriate CSX helper functions for units and values, e.g., `px(10)` instead of `'10px'`, or `percent(50)` instead of `'50%'`. Ensure types match the function signatures.

ReferenceError: require is not defined

Attempting to import `csx` using CommonJS `require()` syntax in an environment (e.g., a modern TypeScript project, browser ES module context, or Node.js with type:"module") that expects ES module syntax.

fix

Update your import statements to use ES module syntax: `import { color } from 'csx';`. Ensure your project's `tsconfig.json` (if applicable) and build setup are configured for ES modules (e.g., `"module": "esnext"` or `"nodenext"`).

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/typestyle/csx ↗

packagehttps://www.npmjs.com/package/csx ↗