Xerxisfy Elite Style Sheet (X2S)

26.0.1 · active · verified Tue Apr 21

Xerxisfy Elite Style Sheet (X2S) is a TypeScript-based CSS preprocessor and bundler designed for its custom `.x2s` stylesheet syntax. Currently at version 26.0.1, it actively develops and provides a robust CLI for compiling single `.x2s` files or entire directories into a single optimized CSS bundle. While no explicit release cadence is documented, the high major version suggests frequent and potentially significant updates. Key differentiators include unique features like `@context` for scoped global variables, `light(...) dark(...)` for theme baking, semantic layering via `layer:`, Xerx Guard locks (`@lock`) to prevent property overrides, and advanced container unit math (e.g., `cw`, `ch`). It also offers zero-config polyfilling for modern CSS features and automatic raster asset rewriting to WebP formats, making it a comprehensive tool for modern CSS development that extends beyond standard preprocessor capabilities like nesting, mixins, and control flow.

Common errors

```
Error: No WebP converter found. Skipping image conversion.
```
cause Xerxisfy Elite Style Sheet could not locate a system-wide executable for converting images to WebP (e.g., `cwebp` or `convert` from ImageMagick).

fix Install a WebP converter like `cwebp` or `ImageMagick` and ensure it's accessible in your system's PATH. On Debian/Ubuntu: `sudo apt-get install webp` (for cwebp) or `sudo apt-get install imagemagick`.
```
x2s: Expected a selector or variable, but got '#'
```
cause You are using `#` as a comment character within a line, or not as the first character on a line, causing X2S to parse it as part of CSS syntax.

fix Use `//` for single-line comments or `** your comment **` for block comments. `#` is only for comments at the absolute beginning of a line.
```
ReferenceError: $myVariable is not defined.
```
cause A variable has been used before it was declared, or it is outside its declared scope (e.g., trying to access a locally scoped variable globally without `@context`).

fix Ensure all variables are declared with `$` before use. For global variables within specific sections, use the `@context` directive to properly scope them, or declare them at the top level of your `.x2s` file.

Warnings

breaking Xerxisfy Elite Style Sheet is at a high major version (26.x), indicating active development and a history of frequent breaking changes between major versions. Always review release notes carefully when upgrading.
Fix: Consult the official GitHub repository for specific migration guides or changelogs for the versions you are upgrading between.
gotcha The automatic conversion of raster assets (PNG, JPG) to WebP requires an external converter (like `cwebp` from libwebp or ImageMagick) to be available in the system's PATH. X2S does not bundle these tools.
Fix: Install `cwebp` or ImageMagick on your system. For example, on macOS: `brew install webp` or `brew install imagemagick`.
gotcha The `#` character is only interpreted as a single-line comment if it is the very first non-whitespace character on a line. Using `#` mid-line or after other characters will interpret it as a CSS ID selector or part of a hex color value.
Fix: For mid-line or general single-line comments, use `//`. For multi-line comments, use `** ... **`.
gotcha The primary and most stable interface for X2S is its Command Line Interface (CLI). While it ships TypeScript types, programmatic APIs may be less documented or subject to more frequent internal changes than the CLI options.
Fix: Prioritize using the `x2s` CLI command for compilation tasks. If programmatic integration is necessary, thoroughly test and pin specific versions to avoid unexpected behavior.

Install

npm install xerxisfy-elite-style-sheet npm
yarn add xerxisfy-elite-style-sheet yarn
pnpm add xerxisfy-elite-style-sheet pnpm

Imports

compile
```
import { compile } from 'xerxisfy-elite-style-sheet';
```
While X2S is primarily a CLI tool, a 'compile' function is typically exposed for programmatic integration in TypeScript preprocessors that ship types. Use the CLI for standard projects.
X2SOptions
```
import type { X2SOptions } from 'xerxisfy-elite-style-sheet';
```
The type definition for configuration options when using the programmatic API. Actual interface name may vary if not explicitly 'X2SOptions'.
runCLI
```
import { runCLI } from 'xerxisfy-elite-style-sheet/dist/cli';
```
For advanced use cases like embedding the X2S CLI runner within another Node.js application. Path might vary based on internal module structure.

Quickstart

Demonstrates installing X2S, creating a sample .x2s file, and compiling it to a minified CSS bundle with source maps in watch mode using the CLI.

mkdir my-x2s-project
cd my-x2s-project

echo '$brand: #007bff;\n@mixin button($padding: 10px 15px) { padding: $padding; border: none; border-radius: 4px; }\n.container { max-width: 960px; margin: 0 auto; }\n.btn { @include button; background-color: $brand; color: white; &:hover { background-color: darken($brand, 10%); } }\n@for $i from 1 through 5 { .col-#{$i} { width: math(100% / 5); } }' > styles/app.x2s

mkdir public

npm install xerxisfy-elite-style-sheet

npx x2s styles/app.x2s public/bundle.css --sourcemap --minify --watch

# Expected output in public/bundle.css and public/bundle.css.map after compilation
# (Press Ctrl+C to stop the watch process)

view raw JSON →