0
# WebAssets Integration
1

2
Filter classes for integrating JavaScript transpilation into WebAssets asset pipeline, supporting automatic compilation of CoffeeScript, ES6+, TypeScript, JSX, and LESS in web applications.
3

4
## Package Information
5

6
WebAssets integration requires the optional webassets dependency:
7

8
```bash
9
pip install dukpy[webassets]
10
# or
11
pip install dukpy webassets
12
```
13

14
## Core Imports
15

16
```python
17
from webassets.filter import register_filter
18
from dukpy.webassets import BabelJS, TypeScript, CompileLess, BabelJSX
19
```
20

21
## Basic Usage
22

23
```python
24
from webassets import Bundle, Environment
25
from webassets.filter import register_filter
26
from dukpy.webassets import BabelJS, TypeScript, CompileLess, BabelJSX
27

28
# Register DukPy filters
29
register_filter(BabelJS)
30
register_filter(TypeScript) 
31
register_filter(CompileLess)
32
register_filter(BabelJSX)
33

34
# Create WebAssets environment
35
env = Environment('./static', './static/compiled')
36

37
# Create bundles with DukPy filters
38
js_bundle = Bundle(
39
    'js/app.js',
40
    'js/components/*.js',
41
    filters='babeljs',
42
    output='compiled/app.js'
43
)
44

45
tsx_bundle = Bundle(
46
    'tsx/main.tsx',
47
    'tsx/components/*.tsx',
48
    filters='typescript',
49
    output='compiled/main.js'
50
)
51

52
css_bundle = Bundle(
53
    'less/styles.less',
54
    'less/components/*.less',
55
    filters='lessc',
56
    output='compiled/styles.css'
57
)
58

59
env.register('js', js_bundle)
60
env.register('tsx', tsx_bundle)
61
env.register('css', css_bundle)
62
```
63

64
## Capabilities
65

66
### ES6+ Babel Filter
67

68
Compiles modern JavaScript to ES5 for browser compatibility using the same Babel engine as `babel_compile()`.
69

70
```python { .api }
71
class BabelJS(Filter):
72
    """
73
    WebAssets filter for ES6+ compilation using BabelJS.
74
    
75
    Filter name: 'babeljs'
76
    
77
    Options:
78
    - BABEL_MODULES_LOADER: Module system ('systemjs', 'umd', or default CommonJS)
79
    
80
    Attributes:
81
    - max_debug_level: None (no debug level restrictions)
82
    """
83
    
84
    name = 'babeljs'
85
    max_debug_level = None
86
    options = {
87
        'loader': 'BABEL_MODULES_LOADER'
88
    }
89
    
90
    def input(self, _in, out, **kw):
91
        """
92
        Process input file through Babel compilation.
93
        
94
        Parameters:
95
        - _in: Input file stream
96
        - out: Output file stream  
97
        - **kw: Additional context including source_path
98
        """
99
```
100

101
Configuration and usage:
102

103
```python
104
from webassets import Bundle
105
from webassets.filter import register_filter
106
from dukpy.webassets import BabelJS
107

108
register_filter(BabelJS)
109

110
# Default CommonJS modules
111
bundle = Bundle(
112
    'js/src/*.js',
113
    filters='babeljs',
114
    output='js/compiled.js'
115
)
116

117
# SystemJS modules
118
import os
119
os.environ['BABEL_MODULES_LOADER'] = 'systemjs'
120
bundle = Bundle(
121
    'js/src/*.js', 
122
    filters='babeljs',
123
    output='js/compiled.js'
124
)
125

126
# UMD modules
127
os.environ['BABEL_MODULES_LOADER'] = 'umd'
128
bundle = Bundle(
129
    'js/src/*.js',
130
    filters='babeljs', 
131
    output='js/compiled.js'
132
)
133
```
134

135
### TypeScript Filter
136

137
Compiles TypeScript files to JavaScript using the same TypeScript compiler as `typescript_compile()`.
138

139
```python { .api }
140
class TypeScript(Filter):
141
    """
142
    WebAssets filter for TypeScript compilation.
143
    
144
    Filter name: 'typescript'
145
    
146
    Uses fixed compiler options:
147
    - Module format: SystemJS
148
    - Target: ES5
149
    - Requires SystemJS runtime for browser usage
150
    
151
    Attributes:
152
    - max_debug_level: None (no debug level restrictions)
153
    """
154
    
155
    name = 'typescript'
156
    max_debug_level = None
157
    
158
    def input(self, _in, out, **kw):
159
        """
160
        Process input file through TypeScript compilation.
161
        
162
        Parameters:
163
        - _in: Input file stream
164
        - out: Output file stream
165
        - **kw: Additional context including source_path
166
        """
167
```
168

169
Usage example:
170

171
```python
172
from webassets import Bundle
173
from webassets.filter import register_filter
174
from dukpy.webassets import TypeScript
175

176
register_filter(TypeScript)
177

178
typescript_bundle = Bundle(
179
    'ts/app.ts',
180
    'ts/components/*.ts',
181
    filters='typescript',
182
    output='js/app.js'
183
)
184
```
185

186
### LESS CSS Filter
187

188
Compiles LESS stylesheets to CSS using the same LESS compiler as `less_compile()`.
189

190
```python { .api }
191
class CompileLess(Filter):
192
    """
193
    WebAssets filter for LESS compilation.
194
    
195
    Filter name: 'lessc'
196
    
197
    Options:
198
    - LIBSASS_INCLUDES: Additional include paths for LESS @import resolution (reused environment variable name)
199
    
200
    Attributes:
201
    - max_debug_level: None (no debug level restrictions)
202
    """
203
    
204
    name = 'lessc'
205
    max_debug_level = None
206
    options = {
207
        'less_includes': option('LIBSASS_INCLUDES', type=list)
208
    }
209
    
210
    def input(self, _in, out, **kw):
211
        """
212
        Process input file through LESS compilation.
213
        
214
        Parameters:
215
        - _in: Input file stream
216
        - out: Output file stream
217
        - **kw: Additional context including source_path
218
        
219
        Automatically adds source file directory to include paths.
220
        """
221
```
222

