0
# Build System
1

2
Core build functionality for processing Svelte packages with support for TypeScript, preprocessing, and file watching.
3

4
## Capabilities
5

6
### Build Function
7

8
Builds a Svelte package once, processing all files and generating output.
9

10
```typescript { .api }
11
/**
12
 * Build a Svelte package once
13
 * @param options - Build configuration options
14
 */
15
function build(options: Options): Promise<void>;
16
```
17

18
**Usage Examples:**
19

20
```typescript
21
import { build } from "@sveltejs/package/src/index.js";
22
import { load_config } from "@sveltejs/package/src/config.js";
23

24
// Basic build
25
const config = await load_config();
26
await build({
27
  cwd: process.cwd(),
28
  input: "src/lib",
29
  output: "dist",
30
  preserve_output: false,
31
  types: true,
32
  config
33
});
34

35
// Build without TypeScript declarations
36
await build({
37
  cwd: process.cwd(),
38
  input: "src/lib", 
39
  output: "dist",
40
  preserve_output: false,
41
  types: false,
42
  config
43
});
44

45
// Build preserving existing output
46
await build({
47
  cwd: process.cwd(),
48
  input: "src/lib",
49
  output: "dist", 
50
  preserve_output: true,
51
  types: true,
52
  config
53
});
54
```
55

56
### Watch Function
57

58
Builds a Svelte package and watches for file changes, rebuilding incrementally.
59

60
```typescript { .api }
61
/**
62
 * Build a Svelte package and watch for changes
63
 * @param options - Build configuration options
64
 * @returns WatchResult with watcher controls
65
 */
66
function watch(options: Options): Promise<WatchResult>;
67

68
interface WatchResult {
69
  /** Chokidar file watcher instance */
70
  watcher: chokidar.FSWatcher;
71
  /** Promise that resolves when watcher is ready */
72
  ready: Promise<void>;
73
  /** Promise that resolves when current processing batch is complete */
74
  settled(): Promise<void>;
75
}
76
```
77

78
**Usage Examples:**
79

80
```typescript
81
import { watch } from "@sveltejs/package/src/index.js";
82
import { load_config } from "@sveltejs/package/src/config.js";
83

84
// Start watching
85
const config = await load_config();
86
const watchResult = await watch({
87
  cwd: process.cwd(),
88
  input: "src/lib",
89
  output: "dist",
90
  preserve_output: false,
91
  types: true,
92
  config
93
});
94

95
// Wait for watcher to be ready
96
await watchResult.ready;
97
console.log("Watching for changes...");
98

99
// Wait for current batch to complete
100
await watchResult.settled();
101

102
// Stop watching
103
watchResult.watcher.close();
104
```
105

106
## Build Process
107

108
The build system follows this process:
109

110
1. **Validation**: Validate input directory exists
111
2. **Setup**: Create temporary directory, scan for files
112
3. **TypeScript**: Generate .d.ts files if types enabled
113
4. **File Processing**: Process each file (Svelte preprocessing, TS transpilation, alias resolution)
114
5. **Output**: Copy processed files to output directory
115
6. **Validation**: Run package validation checks
116

117
### File Processing Pipeline
118

119
Each file goes through:
120

121
1. **Detection**: Analyze file type and determine processing needs
122
2. **Preprocessing**: Apply Svelte preprocessors if applicable
123
3. **Transpilation**: Convert TypeScript to JavaScript if needed
124
4. **Alias Resolution**: Resolve $lib and custom path aliases
125
5. **Code Analysis**: Analyze processed code for validation
126
6. **Writing**: Write processed file to output
127

128
### Watch Mode Behavior
129

130
In watch mode:
131

132
- Incremental processing of changed files only
133
- Debounced rebuilds (100ms delay)
134
- Automatic .d.ts regeneration when TypeScript files change
135
- File deletion handling with cleanup of empty directories
136
- Error isolation - errors don't stop the watcher
137

138
### Utility Functions
139

140
Supporting utility functions used internally by the build system.
141

142
```typescript { .api }
143
/**
144
 * Resolves path aliases in import statements
145
 * @param input - Input directory path
146
 * @param file - File path relative to input
147
 * @param content - File content to process
148
 * @param aliases - Alias mapping (e.g., { '$lib': 'src/lib' })
149
 * @returns Content with resolved aliases
150
 */
151
function resolve_aliases(input: string, file: string, content: string, aliases: Record<string, string>): string;
152

153
/**
154
 * Strip lang/type attributes from Svelte script and style tags
155
 * @param content - Svelte component content
156
 * @returns Content with stripped attributes
157
 */
158
function strip_lang_tags(content: string): string;
159

160
/**
161
 * Write file with directory creation
162
 * @param file - File path to write
163
 * @param contents - File contents
164
 */
165
function write(file: string, contents: string | Buffer): void;
166

167
/**
168
 * Scan directory for files matching extensions
169
 * @param input - Directory to scan
170
 * @param extensions - File extensions to include
171
 * @returns Array of analyzed file objects
172
 */
173
function scan(input: string, extensions: string[]): File[];
174

175
/**
176
 * Analyze file type and determine processing requirements
177
 * @param file - File path to analyze
178
 * @param extensions - Svelte file extensions
179
 * @returns File analysis object
180
 */
181
function analyze(file: string, extensions: string[]): File;
182
```
183

184
**Usage Examples:**
185

186
```typescript
187
import { resolve_aliases, strip_lang_tags, write, scan, analyze } from "@sveltejs/package/src/utils.js";
188

189
// Resolve $lib aliases in import statements
190
const resolvedContent = resolve_aliases(
191
  'src/lib',
192
  'components/Button.svelte',
193
  'import { utils } from "$lib/utils";',
194
  { '$lib': 'src/lib' }
195
);
196
// Result: 'import { utils } from "../utils";'
197

198
// Strip lang attributes from Svelte components
199
const stripped = strip_lang_tags('<script lang="ts">export let name: string;</script>');
200
// Result: '<script>export let name: string;</script>'
201

202
// Write file with automatic directory creation
203
write('dist/components/Button.js', 'export default Button;');
204

205
// Scan directory for Svelte files
206
const files = scan('src/lib', ['.svelte']);
207
// Result: [{ name: 'Button.svelte', dest: 'Button.svelte', base: 'Button', is_svelte: true }]
208

209
// Analyze individual file
210
const analysis = analyze('components/Button.svelte', ['.svelte']);
211
// Result: { name: 'components/Button.svelte', dest: 'components/Button.svelte', base: 'components/Button', is_svelte: true }
212
```
213

214
## Types
215

216
```typescript { .api }
217
interface Options {
218
  cwd: string;
219
  input: string;
220
  output: string;
221
  preserve_output: boolean;
222
  types: boolean;
223
  tsconfig?: string;
224
  config: Config;
225
}
226

227
interface Config {
228
  extensions?: string[];
229
  kit?: {
230
    alias?: Record<string, string>;
231
    files?: {
232
      lib?: string;
233
    };
234
    outDir?: string;
235
  };
236
  preprocess?: PreprocessorGroup;
237
}
238

239
interface File {
240
  name: string;
241
  dest: string;
242
  base: string;
243
  is_svelte: boolean;
244
}
245
```