0
# Development Mode
1

2
Experimental development server integration with hot-reload support for CSS injection during development.
3

4
## Capabilities
5

6
### Development Options
7

8
Configure experimental development mode with CSS hot-reload support.
9

10
```typescript { .api }
11
/**
12
 * Development mode configuration (experimental)
13
 */
14
interface DevOptions {
15
  /** Enable plugin in development server */
16
  enableDev?: boolean;
17
  /** Custom style removal code for hot-reload */
18
  removeStyleCode?: (id: string) => string;
19
  /** Custom style removal runtime function for hot-reload */
20
  removeStyleCodeFunction?: (id: string) => void;
21
}
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import { defineConfig } from "vite";
28
import cssInjectedByJsPlugin from "vite-plugin-css-injected-by-js";
29

30
// Basic development mode
31
export default defineConfig({
32
  plugins: [
33
    cssInjectedByJsPlugin({
34
      dev: {
35
        enableDev: true,
36
      },
37
    }),
38
  ],
39
});
40

41
// Development mode with custom style removal
42
export default defineConfig({
43
  plugins: [
44
    cssInjectedByJsPlugin({
45
      dev: {
46
        enableDev: true,
47
        removeStyleCodeFunction: (id) => {
48
          console.log(`Removing styles for: ${id}`);
49
          // Custom cleanup logic
50
        },
51
      },
52
    }),
53
  ],
54
});
55
```
56

57
### Enable Development Mode
58

59
Activate plugin functionality in Vite's development server.
60

61
```typescript { .api }
62
/**
63
 * Enable plugin in development server
64
 * WARNING: Experimental feature with non-conventional implementation
65
 */
66
enableDev?: boolean;
67
```
68

69
**Usage Examples:**
70

71
```typescript
72
// Enable development mode
73
dev: {
74
  enableDev: true
75
}
76
```
77

78
**Important Notes:**
79
- This is an experimental feature using non-conventional solutions
80
- Development mode modifies CSS import behavior to inject styles via JavaScript
81
- Hot-reload functionality requires proper style removal code
82

83
### Custom Style Removal Code
84

85
Provide custom JavaScript code for removing injected styles during hot-reload.
86

87
```typescript { .api }
88
/**
89
 * Custom style removal code for hot-reload
90
 * @param id - Vite development ID for the CSS file
91
 * @returns JavaScript code string that removes the injected styles
92
 */
93
removeStyleCode?: (id: string) => string;
94
```
95

96
**Usage Examples:**
97

98
```typescript
99
// Custom removal code
100
removeStyleCode: (id) => `
101
  {
102
    const elements = document.querySelectorAll('style[data-vite-dev-id="${id}"]');
103
    elements.forEach(el => el.remove());
104
  }
105
`
106

107
// Enhanced removal with logging
108
removeStyleCode: (id) => `
109
  {
110
    console.log('Removing styles for:', '${id}');
111
    const selector = 'style[data-vite-dev-id="${id}"]';
112
    const elements = document.querySelectorAll(selector);
113
    elements.forEach(element => {
114
      element.remove();
115
    });
116
  }
117
`
118
```
119

120
### Custom Style Removal Function
121

122
Provide a runtime function for removing injected styles during hot-reload.
123

124
```typescript { .api }
125
/**
126
 * Custom style removal runtime function for hot-reload
127
 * @param id - Vite development ID for the CSS file
128
 */
129
removeStyleCodeFunction?: (id: string) => void;
130
```
131

132
**Usage Examples:**
133

134
```typescript
135
// Simple removal function
136
removeStyleCodeFunction: (id) => {
137
  const elements = document.querySelectorAll(`style[data-vite-dev-id="${id}"]`);
138
  elements.forEach(el => el.remove());
139
}
140

141
// Enhanced removal with error handling
142
removeStyleCodeFunction: (id) => {
143
  try {
144
    const selector = `style[data-vite-dev-id="${id}"]`;
145
    const elements = document.querySelectorAll(selector);
146
    console.log(`Removing ${elements.length} style elements for ${id}`);
147
    elements.forEach(element => {
148
      element.remove();
149
    });
150
  } catch (error) {
151
    console.warn('Failed to remove styles:', error);
152
  }
153
}
154
```
155

156
## Development Mode Implementation Details
157

158
### How Development Mode Works
159

160
1. **CSS Import Transformation**: The plugin intercepts CSS imports during development
161
2. **Style Injection**: CSS is injected via JavaScript instead of being served as separate files
162
3. **Hot-Reload Support**: Styles are removed and re-injected when CSS files change
163
4. **Attribute Tracking**: Injected styles include `data-vite-dev-id` attributes for identification
164

165
### Style Element Attributes in Development
166

167
During development, injected style elements include additional attributes:
168

169
```typescript { .api }
170
interface DevModeAttributes {
171
  "data-vite-dev-id": string; // Vite's development file ID
172
  [key: string]: string; // Additional custom attributes
173
}
174
```
175

176
### Compatibility with Custom Injection
177

178
When using custom injection functions (`injectCode` or `injectCodeFunction`) in development mode:
179

180
- The `options.attributes` object includes the `data-vite-dev-id` attribute
181
- Custom injection functions must handle the development attributes appropriately
182
- Style removal functions must target styles with the correct `data-vite-dev-id` value
183

184
**Example with custom injection and development mode:**
185

186
```typescript
187
export default defineConfig({
188
  plugins: [
189
    cssInjectedByJsPlugin({
190
      dev: {
191
        enableDev: true,
192
        removeStyleCodeFunction: (id) => {
193
          // Remove styles using the dev ID
194
          const elements = document.querySelectorAll(`style[data-vite-dev-id="${id}"]`);
195
          elements.forEach(el => el.remove());
196
        },
197
      },
198
      injectCodeFunction: (cssCode, options) => {
199
        try {
200
          if (typeof document !== 'undefined') {
201
            const style = document.createElement('style');
202
            
203
            // Set all attributes including dev attributes
204
            for (const [key, value] of Object.entries(options.attributes || {})) {
205
              style.setAttribute(key, value);
206
            }
207
            
208
            style.appendChild(document.createTextNode(cssCode));
209
            document.head.appendChild(style);
210
          }
211
        } catch (error) {
212
          console.error('CSS injection failed:', error);
213
        }
214
      },
215
    }),
216
  ],
217
});
218
```
219

220
### Development Mode Limitations
221

222
- **Experimental Status**: May have unexpected behavior or breaking changes
223
- **Performance Impact**: Additional JavaScript execution during development
224
- **Custom Injection Requirements**: Must implement compatible style removal when using custom injection
225
- **Hot-Reload Dependencies**: Requires proper cleanup for smooth hot-reload experience