0
# Build Utilities
1

2
Core build functionality for managing JupyterLab extension assets, including schema copying, theme processing, CSS import generation, and extension metadata normalization.
3

4
## Capabilities
5

6
### Asset Management
7

8
Ensures that extension packages have their assets (schemas, themes, styles) properly copied and configured for the build process.
9

10
```typescript { .api }
11
/**
12
 * Ensures that the assets of plugin packages are populated for a build
13
 * @param options - Configuration options for asset management
14
 * @returns Array of webpack configuration objects for theme processing
15
 */
16
function Build.ensureAssets(options: Build.IEnsureOptions): webpack.Configuration[];
17

18
interface Build.IEnsureOptions {
19
  /** The output directory where the build assets should reside */
20
  output: string;
21
  /** The directory for the schema directory, defaults to the output directory */
22
  schemaOutput?: string;
23
  /** The directory for the theme directory, defaults to the output directory */
24
  themeOutput?: string;
25
  /** The names of the packages to ensure */
26
  packageNames: ReadonlyArray<string>;
27
  /** The package paths to ensure */
28
  packagePaths?: ReadonlyArray<string>;
29
}
30
```
31

32
The `ensureAssets` function performs several key operations:
33

34
1. **Schema Processing**: Copies schema files from extension packages to the designated schema output directory
35
2. **Theme Configuration**: Creates webpack configurations for theme CSS processing and extraction
36
3. **Style Import Generation**: Generates a consolidated `style.js` file with imports for all extension stylesheets
37
4. **Asset Resolution**: Resolves package paths and validates package metadata
38

39
**Usage Example:**
40

41
```typescript
42
import { Build } from "@jupyterlab/builder";
43

44
// Ensure assets for multiple extensions
45
const themeConfigs = Build.ensureAssets({
46
  output: "./build",
47
  schemaOutput: "./build/schemas", 
48
  themeOutput: "./build/themes",
49
  packageNames: [
50
    "@jupyterlab/notebook",
51
    "@jupyterlab/fileeditor",
52
    "@my-org/custom-extension"
53
  ]
54
});
55

56
// The returned configurations can be used with webpack
57
import * as webpack from "webpack";
58
const compiler = webpack(themeConfigs);
59
```
60

61
### Extension Metadata Normalization
62

63
Extracts and normalizes JupyterLab extension metadata from package.json files.
64

65
```typescript { .api }
66
/**
67
 * Returns JupyterLab extension metadata from a module
68
 * @param module - Module definition containing package.json data
69
 * @returns Normalized extension metadata
70
 * @throws Error if module does not contain JupyterLab metadata
71
 */
72
function Build.normalizeExtension(module: Build.IModule): Build.ILabExtension;
73

74
interface Build.IModule {
75
  /** The JupyterLab metadata */
76
  jupyterlab?: Build.ILabExtension;
77
  /** The main entry point in a module */
78
  main?: string;
79
  /** The name of a module */
80
  name: string;
81
}
82

83
interface Build.ILabExtension {
84
  /** 
85
   * Indicates whether the extension is a standalone extension.
86
   * If true, uses the main export. If string, uses that path as entry point.
87
   */
88
  readonly extension?: boolean | string;
89
  /** 
90
   * Indicates whether the extension is a MIME renderer extension.
91
   * If true, uses the main export. If string, uses that path as entry point.
92
   */
93
  readonly mimeExtension?: boolean | string;
94
  /** The local schema file path in the extension package */
95
  readonly schemaDir?: string;
96
  /** The local theme file path in the extension package */
97
  readonly themePath?: string;
98
}
99
```
100

101
The `normalizeExtension` function:
102

103
1. **Entry Point Resolution**: Resolves extension and mimeExtension entry points to actual file paths
104
2. **Validation**: Ensures extension and mimeExtension don't point to the same export
105
3. **Default Handling**: Uses `main` field as default when extension/mimeExtension is `true`
106
4. **Error Handling**: Throws descriptive errors for invalid configurations
107

108
**Usage Example:**
109

110
```typescript
111
import { Build } from "@jupyterlab/builder";
112

113
// Normalize extension metadata from package.json
114
const moduleData = {
115
  name: "@my-org/my-extension",
116
  main: "lib/index.js",
117
  jupyterlab: {
118
    extension: true,
119
    schemaDir: "schema",
120
    themePath: "style/index.css"
121
  }
122
};
123

124
const normalized = Build.normalizeExtension(moduleData);
125
// Result: {
126
//   extension: "lib/index.js",
127
//   mimeExtension: undefined,
128
//   schemaDir: "schema", 
129
//   themePath: "style/index.css"
130
// }
131
```
132

133
## Asset Processing Details
134

135
### Schema Handling
136

137
The asset management system automatically:
138

139
- Discovers schema files using glob patterns
140
- Creates versioned schema directories to avoid conflicts  
141
- Preserves package.json metadata for version comparison
142
- Handles incremental updates by comparing package versions
143

144
### Theme Processing
145

146
Theme assets are processed through webpack configurations that:
147

148
- Extract CSS using MiniCssExtractPlugin
149
- Process SVG files as data URIs for CSS contexts
150
- Handle various asset types (fonts, images, etc.)
151
- Generate production-optimized theme bundles
152

153
### Style Import Generation
154

155
The system generates a consolidated `style.js` file containing:
156

157
- Alphabetically sorted imports from all extensions
158
- Preference for `styleModule` over `style` package.json fields
159
- Generated header comments indicating the build source
160
- UTF-8 encoded output for proper character handling