Skip to content

API.md

Latest commit

 

History

History
362 lines (270 loc) · 8.75 KB

API.md

File metadata and controls

362 lines (270 loc) · 8.75 KB

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
    • preserveFormatting (boolean) - Insert whitespace AST nodes and store raw formatting properties on nodes for identity round-trip. When true, whitespace between siblings is preserved as CssWhitespaceAST nodes, and raw formatting properties (rawPrelude, rawBetween, rawValue, rawSource) are stored on relevant nodes. Default: false

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)
    • identity (boolean) - Reproduce the original CSS exactly as parsed. Requires preserveFormatting: true during parsing. Walks the AST including whitespace nodes and uses raw formatting properties to reconstruct the original output. Inserted or modified nodes without raw properties are emitted in beautified format. Falls back to beautified output when preserveFormatting was not used. Default: false
    • removeEmptyRules (boolean) - Remove rules with empty declaration blocks from the output. Works in all modes (beautified, compressed, identity). 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: Array<CssAtRuleAST | CssWhitespaceAST>;
    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
  identity?: boolean;       // Default: false
  removeEmptyRules?: 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}

Identity Round-Trip

Reproduce the original CSS exactly as it was written, preserving all whitespace, comments, and formatting:

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

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

// Parse with preserveFormatting to store original source
const ast = parse(css, { preserveFormatting: true });

// Stringify with identity mode to reproduce the original CSS
const output = stringify(ast, { identity: true });
console.log(output === css); // true

When preserveFormatting was not used during parsing, identity mode falls back to beautified output.

Removing Empty Rules

Strip rules with empty declaration blocks from the output:

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

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

// Beautified without empty rules
const output = stringify(ast, { removeEmptyRules: true });
console.log(output);
// Output:
// .keep {
//   color: red;
// }

// Also works with compressed mode
const compressed = stringify(ast, { compress: true, removeEmptyRules: true });
console.log(compressed);
// Output: .keep{color:red;}

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.