@adobe/css-tools

A modern CSS parser and stringifier with TypeScript support

Parse CSS into an Abstract Syntax Tree (AST) and convert it back to CSS with configurable formatting. Built with TypeScript for type safety and modern JavaScript features.

Install

npm install @adobe/css-tools

Usage

import { parse, stringify } from '@adobe/css-tools'

// Parse CSS to AST
const ast = parse('body { font-size: 12px; }')

// Stringify AST back to CSS
const css = stringify(ast)
// => "body { font-size: 12px; }"

// Pretty print with custom indentation
const formatted = stringify(ast, { indent: '  ' })
// => "body {\n  font-size: 12px;\n}"

// Minify output
const minified = stringify(ast, { compress: true })
// => "body{font-size:12px}"

// Identity mode: round-trip CSS exactly as written
const original = 'body  { font-size:  12px;  }'
const ast2 = parse(original, { preserveFormatting: true })
stringify(ast2, { identity: true }) === original // true

// Remove empty rules
const ast3 = parse('.empty {} .keep { color: red; }')
stringify(ast3, { removeEmptyRules: true })
// => ".keep {\n  color: red;\n}"

API

parse(code, options?)

Parses CSS code and returns an Abstract Syntax Tree (AST).

Parameters:

• code (string) - The CSS code to parse
• options (object, optional) - Parsing options
  • silent (boolean) - Silently fail on parse errors instead of throwing
  • source (string) - File path for better error reporting
  • preserveFormatting (boolean) - Insert whitespace AST nodes and store raw formatting properties for identity round-trip (default: false)

Returns: CssStylesheetAST - The parsed CSS as an AST

stringify(ast, options?)

Converts a CSS AST back to CSS string with configurable formatting.

Parameters:

• ast (CssStylesheetAST) - The CSS AST to stringify
• options (object, optional) - Stringification options
  • indent (string) - Indentation string (default: ' ')
  • compress (boolean) - Whether to compress/minify the output (default: false)
  • identity (boolean) - Reproduce the original CSS exactly as parsed; requires preserveFormatting during parsing (default: false)
  • removeEmptyRules (boolean) - Remove rules with empty declaration blocks (default: false)

Returns: string - The formatted CSS string

Features

• Complete CSS Support: All standard CSS features including selectors, properties, values, at-rules, and comments
• TypeScript Support: Full type definitions for all AST nodes and functions
• Error Handling: Configurable error handling with detailed position information
• Formatting Options: Pretty print, minify, identity (round-trip), or custom formatting
• Identity Round-Trip: Parse and stringify CSS back to the exact original formatting
• Empty Rule Removal: Optionally strip rules with empty declaration blocks
• Performance Optimized: Efficient parsing and stringification for large CSS files
• Source Maps: Track original source positions for debugging and tooling

Supported CSS Features

• Selectors: Element, class, ID, attribute, pseudo-class, pseudo-element selectors
• Properties: All standard CSS properties and custom properties
• Values: Colors, lengths, percentages, functions, calc(), etc.
• At-rules: @media, @keyframes, @import, @charset, @namespace, @font-face, @page, @document, @supports, @container, @layer, @starting-style, @host, @custom-media
• Comments: Both /* */ and // comments
• Whitespace: Preserves formatting information
• Vendor prefixes: Supports vendor-prefixed at-rules and properties
• Nested rules: Media queries, supports, containers, etc.
• Complex selectors: Combinators, pseudo-selectors, attribute selectors

Examples

Error Handling

import { parse } from '@adobe/css-tools'

const malformedCss = `
  body { color: red; }
  { color: blue; } /* Missing selector */
  .valid { background: green; }
`

// Parse with silent error handling
const result = parse(malformedCss, { silent: true })

// Check for parsing errors
if (result.stylesheet.parsingErrors) {
  console.log('Parsing errors:', result.stylesheet.parsingErrors.length)
  result.stylesheet.parsingErrors.forEach(error => {
    console.log(`Error at line ${error.line}: ${error.message}`)
  })
}

// Valid rules are still parsed
console.log('Valid rules:', result.stylesheet.rules.length)

Source Tracking

import { parse } from '@adobe/css-tools'

const css = 'body { color: red; }'
const ast = parse(css, { source: 'styles.css' })

// Position information is available
const rule = ast.stylesheet.rules[0]
console.log(rule.position?.source) // "styles.css"
console.log(rule.position?.start) // { line: 1, column: 1 }
console.log(rule.position?.end) // { line: 1, column: 20 }

For more examples, see the Examples documentation.

Performance

The library is optimized for performance and can handle large CSS files efficiently. For benchmarking information, see the benchmark/ directory in the source code.

Documentation

• API Reference - Complete API documentation
• AST Structure - Detailed AST node types and structure
• Examples - Comprehensive usage examples
• Changelog - Version history and changes

Background

This is a fork of the npm css package, maintained by Adobe with modern improvements including TypeScript support, enhanced performance, and security updates. It provides a robust foundation for CSS tooling, preprocessing, and analysis.

License

MIT