API.md

API Reference

Overview

@adobe/css-tools provides a modern CSS parser and stringifier with comprehensive TypeScript support. It can parse CSS into an Abstract Syntax Tree (AST) and convert the AST back to CSS with various formatting options.

Installation

npm install @adobe/css-tools

Core Functions

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. When true, errors are collected in ast.stylesheet.parsingErrors
  • source (string) - File path for better error reporting

Returns

• CssStylesheetAST - The parsed CSS as an AST

Example

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

const css = `
  .example {
    color: red;
    font-size: 16px;
  }
`;

const ast = parse(css);
console.log(ast.stylesheet.rules);

stringify(ast, options?)

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

Parameters

• ast (CssStylesheetAST) - The CSS AST to stringify
• options (CompilerOptions, optional) - Stringification options
  • indent (string) - Indentation string (default: ' ')
  • compress (boolean) - Whether to compress/minify the output (default: false)

Returns

• string - The formatted CSS string

Example

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

const css = '.example { color: red; }';
const ast = parse(css);

// Pretty print
const formatted = stringify(ast, { indent: '  ' });
console.log(formatted);
// Output:
// .example {
//   color: red;
// }

// Compressed
const minified = stringify(ast, { compress: true });
console.log(minified);
// Output: .example{color:red}

Type Definitions

Core Types

CssStylesheetAST

The root AST node representing a complete CSS stylesheet.

type CssStylesheetAST = {
  type: CssTypes.stylesheet;
  stylesheet: {
    source?: string;
    rules: CssRuleAST[];
    parsingErrors?: CssParseError[];
  };
};

CssRuleAST

Represents a CSS rule (selector + declarations).

type CssRuleAST = {
  type: CssTypes.rule;
  selectors: string[];
  declarations: CssDeclarationAST[];
  position?: CssPosition;
  parent?: CssStylesheetAST;
};

CssDeclarationAST

Represents a CSS property declaration.

type CssDeclarationAST = {
  type: CssTypes.declaration;
  property: string;
  value: string;
  position?: CssPosition;
  parent?: CssRuleAST;
};

CssMediaAST

Represents a CSS @media rule.

type CssMediaAST = {
  type: CssTypes.media;
  media: string;
  rules: CssRuleAST[];
  position?: CssPosition;
  parent?: CssStylesheetAST;
};

CssKeyframesAST

Represents a CSS @keyframes rule.

type CssKeyframesAST = {
  type: CssTypes.keyframes;
  name: string;
  keyframes: CssKeyframeAST[];
  position?: CssPosition;
  parent?: CssStylesheetAST;
};

CssPosition

Represents source position information.

type CssPosition = {
  source?: string;
  start: {
    line: number;
    column: number;
  };
  end: {
    line: number;
    column: number;
  };
};

CssParseError

Represents a parsing error.

type CssParseError = {
  message: string;
  reason: string;
  filename?: string;
  line: number;
  column: number;
  source?: string;
};

Compiler Options

CompilerOptions

Options for the stringifier.

type CompilerOptions = {
  indent?: string;    // Default: '  '
  compress?: boolean; // Default: false
};

Error Handling

Silent Parsing

When parsing malformed CSS, you can use the silent option to collect errors instead of throwing:

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

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

const result = parse(malformedCss, { silent: true });

if (result.stylesheet.parsingErrors) {
  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

Enable source tracking for better error reporting:

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

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

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 }

Advanced Usage

Working with At-Rules

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

const css = `
  @media (max-width: 768px) {
    .container {
      padding: 10px;
    }
  }
  
  @keyframes fadeIn {
    from { opacity: 0; }
    to { opacity: 1; }
  }
`;

const ast = parse(css);

// Access media rules
const mediaRule = ast.stylesheet.rules.find(rule => rule.type === 'media');
console.log(mediaRule.media); // "(max-width: 768px)"

// Access keyframes
const keyframesRule = ast.stylesheet.rules.find(rule => rule.type === 'keyframes');
console.log(keyframesRule.name); // "fadeIn"

Custom Formatting

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

const css = '.example{color:red;font-size:16px}';
const ast = parse(css);

// Custom indentation
const formatted = stringify(ast, { indent: '    ' });
console.log(formatted);
// Output:
// .example {
//     color: red;
//     font-size: 16px;
// }

// Compressed with no spaces
const compressed = stringify(ast, { compress: true });
console.log(compressed);
// Output: .example{color:red;font-size:16px}

TypeScript Integration

The library provides comprehensive TypeScript support with full type definitions for all AST nodes and functions:

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

const css: string = '.example { color: red; }';
const ast: CssStylesheetAST = parse(css);
const output: string = stringify(ast);

Performance Considerations

• The parser is optimized for large CSS files
• AST nodes are lightweight and memory-efficient
• Stringification is fast and supports streaming for large outputs
• Consider using compress: true for production builds to reduce file size

Browser Support

The library works in all modern browsers and Node.js environments. For older environments, you may need to use a bundler with appropriate polyfills.