0
# Stylis
1

2
Stylis is a lightweight CSS preprocessor that provides essential CSS preprocessing capabilities including CSS nesting, selector namespacing, automatic vendor prefixing, CSS minification, and ES module compatibility. The library operates on an Abstract Syntax Tree (AST) structure offering a compile-serialize-stringify workflow for parsing CSS strings, manipulating them through middleware functions, and outputting processed CSS.
3

4
## Package Information
5

6
- **Package Name**: stylis
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES Module)
9
- **Installation**: `npm install stylis`
10

11
## Core Imports
12

13
```javascript
14
import { compile, serialize, stringify } from 'stylis';
15
```
16

17
For individual module imports:
18

19
```javascript
20
import { compile, parse } from 'stylis';              // Parser functions
21
import { serialize, stringify } from 'stylis';        // Serializer functions  
22
import { middleware, prefixer, namespace } from 'stylis'; // Middleware system
23
import { tokenize } from 'stylis';                     // Tokenization utilities
24
```
25

26
## Basic Usage
27

28
```javascript
29
import { compile, serialize, stringify } from 'stylis';
30

31
// Basic CSS processing
32
const css = 'h1 { color: red; &:hover { color: blue; } }';
33
const processed = serialize(compile(css), stringify);
34
console.log(processed); // "h1{color:red;}h1:hover{color:blue;}"
35

36
// With vendor prefixing
37
import { middleware, prefixer } from 'stylis';
38
const prefixed = serialize(
39
  compile('div { display: flex; }'), 
40
  middleware([prefixer, stringify])
41
);
42
console.log(prefixed); // Includes -webkit-box, -ms-flexbox, etc.
43
```
44

45
## Architecture
46

47
Stylis is built around several key components:
48

49
- **Parser**: Transforms CSS strings into Abstract Syntax Trees (AST) with support for nesting, at-rules, and comments
50
- **AST Structure**: Unified node structure with `value`, `type`, `props`, `children`, and metadata properties
51
- **Middleware System**: Pluggable transformation pipeline allowing custom CSS processing and built-in utilities
52
- **Serializer**: Converts AST back to CSS strings with customizable output formatting
53
- **Tokenizer**: Low-level parsing utilities for character-by-character CSS analysis
54
- **Utilities**: Helper functions for string manipulation, array operations, and CSS processing
55

56
## Capabilities
57

58
### CSS Parsing and Compilation
59

60
Transform CSS strings into Abstract Syntax Trees with support for nesting, at-rules, comments, and declarations.
61

62
```javascript { .api }
63
function compile(value: string): object[];
64
function parse(
65
  value: string, 
66
  root: object, 
67
  parent: object, 
68
  rule: string[], 
69
  rules: string[], 
70
  rulesets: string[], 
71
  pseudo: number[], 
72
  points: number[], 
73
  declarations: string[]
74
): object;
75
```
76

77
[Parser and Compilation](./parser.md)
78

79
### CSS Serialization and Output
80

81
Convert AST nodes back into CSS strings with customizable formatting and processing.
82

83
```javascript { .api }
84
function serialize(children: object[], callback: function): string;
85
function stringify(element: object, index: number, children: object[], callback: function): string;
86
```
87

88
[Serialization and Stringification](./serialization.md)
89

90
### Middleware System
91

92
Pluggable transformation pipeline with built-in middleware for vendor prefixing, namespacing, and custom processing.
93

94
```javascript { .api }
95
function middleware(collection: function[]): function;
96
function prefixer(element: object, index: number, children: object[], callback: function): void;
97
function namespace(element: object): void;
98
```
99

100
[Middleware System](./middleware.md)
101

102
### Tokenization and Low-level Parsing
103

104
Character-by-character parsing utilities for custom CSS processing and analysis.
105

106
```javascript { .api }
107
function tokenize(value: string): string[];
108
function alloc(value: string): any[];
109
function dealloc(value: any): any;
110
```
111

112
[Tokenization](./tokenization.md)
113

114
### Utility Functions and Constants
115

116
Helper functions for string manipulation, array operations, and CSS processing constants.
117

118
```javascript { .api }
119
// Constants
120
const COMMENT: string; // 'comm'
121
const RULESET: string; // 'rule' 
122
const DECLARATION: string; // 'decl'
123

124
// Utility functions
125
function hash(value: string, length: number): number;
126
function trim(value: string): string;
127
function replace(value: string, pattern: string|RegExp, replacement: string): string;
128
```
129

130
[Utilities](./utilities.md)
131

132
## AST Node Structure
133

134
All AST nodes in Stylis follow a consistent structure:
135

136
```javascript { .api }
137
interface StylisNode {
138
  value: string;           // Original CSS text
139
  type: string;            // Node type ('rule', 'decl', 'comm', or at-rule name)
140
  props: string | string[]; // Parsed properties (selectors for rules, property name for declarations)
141
  children: object[] | string; // Child nodes or property value
142
  line: number;            // Source line number
143
  column: number;          // Source column number
144
  length: number;          // Character length
145
  return: string;          // Generated output (used by serializers)
146
  root: object;            // Parent node in compiled output
147
  parent: object;          // Parent node in input structure
148
  siblings: object[];      // Sibling nodes
149
}
150
```
151

152
## Error Handling
153

154
Stylis is designed to be fault-tolerant and will parse most CSS input without throwing errors. Invalid CSS is typically preserved in the AST structure and passed through to the output, allowing downstream tools to handle validation and error reporting.