Muro CSS (.mss preprocessor)

26.0.2 verified Sat Apr 25 auth: no javascript

A TypeScript CSS preprocessor and bundler for .mss files. Current stable version is 26.0.2. Actively maintained with regular releases. Compiles a single entry file or an entire directory of .mss sources into one CSS output. Supports variables, nesting, mixins, imports (including built-in modules like muro:reset), conditionals, loops, theme baking (light/dark), semantic layering, guard locks, and automatic raster asset rewriting to webp. Includes CLI with watch, minify, purge, sourcemap, and asset-dir options. Ships TypeScript types. Differentiators: designed as a TypeScript-first alternative to Sass/PostCSS with built-in utilities and zero-config polyfilling.

Common errors

error Error: Cannot find module 'muro-css' ↓

cause Package not installed in node_modules.

fix

Run 'npm i muro-css' or 'npm i -D muro-css' to install.

error TypeError: compile is not a function ↓

cause Incorrect import path or using default import when import { compile } is required.

fix

Use import { compile } from 'muro-css'.

error SyntaxError: Unexpected token '#' ↓

cause A # comment is placed after non-whitespace on a line, or hex color/scss syntax is mistakenly treated.

fix

Ensure # comments start at line beginning; use // for inline comments.

Warnings

breaking Since v26, legacy .x2s files and imports (x2s:*, @x2s/*) are deprecated and will be removed in the next major version. ↓

fix Rename .x2s files to .mss and replace x2s:*/@x2s/* imports with muro:* equivalents.

breaking Node.js >=18 required in v26. Older Node versions will fail. ↓

fix Upgrade Node.js to version 18 or later.

deprecated The x2s CLI alias and x2s: built-in imports are deprecated in v26 and will be removed next release. ↓

fix Use muro CLI and muro: built-in imports instead.

gotcha When using @import in .mss files, paths beginning with 'muro:' refer to built-in modules. Other relative paths must include the file extension. ↓

fix Use @import 'muro:reset' for built-in, or @import './partial.mss' for files.

gotcha The # character at line start is treated as a comment only if it's the first non-whitespace character. Hex colors and ID selectors like #hero work normally. ↓

fix Avoid putting space before # for comments; use // or ** for safer comment syntax.

gotcha Automatic raster asset rewriting to .webp requires an external converter to be installed on the system. Without it, assets are left as-is. ↓

fix Ensure a .webp converter (e.g., cwebp) is available in PATH, or use --no-assets to skip rewriting.

Install

npm install muro-css

yarn add muro-css

pnpm add muro-css

Imports

default
wrong
```
const muro = require('muro-css')
```
correct
```
import muro from 'muro-css'
```
ESM-only; package.json type is module. Ships types.

compile

wrong

import compile from 'muro-css/compile'

correct

import { compile } from 'muro-css'

Named export for programmatic use. Available since v26.

MuroOptions

wrong

import { MuroOptions } from 'muro-css'

correct

import type { MuroOptions } from 'muro-css'

Type-only import; MuroOptions is an interface, not a value.

Quickstart

Compiles an .mss file to CSS using CLI and programmatic API with TypeScript types.

// app.mss
$primary: #224466;

.button {
  color: $primary;
  &:hover {
    color: darken($primary, 10%);
  }
}

// Install: npm i -D muro-css
// Run: muro app.mss app.css

// Programmatic usage in Node.js >=18
import { compile } from 'muro-css';

const result = compile({
  input: 'styles.mss',
  output: 'styles.css',
  sourcemap: true,
});

console.log('CSS compiled:', result.css);