0
# Build Integration
1

2
Babel plugin and webpack loader for transforming styled-jsx syntax and processing external CSS files.
3

4
## Capabilities
5

6
### Babel Plugin
7

8
The core Babel plugin that transforms styled-jsx tagged template literals into optimized runtime code.
9

10
```javascript { .api }
11
/**
12
 * Babel plugin that transforms styled-jsx tagged templates
13
 * @param options - Plugin configuration options
14
 * @returns Babel plugin function
15
 */
16
module.exports = function styledJsxBabelPlugin(options?: {
17
  /** Use CSSOM injection for optimized performance (default: false) */
18
  optimizeForSpeed?: boolean;
19
  /** Generate source maps for debugging (default: false) */  
20
  sourceMaps?: boolean;
21
  /** Custom path to style module (default: 'styled-jsx/style') */
22
  styleModule?: string;
23
  /** Enable automatic vendor prefixing (default: true) */
24
  vendorPrefixes?: boolean;
25
  /** CSS preprocessing plugins array */
26
  plugins?: Array<any>;
27
}): any;
28
```
29

30
**Basic Setup:**
31

32
```json
33
{
34
  "plugins": ["styled-jsx/babel"]
35
}
36
```
37

38
**Advanced Configuration:**
39

40
```json
41
{
42
  "plugins": [
43
    [
44
      "styled-jsx/babel", 
45
      {
46
        "optimizeForSpeed": true,
47
        "sourceMaps": false,
48
        "vendorPrefixes": true,
49
        "plugins": ["styled-jsx-plugin-postcss"]
50
      }
51
    ]
52
  ]
53
}
54
```
55

56
**Usage Examples:**
57

58
```javascript
59
// .babelrc.js
60
module.exports = {
61
  presets: ['@babel/preset-react'],
62
  plugins: [
63
    [
64
      'styled-jsx/babel',
65
      {
66
        optimizeForSpeed: process.env.NODE_ENV === 'production',
67
        sourceMaps: process.env.NODE_ENV === 'development',
68
        vendorPrefixes: true
69
      }
70
    ]
71
  ]
72
};
73

74
// babel.config.js (for monorepos)
75
module.exports = {
76
  presets: ['@babel/preset-env', '@babel/preset-react'],
77
  plugins: [
78
    ['styled-jsx/babel', {
79
      // Development settings
80
      optimizeForSpeed: false,
81
      sourceMaps: true,
82
      vendorPrefixes: true
83
    }]
84
  ],
85
  env: {
86
    production: {
87
      plugins: [
88
        ['styled-jsx/babel', {
89
          // Production optimizations
90
          optimizeForSpeed: true,
91
          sourceMaps: false,
92
          vendorPrefixes: true
93
        }]
94
      ]
95
    }
96
  }
97
};
98
```
99

100
### Webpack Loader
101

102
Webpack loader configuration for processing external CSS files with styled-jsx.
103

104
```javascript { .api }
105
/**
106
 * Webpack loader configuration object
107
 * Contains path to the webpack loader module
108
 */
109
module.exports = {
110
  /** Path to webpack loader module */
111
  loader: string;
112
}
113
```
114

115
**Basic Webpack Setup:**
116

117
```javascript
118
// webpack.config.js
119
const styledJsxWebpack = require('styled-jsx/webpack');
120

121
module.exports = {
122
  module: {
123
    rules: [
124
      {
125
        test: /\.css$/,
126
        use: [
127
          'babel-loader',
128
          styledJsxWebpack.loader
129
        ]
130
      }
131
    ]
132
  }
133
};
134
```
135

136
**Advanced Webpack Configuration:**
137