223
Usage example:
224

225
```python
226
from webassets import Bundle
227
from webassets.filter import register_filter
228
from dukpy.webassets import CompileLess
229
import os
230

231
register_filter(CompileLess)
232

233
# Basic LESS compilation
234
less_bundle = Bundle(
235
    'less/main.less',
236
    'less/components/*.less',
237
    filters='lessc',
238
    output='css/styles.css'
239
)
240

241
# With custom include paths
242
os.environ['LIBSASS_INCLUDES'] = 'less/mixins:less/variables:node_modules'
243
less_bundle_with_includes = Bundle(
244
    'less/app.less',
245
    filters='lessc',
246
    output='css/app.css'
247
)
248
```
249

250
### JSX React Filter
251

252
Compiles JSX to React-compatible JavaScript using the same JSX compiler as `jsx_compile()`.
253

254
```python { .api }
255
class BabelJSX(Filter):
256
    """
257
    WebAssets filter for JSX compilation using BabelJS with React presets.
258
    
259
    Filter name: 'babeljsx'
260
    
261
    Options:
262
    - BABEL_MODULES_LOADER: Module system ('systemjs', 'umd', or default CommonJS)
263
    
264
    Automatically configures Babel with ['es2015', 'react'] presets.
265
    """
266
    
267
    name = 'babeljsx'
268
    options = {
269
        'loader': 'BABEL_MODULES_LOADER'
270
    }
271
    
272
    def input(self, _in, out, **kw):
273
        """
274
        Process input file through JSX compilation.
275
        
276
        Parameters:
277
        - _in: Input file stream
278
        - out: Output file stream
279
        - **kw: Additional context including source_path
280
        """
281
```
282

283
Usage example:
284

285
```python
286
from webassets import Bundle
287
from webassets.filter import register_filter
288
from dukpy.webassets import BabelJSX
289

290
register_filter(BabelJSX)
291

292
jsx_bundle = Bundle(
293
    'jsx/app.jsx',
294
    'jsx/components/*.jsx',
295
    filters='babeljsx',
296
    output='js/react-app.js'
297
)
298
```
299

300
## Complete Integration Example
301

302
```python
303
from webassets import Bundle, Environment
304
from webassets.filter import register_filter
305
from dukpy.webassets import BabelJS, TypeScript, CompileLess, BabelJSX
306
import os
307

308
# Register all DukPy filters
309
register_filter(BabelJS)
310
register_filter(TypeScript)
311
register_filter(CompileLess)
312
register_filter(BabelJSX)
313

314
# Configure environment variables
315
os.environ['BABEL_MODULES_LOADER'] = 'umd'
316
os.environ['LIBSASS_INCLUDES'] = 'assets/less/mixins:assets/less/variables'
317

318
# Create WebAssets environment
319
env = Environment(
320
    directory='./assets',
321
    url='/static/',
322
    load_path=['./assets']
323
)
324

325
# JavaScript bundles
326
modern_js = Bundle(
327
    'js/modern/*.js',
328
    filters='babeljs',
329
    output='compiled/modern.js'
330
)
331

332
react_components = Bundle(
333
    'jsx/components/*.jsx',
334
    'jsx/app.jsx',
335
    filters='babeljsx',
336
    output='compiled/react-app.js'
337
)
338

339
typescript_app = Bundle(
340
    'ts/main.ts',
341
    'ts/services/*.ts',
342
    'ts/components/*.ts',
343
    filters='typescript',
344
    output='compiled/typescript-app.js'
345
)
346

347
# CSS bundles
348
styles = Bundle(
349
    'less/main.less',
350
    'less/components/*.less',
351
    filters='lessc',
352
    output='compiled/styles.css'
353
)
354

355
# Register bundles
356
env.register('modern_js', modern_js)
357
env.register('react', react_components)
358
env.register('typescript', typescript_app)
359
env.register('styles', styles)
360

361
# Build assets
362
modern_js.build()
363
react_components.build()
364
typescript_app.build()
365
styles.build()
366
```
367

368
## Browser Runtime Requirements
369

370
### BabelJS and BabelJSX
371
- Requires babel-polyfill for full ES6+ feature support
372
- SystemJS or UMD builds require appropriate module loaders
373

374
### TypeScript
375
- Compiled output uses SystemJS modules
376
- Requires SystemJS runtime: https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.24/system.js
377

378
### React JSX
379
- Requires React runtime library
380
- Babel polyfill recommended for ES6+ features
381

382
## Configuration Options
383

384
All filters support WebAssets' standard configuration through environment variables:
385

386
```python
387
import os
388

389
# Configure Babel module format
390
os.environ['BABEL_MODULES_LOADER'] = 'systemjs'  # or 'umd'
391

392
# Configure LESS include paths  
393
os.environ['LIBSASS_INCLUDES'] = 'path1:path2:path3'
394

395
# Multiple paths on Windows
396
os.environ['LIBSASS_INCLUDES'] = 'path1;path2;path3'
397
```
398

399
## Error Handling
400

401
WebAssets filters will raise the underlying DukPy exceptions during compilation:
402

403
- `JSRuntimeError`: JavaScript/TypeScript compilation errors
404
- `LessCompilerError`: LESS compilation errors
405

406
These errors will be caught by WebAssets and reported as build failures with detailed error messages.