0
# Package Validation
1

2
Validation system for package.json exports fields and Svelte-specific configuration compliance.
3

4
## Capabilities
5

6
### Create Validator Function
7

8
Creates a validator instance for analyzing and validating package structure.
9

10
```typescript { .api }
11
/**
12
 * Create validator for package analysis and validation
13
 * @param options - Build options containing configuration
14
 * @returns ValidatorResult with analysis and validation functions
15
 */
16
function create_validator(options: Options): ValidatorResult;
17

18
interface ValidatorResult {
19
  /** Analyze processed code for validation */
20
  analyse_code(name: string, code: string): void;
21
  /** Run validation checks on the package */
22
  validate(): void;
23
}
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import { create_validator } from "@sveltejs/package/src/validate.js";
30
import { load_config } from "@sveltejs/package/src/config.js";
31

32
// Create validator
33
const config = await load_config();
34
const { analyse_code, validate } = create_validator({
35
  cwd: process.cwd(),
36
  input: "src/lib",
37
  output: "dist", 
38
  preserve_output: false,
39
  types: true,
40
  config
41
});
42

43
// Analyze processed code
44
analyse_code("components/Button.svelte", svelteCode);
45
analyse_code("utils/helpers.js", jsCode);
46

47
// Run validation
48
validate(); // Throws errors if validation fails
49
```
50

51
## Validation Checks
52

53
### Package.json Exports Validation
54

55
The validator checks package.json exports field compliance:
56

57
#### Required Exports Field
58

59
```json
60
{
61
  "exports": {
62
    ".": {
63
      "svelte": "./dist/index.js",
64
      "import": "./dist/index.js",
65
      "default": "./dist/index.js"
66
    }
67
  }
68
}
69
```
70

71
**Validation Rules:**
72

73
- `exports` field must be present
74
- Root export (`"."`) must be defined for packages with a `svelte` field
75
- Svelte condition must be present when using Svelte files
76

77
#### Svelte Field Alignment  
78

79
When both `svelte` field and `exports` are present:
80

81
```json
82
{
83
  "svelte": "./dist/index.js",
84
  "exports": {
85
    ".": {
86
      "svelte": "./dist/index.js",
87
      "import": "./dist/index.js"
88
    }
89
  }
90
}
91
```
92

93
**Validation Rules:**
94

95
- `svelte` field must match an export path in root export
96
- Consistent file resolution between `svelte` field and exports
97
- Export conditions must include `svelte` when using Svelte components
98

99
#### Export Conditions
100

101
Supported export conditions:
102

103
- `svelte` - Svelte component entry point
104
- `import` - ES module entry point  
105
- `require` - CommonJS entry point
106
- `default` - Fallback entry point
107
- `types` - TypeScript declaration entry point
108

109
### Code Analysis
110

111
The validator analyzes processed code for:
112

113
- **SvelteKit Imports**: Detects usage of `$app/*` imports and validates dependencies
114
- **Svelte Dependencies**: Checks for Svelte component usage and proper peer dependencies
115
- **Environment Variables**: Detects `import.meta.env` usage (warns about bundler compatibility)
116
- **File Types**: Tracks which files are Svelte components vs regular JS/TS
117

118
**Specific Checks:**
119

120
- `$app/environment` imports should be avoided for non-SvelteKit compatibility
121
- `import.meta.env` usage is flagged as Vite-specific
122
- SvelteKit imports require `@sveltejs/kit` as a dependency
123
- Svelte files require `svelte` as a peer dependency
124

125
## Warning Messages
126

127
### Environment Variable Usage
128

129
```
130
Avoid usage of `import.meta.env` in your code. It only works in apps bundled with Vite. 
131
Consider using packages like `esm-env` instead which works with all bundlers or without bundling.
132
```
133

134
### SvelteKit Environment Import
135

136
```
137
Avoid usage of `$app/environment` in your code, if you want the library to work for people not using SvelteKit (only regular Svelte, for example). 
138
Consider using packages like `esm-env` instead which provide cross-bundler-compatible environment variables.
139
```
140