138
```javascript
139
// webpack.config.js
140
const path = require('path');
141

142
module.exports = {
143
  module: {
144
    rules: [
145
      // Handle .jsx and .js files
146
      {
147
        test: /\.(js|jsx)$/,
148
        exclude: /node_modules/,
149
        use: {
150
          loader: 'babel-loader',
151
          options: {
152
            presets: ['@babel/preset-react'],
153
            plugins: [
154
              ['styled-jsx/babel', {
155
                optimizeForSpeed: process.env.NODE_ENV === 'production'
156
              }]
157
            ]
158
          }
159
        }
160
      },
161
      // Handle external CSS files with styled-jsx
162
      {
163
        test: /\.css$/,
164
        include: path.resolve(__dirname, 'src/styles'),
165
        use: [
166
          'babel-loader',
167
          {
168
            loader: require.resolve('styled-jsx/webpack'),
169
            options: {
170
              type: 'scoped' // or 'global', 'resolve'
171
            }
172
          }
173
        ]
174
      }
175
    ]
176
  },
177
  resolve: {
178
    extensions: ['.js', '.jsx', '.css']
179
  }
180
};
181
```
182

183
### CSS File Processing
184

185
Using external CSS files with styled-jsx webpack loader.
186

187
**CSS File (styles/button.css):**
188

189
```css
190
.button {
191
  padding: 12px 24px;
192
  border: none;
193
  border-radius: 4px;
194
  cursor: pointer;
195
  font-size: 16px;
196
  transition: all 0.2s;
197
}
198

199
.button:hover {
200
  transform: translateY(-1px);
201
  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.15);
202
}
203

204
.primary {
205
  background: #007bff;
206
  color: white;
207
}
208

209
.secondary {
210
  background: #6c757d;
211
  color: white;
212
}
213
```
214

215
**Component Usage:**
216

217
```jsx
218
import buttonStyles from './styles/button.css';
219

220
function Button({ variant = 'primary', children, ...props }) {
221
  return (
222
    <div>
223
      <button className={`button ${variant}`} {...props}>
224
        {children}
225
      </button>
226
      {buttonStyles}
227
    </div>
228
  );
229
}
230
```
231

232
### Next.js Integration
233

234
styled-jsx is built into Next.js and requires no additional configuration.
235

236
```jsx { .api }
237
// Next.js includes styled-jsx by default
238
// No babel configuration needed
239
<style jsx>{`/* styles */`}</style>
240
<style jsx global>{`/* global styles */`}</style>
241
```
242

243
**Usage in Next.js:**
244

245
```jsx
246
// pages/index.js
247
export default function Home() {
248
  return (
249
    <div className="container">
250
      <h1>Welcome to Next.js</h1>
251
      <p className="description">
252
        Get started by editing pages/index.js
253
      </p>
254
      
255
      <style jsx>{`
256
        .container {
257
          min-height: 100vh;
258
          padding: 0 0.5rem;
259
          display: flex;
260
          flex-direction: column;
261
          justify-content: center;
262
          align-items: center;
263
        }
264
        
265
        .description {
266
          text-align: center;
267
          line-height: 1.5;
268
          font-size: 1.5rem;
269
        }
270
      `}</style>
271
      
272
      <style jsx global>{`
273
        html,
274
        body {
275
          padding: 0;
276
          margin: 0;
277
          font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto;
278
        }
279
        
280
        * {
281
          box-sizing: border-box;
282
        }
283
      `}</style>
284
    </div>
285
  );
286
}
287

288
// pages/_app.js (for global styles)
289
import App from 'next/app';
290

291
class MyApp extends App {
292
  render() {
293
    const { Component, pageProps } = this.props;
294
    
295
    return (
296
      <>
297
        <Component {...pageProps} />
298
        <style jsx global>{`
299
          body {
300
            font-family: 'SF Pro Display', -apple-system, BlinkMacSystemFont;
301
          }
302
        `}</style>
303
      </>
304
    );
305
  }
306
}
307

308
export default MyApp;
309
```
310

311
### Configuration Options
312

313
Detailed breakdown of all configuration options available.
314

315
#### optimizeForSpeed
316

317
Enables CSSOM-based injection for better performance in production.
318

319
```json
320
{
321
  "plugins": [["styled-jsx/babel", { "optimizeForSpeed": true }]]
322
}
323
```
324

