0
# @sveltejs/package
1

2
@sveltejs/package is a specialized build tool for creating Svelte component libraries and packages. It automates the complex packaging process by preprocessing Svelte components, transpiling TypeScript files to JavaScript, generating comprehensive type definitions (.d.ts files), and creating a properly structured dist directory with all necessary library files.
3

4
## Package Information
5

6
- **Package Name**: @sveltejs/package
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install -D @sveltejs/package`
10

11
## Core Imports
12

13
**Important**: This package is primarily a CLI tool (`svelte-package` command). The package.json exports field only includes `"./package.json"` - no programmatic APIs are officially exported.
14

15
For programmatic usage, you must import directly from source files:
16

17
```typescript
18
// Core build functions
19
import { build, watch } from "@sveltejs/package/src/index.js";
20

21
// Configuration utilities  
22
import { load_config, load_pkg_json } from "@sveltejs/package/src/config.js";
23

24
// File system utilities
25
import { mkdirp, rimraf, copy, walk, posixify } from "@sveltejs/package/src/filesystem.js";
26

27
// TypeScript processing
28
import { emit_dts, transpile_ts } from "@sveltejs/package/src/typescript.js";
29

30
// Validation system
31
import { create_validator } from "@sveltejs/package/src/validate.js";
32

33
// Build utilities
34
import { resolve_aliases, strip_lang_tags, write, scan, analyze } from "@sveltejs/package/src/utils.js";
35
```
36

37
**Note**: These direct imports access internal implementation files that are not part of the public API. They may change between versions without notice.
38

39
## Basic Usage
40

41
### CLI Usage
42

43
```bash
44
# Basic package build
45
npx svelte-package
46

47
# Build with custom input and output directories
48
npx svelte-package -i src/lib -o dist
49

50
# Build without TypeScript declarations
51
npx svelte-package --types false
52

53
# Watch mode for development
54
npx svelte-package --watch
55
```
56

57
### Programmatic Usage
58

59
```typescript
60
import { build } from "@sveltejs/package/src/index.js";
61
import { load_config } from "@sveltejs/package/src/config.js";
62

63
const config = await load_config();
64

65
await build({
66
  cwd: process.cwd(),
67
  input: "src/lib",
68
  output: "dist",
69
  preserve_output: false,
70
  types: true,
71
  config
72
});
73
```
74

75
## Architecture
76

77
@sveltejs/package is built around several key components:
78

79
- **CLI Interface**: Command-line tool with sade for parsing arguments and configuration
80
- **Build System**: Core build and watch functions for processing source files
81
- **File Processing Pipeline**: Multi-stage processing for Svelte, TypeScript, and other files
82
- **TypeScript Integration**: Transpilation and declaration file generation
83
- **Configuration System**: Svelte config loading and validation
84
- **Validation Engine**: Package.json exports validation and compliance checking
85

86
## Capabilities
87

88
### Build System
89

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

92
```typescript { .api }
93
function build(options: Options): Promise<void>;
94

95
function watch(options: Options): Promise<WatchResult>;
96

97
interface WatchResult {
98
  watcher: chokidar.FSWatcher;
99
  ready: Promise<void>;
100
  settled(): Promise<void>;
101
}
102
```
103

104
[Build System](./build-system.md)
105

106
### Configuration Management
107

108
Configuration loading and validation for Svelte projects with support for multiple config file formats.
109

110
```typescript { .api }
111
function load_config(options?: { cwd?: string }): Promise<Config>;
112

113
function load_pkg_json(cwd?: string): Record<string, any>;
114

115
interface Config {
116
  extensions?: string[];
117
  kit?: {
118
    alias?: Record<string, string>;
119
    files?: {
120
      lib?: string;
121
    };
122
    outDir?: string;
123
  };
124
  preprocess?: PreprocessorGroup;
125
}
126
```
127

128
[Configuration Management](./configuration.md)
129

130
### File System Utilities
131

132
File system operations including directory creation, recursive deletion, and file copying with cross-platform path handling.
133

134
```typescript { .api }
135
function mkdirp(dir: string): void;
136

137
function rimraf(path: string): void;
138

139
function copy(source: string, target: string, opts?: CopyOptions): void;
140

141
function walk(cwd: string, dirs?: boolean): string[];
142

143
function posixify(str: string): string;
144
```
145

146
[File System Utilities](./filesystem.md)
147

148
### TypeScript Processing
149

150
TypeScript compilation and declaration file generation with support for custom tsconfig files and path alias resolution.
151

152
```typescript { .api }
153
function emit_dts(
154
  input: string,
155
  output: string,
156
  final_output: string,
157
  cwd: string,
158
  alias: Record<string, string>,
159
  files: File[],
160
  tsconfig?: string
161
): Promise<void>;
162

163
function transpile_ts(
164
  tsconfig: string | undefined,
165
  filename: string,
166
  source: string
167
): Promise<string>;
168
```
169

170
[TypeScript Processing](./typescript.md)
171

172
### Package Validation
173

174
Validation system for package.json exports fields and Svelte-specific configuration compliance.
175

176
```typescript { .api }
177
function create_validator(options: Options): ValidatorResult;
178

179
interface ValidatorResult {
180
  analyse_code(name: string, code: string): void;
181
  validate(): void;
182
}
183
```
184

185
[Package Validation](./validation.md)
186

187
## Types
188

189
```typescript { .api }
190
import { PreprocessorGroup } from 'svelte/types/compiler/preprocess';
191
import { FSWatcher } from 'chokidar';
192

193
interface Options {
194
  cwd: string;
195
  input: string;
196
  output: string;
197
  preserve_output: boolean;
198
  types: boolean;
199
  tsconfig?: string;
200
  config: Config;
201
}
202

203
interface File {
204
  name: string;
205
  dest: string;
206
  base: string;
207
  is_svelte: boolean;
208
}
209

210
interface Config {
211
  extensions?: string[];
212
  kit?: {
213
    alias?: Record<string, string>;
214
    files?: {
215
      lib?: string;
216
    };
217
    outDir?: string;
218
  };
219
  preprocess?: PreprocessorGroup;
220
}
221

222
interface ValidatedConfig {
223
  extensions: string[];
224
  kit?: any;
225
  preprocess?: any;
226
}
227

228
interface WatchResult {
229
  watcher: FSWatcher;
230
  ready: Promise<void>;
231
  settled(): Promise<void>;
232
}
233

234
interface ValidatorResult {
235
  analyse_code(name: string, code: string): void;
236
  validate(): void;
237
}
238

239
interface CopyOptions {
240
  filter?: (basename: string) => boolean;
241
  replace?: Record<string, string>;
242
}
243

244
type RecursiveRequired<T> = {
245
  [K in keyof T]-?: Extract<T[K], Function> extends never
246
    ? RecursiveRequired<T[K]>
247
    : T[K];
248
};
249

250
type Validator<T = any> = (input: T, keypath: string) => T;
251
```