141
### Missing SvelteKit Dependency
142

143
```
144
You are using SvelteKit-specific imports in your code, but you have not declared a dependency on `@sveltejs/kit` in your `package.json`. 
145
Add it to your `dependencies` or `peerDependencies`.
146
```
147

148
### Missing Svelte Dependency
149

150
```
151
You are using Svelte components or Svelte-specific imports in your code, but you have not declared a dependency on `svelte` in your `package.json`. 
152
Add it to your `dependencies` or `peerDependencies`.
153
```
154

155
## Error Messages
156

157
### Missing Exports Field
158

159
```
160
No `exports` field found in `package.json`, please provide one. 
161
See https://svelte.dev/docs/kit/packaging#anatomy-of-a-package-json-exports for more info
162
```
163

164
### Missing Svelte Condition
165

166
```
167
You are using Svelte files, but did not declare a `svelte` condition in one of your `exports` in your `package.json`. 
168
Add a `svelte` condition to your `exports` to ensure that your package is recognized as Svelte package by tooling.
169
```
170

171
### Misaligned Svelte Field
172

173
```
174
The `svelte` field in your `package.json` does not match any export in your root `exports`. 
175
Please align them so that bundlers will resolve consistently to the same file.
176
```
177

178
### Missing Root Export
179

180
```
181
You have a `svelte` field in your `package.json`, but no root export in your `exports`. 
182
Please align them so that bundlers will resolve consistently to the same file.
183
```
184

185
## Validation Process
186

187
### Analysis Phase
188

189
1. **Code Collection**: Collect all processed source code
190
2. **Pattern Detection**: Detect Svelte components and import patterns
191
3. **Dependency Analysis**: Analyze import/export relationships
192
4. **Type Usage**: Track TypeScript usage patterns
193

194
### Validation Phase
195

196
1. **Package.json Loading**: Load and parse package.json
197
2. **Export Structure**: Validate exports field structure
198
3. **Condition Checks**: Verify required export conditions
199
4. **Field Alignment**: Cross-check svelte field with exports
200
5. **Error Reporting**: Generate detailed error messages
201

202
## Integration with Build System
203

204
The validator integrates with the build process:
205

206
1. **Validator Creation**: Created at build start with options
207
2. **Code Analysis**: Called for each processed file
208
3. **Final Validation**: Run after all files are processed
209
4. **Error Handling**: Validation errors stop the build
210

211
### Watch Mode Integration
212

213
In watch mode:
214

215
- Validator is recreated for each build cycle
216
- Code analysis is updated incrementally
217
- Validation runs after each complete rebuild
218
- Errors are reported but don't stop the watcher
219

220
## Advanced Validation
221

222
### Export Pattern Matching
223

224
The validator uses regex patterns to match export paths:
225

226
```typescript
227
// Converts export patterns to regex for validation
228
// "./dist/*.js" becomes /^\.\/dist\/.*\.js$/
229
function export_to_regex(exportPath: string): RegExp;
230
```
231

232
### Conditional Export Traversal
233

234
Recursively traverses export conditions to extract:
235

236
- All export paths
237
- All condition names
238
- Nested export structures
239

240
## Configuration Impact
241

242
Validation behavior changes based on configuration:
243

244
- **Svelte Files**: Requires `svelte` export condition
245
- **TypeScript**: Validates .d.ts file generation
246
- **Custom Extensions**: Validates custom file type handling
247
- **Preprocessing**: Accounts for preprocessed output
248

249
## Types
250

251
```typescript { .api }
252
interface ValidatorResult {
253
  analyse_code(name: string, code: string): void;
254
  validate(): void;
255
}
256

257
interface Options {
258
  cwd: string;
259
  input: string;
260
  output: string;
261
  preserve_output: boolean;
262
  types: boolean;
263
  tsconfig?: string;
264
  config: Config;
265
}
266
```