325
**Effects:**
326
- Uses CSSOM APIs for faster style injection
327
- Reduces bundle size by optimizing style handling  
328
- Disables source maps (incompatible)
329
- Automatically enabled in production (`NODE_ENV === 'production'`)
330

331
#### sourceMaps
332

333
Generates source maps for easier debugging during development.
334

335
```json
336
{
337
  "plugins": [["styled-jsx/babel", { "sourceMaps": true }]]
338
}
339
```
340

341
**Effects:**
342
- Enables CSS source map generation
343
- Maps compiled CSS back to original JSX
344
- Only works when `optimizeForSpeed` is false
345
- Useful for development debugging
346

347
#### styleModule
348

349
Customizes the import path for the style component.
350

351
```json
352
{
353
  "plugins": [["styled-jsx/babel", { "styleModule": "./custom-style-module" }]]
354
}
355
```
356

357
**Custom Style Module Example:**
358

359
```javascript
360
// custom-style-module.js
361
import DefaultJSXStyle from 'styled-jsx/style';
362

363
export default function CustomJSXStyle(props) {
364
  // Add custom behavior
365
  console.log('Style rendered:', props.id);
366
  
367
  // Use default implementation
368
  return DefaultJSXStyle(props);
369
}
370
```
371

372
#### vendorPrefixes
373

374
Controls automatic vendor prefix generation.
375

376
```json
377
{
378
  "plugins": [["styled-jsx/babel", { "vendorPrefixes": false }]]
379
}
380
```
381

382
**Effects:**
383
- `true` (default): Automatically adds vendor prefixes
384
- `false`: Disables vendor prefixing
385
- Uses autoprefixer-like functionality
386

387
#### plugins
388

389
Array of CSS preprocessing plugins.
390

391
```json
392
{
393
  "plugins": [
394
    [
395
      "styled-jsx/babel", 
396
      {
397
        "plugins": [
398
          "styled-jsx-plugin-postcss",
399
          ["styled-jsx-plugin-scss", { "sassOptions": {} }]
400
        ]
401
      }
402
    ]
403
  ]
404
}
405
```
406

407
**Available Plugins:**
408

409
```javascript
410
// Using PostCSS
411
{
412
  "plugins": [
413
    [
414
      "styled-jsx/babel",
415
      {
416
        "plugins": [
417
          [
418
            "styled-jsx-plugin-postcss",
419
            {
420
              "plugins": [
421
                "postcss-nested",
422
                "autoprefixer"
423
              ]
424
            }
425
          ]
426
        ]
427
      }
428
    ]
429
  ]
430
}
431

432
// Using Sass
433
{
434
  "plugins": [
435
    [
436
      "styled-jsx/babel",
437
      {
438
        "plugins": [
439
          [
440
            "styled-jsx-plugin-sass",
441
            {
442
              "sassOptions": {
443
                "includePaths": ["./styles"]
444
              }
445
            }
446
          ]
447
        ]
448
      }
449
    ]
450
  ]
451
}
452
```
453

454
### TypeScript Configuration
455

456
Setting up styled-jsx with TypeScript projects.
457

458
**tsconfig.json:**
459

460
```json
461
{
462
  "compilerOptions": {
463
    "jsx": "preserve",
464
    "types": ["styled-jsx"]
465
  },
466
  "include": [
467
    "next-env.d.ts",
468
    "**/*.ts",
469
    "**/*.tsx"
470
  ]
471
}
472
```
473

474
**Custom Type Definitions:**
475

476
```typescript
477
// types/styled-jsx.d.ts
478
import 'react';
479

480
declare module 'react' {
481
  interface StyleHTMLAttributes<T> extends HTMLAttributes<T> {
482
    jsx?: boolean;
483
    global?: boolean;
484
  }
485
}
486

487
// For css.resolve usage
488
declare module 'styled-jsx/css' {
489
  interface ResolveResult {
490
    className: string;
491
    styles: JSX.Element;
492
  }
493
  
494
  function resolve(
495
    template: TemplateStringsArray,
496
    ...args: any[]
497
  ): ResolveResult;
498
}
499
```