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.