0
# Rework
1

2
Rework is a flexible CSS manipulation framework built on top of the CSS parser library. It provides a plugin-based architecture for creating custom CSS transformations through a simple chainable API, supporting operations like vendor prefixing, property creation, image inlining, and any other CSS manipulations.
3

4
## Package Information
5

6
- **Package Name**: rework
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install rework`
10

11
## Core Imports
12

13
```javascript
14
const rework = require('rework');
15
```
16

17

18
## Basic Usage
19

20
```javascript
21
const rework = require('rework');
22

23
// Transform CSS with plugins
24
const css = rework('body { font-size: 12px; }', { source: 'source.css' })
25
  .use(pluginA)
26
  .use(pluginB)
27
  .toString({ sourcemap: true });
28

29
console.log(css);
30
```
31

32
## Architecture
33

34
Rework is built around several key components:
35

36
- **Plugin Framework**: Core functionality extended through plugin functions that operate on CSS AST
37
- **Chainable API**: Fluent interface allowing sequential application of multiple transformations
38
- **CSS AST**: Built on the `css` library's Abstract Syntax Tree for reliable parsing and stringification
39
- **Source Map Support**: Built-in source map generation and inlining for debugging transformed CSS
40
- **Zero Built-ins**: Pure framework providing only plugin application infrastructure
41

42
## Capabilities
43

44
### CSS Parsing and Instantiation
45

46
Creates a new Rework instance from CSS string input with optional parsing configuration.
47

48
```javascript { .api }
49
/**
50
 * Creates a new Rework instance from CSS string
51
 * @param {string} str - CSS string to parse
52
 * @param {Object} [options] - Options passed to css.parse
53
 * @param {string} [options.source] - Source filename for source maps
54
 * @returns {Rework} New Rework instance for chaining operations
55
 */
56
function rework(str, options);
57
```
58

59
**Usage Examples:**
60

61
```javascript
62
// Basic parsing
63
const stylesheet = rework('body { color: red; }');
64

65
// With source information for source maps
66
const stylesheet = rework(cssString, { source: 'input.css' });
67

68
// With CSS parser options
69
const stylesheet = rework(cssString, { 
70
  source: 'styles.css',
71
  position: true  // Include position info in AST
72
});
73
```
74

75
### Plugin Application
76

77
Applies plugin functions to transform the CSS Abstract Syntax Tree. Plugins receive the stylesheet AST and the Rework instance.
78

79
```javascript { .api }
80
/**
81
 * Applies a plugin function to the stylesheet
82
 * @param {Function} fn - Plugin function receiving (stylesheet, rework) parameters
83
 * @returns {Rework} Same Rework instance for method chaining
84
 */
85
Rework.prototype.use(fn);
86
```
87

88
**Plugin Function Signature:**
89

90
```javascript { .api }
91
/**
92
 * Plugin function signature
93
 * @param {Object} stylesheet - CSS AST stylesheet node with rules array
94
 * @param {Rework} rework - The Rework instance for additional context
95
 */
96
function plugin(stylesheet, rework) {
97
  // Modify stylesheet.rules or other AST properties
98
  // Example: add vendor prefixes, transform properties, etc.
99
}
100
```
101

102
**Usage Examples:**
103

104
```javascript
105
// Simple plugin example
106
function addPrefix(stylesheet, rework) {
107
  stylesheet.rules.forEach(rule => {
108
    if (rule.type === 'rule') {
109
      rule.declarations.forEach(decl => {
110
        if (decl.property === 'transform') {
111
          // Add vendor-prefixed versions
112
          stylesheet.rules.push({
113
            type: 'rule',
114
            selectors: rule.selectors,
115
            declarations: [
116
              { property: '-webkit-transform', value: decl.value },
117
              { property: '-moz-transform', value: decl.value }
118
            ]
119
          });
120
        }
121
      });
122
    }
123
  });
124
}
125

126
// Apply plugin
127
const result = rework(css)
128
  .use(addPrefix)
129
  .toString();
130

131
// Chain multiple plugins
132
const result = rework(css)
133
  .use(plugin1)
134
  .use(plugin2) 
135
  .use(plugin3)
136
  .toString();
137
```
138

139
### CSS Stringification
140

141
Converts the manipulated CSS AST back to CSS string with optional formatting and source map support.
142

143
```javascript { .api }
144
/**
145
 * Converts CSS AST to string with optional source map support
146
 * @param {Object} [options] - Options passed to css.stringify plus rework-specific options
147
 * @param {boolean} [options.sourcemap] - Generate and include source map information
148
 * @param {boolean} [options.sourcemapAsObject] - When true with sourcemap, returns {code, map} object instead of string
149
 * @param {boolean} [options.compress] - Compress CSS output (remove whitespace)
150
 * @param {number} [options.indent] - Indentation for pretty printing (default: 2 spaces)
151
 * @returns {string|Object} CSS string with optional inline sourcemap, or {code: string, map: Object} when sourcemapAsObject: true
152
 */
153
Rework.prototype.toString(options);
154
```
155

156
**Usage Examples:**
157

158
```javascript
159
// Basic stringification
160
const css = rework(input).use(plugin).toString();
161

162
// Compressed output
163
const minified = rework(input)
164
  .use(plugin)
165
  .toString({ compress: true });
166

167
// With inline source map (as base64-encoded comment)
168
const cssWithMap = rework(input, { source: 'input.css' })
169
  .use(plugin)
170
  .toString({ sourcemap: true });
171
// Returns: "body{color:red;}\n/*# sourceMappingURL=data:application/json;base64,... */"
172

173
// With source map as separate object
174
const result = rework(input, { source: 'input.css' })
175
  .use(plugin) 
176
  .toString({ 
177
    sourcemap: true, 
178
    sourcemapAsObject: true 
179
  });
180
// result.code contains CSS string
181
// result.map contains source map object with version, sources, mappings, etc.
182

183
// Source map requires source option during parsing
184
const reworkInstance = rework(cssString, { source: 'original.css' });
185
```
186

187
## Types
188

189
```javascript { .api }
190
/**
191
 * Rework class - Internal constructor (instantiated via rework factory function)
192
 * @class
193
 */
194
function Rework(obj) {
195
  /**
196
   * CSS AST object containing stylesheet structure from css.parse
197
   * @type {Object}
198
   */
199
  this.obj = obj;
200
}
201

202
/**
203
 * CSS AST stylesheet structure (from css library)
204
 * The root object returned by css.parse()
205
 * @typedef {Object} Stylesheet
206
 * @property {string} type - Always 'stylesheet'
207
 * @property {Object} stylesheet - The stylesheet container
208
 * @property {Rule[]} stylesheet.rules - Array of CSS rules
209
 * @property {Error[]} [stylesheet.parsingErrors] - Parse errors if any
210
 */
211

212
/**
213
 * CSS rule object in the AST
214
 * @typedef {Object} Rule
215
 * @property {string} type - Rule type: 'rule', 'comment', 'media', 'keyframes', 'supports', etc.
216
 * @property {string[]} [selectors] - CSS selectors (for 'rule' type)
217
 * @property {Declaration[]} [declarations] - CSS declarations (for 'rule' type)
218
 * @property {string} [comment] - Comment text (for 'comment' type)
219
 * @property {Rule[]} [rules] - Nested rules (for 'media', 'keyframes', etc.)
220
 */
221

222
/**
223
 * CSS declaration object
224
 * @typedef {Object} Declaration
225
 * @property {string} type - Always 'declaration'
226
 * @property {string} property - CSS property name
227
 * @property {string} value - CSS property value
228
 */
229
```