Package Validation

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

Capabilities

Create Validator Function

Creates a validator instance for analyzing and validating package structure.

/**
 * Create validator for package analysis and validation
 * @param options - Build options containing configuration
 * @returns ValidatorResult with analysis and validation functions
 */
function create_validator(options: Options): ValidatorResult;

interface ValidatorResult {
  /** Analyze processed code for validation */
  analyse_code(name: string, code: string): void;
  /** Run validation checks on the package */
  validate(): void;
}

Usage Examples:

import { create_validator } from "@sveltejs/package/src/validate.js";
import { load_config } from "@sveltejs/package/src/config.js";

// Create validator
const config = await load_config();
const { analyse_code, validate } = create_validator({
  cwd: process.cwd(),
  input: "src/lib",
  output: "dist", 
  preserve_output: false,
  types: true,
  config
});

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

// Run validation
validate(); // Throws errors if validation fails

Validation Checks

Package.json Exports Validation

The validator checks package.json exports field compliance:

Required Exports Field

{
  "exports": {
    ".": {
      "svelte": "./dist/index.js",
      "import": "./dist/index.js",
      "default": "./dist/index.js"
    }
  }
}

Validation Rules:

• exports field must be present
• Root export (".") must be defined for packages with a svelte field
• Svelte condition must be present when using Svelte files

Svelte Field Alignment

When both svelte field and exports are present:

{
  "svelte": "./dist/index.js",
  "exports": {
    ".": {
      "svelte": "./dist/index.js",
      "import": "./dist/index.js"
    }
  }
}

Validation Rules:

• svelte field must match an export path in root export
• Consistent file resolution between svelte field and exports
• Export conditions must include svelte when using Svelte components

Export Conditions

Supported export conditions:

• svelte - Svelte component entry point
• import - ES module entry point
• require - CommonJS entry point
• default - Fallback entry point
• types - TypeScript declaration entry point

Code Analysis

The validator analyzes processed code for:

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

Specific Checks:

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

Warning Messages

Environment Variable Usage

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

SvelteKit Environment Import

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). 
Consider using packages like `esm-env` instead which provide cross-bundler-compatible environment variables.

Missing SvelteKit Dependency

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

Missing Svelte Dependency

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`. 
Add it to your `dependencies` or `peerDependencies`.

Error Messages

Missing Exports Field

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

Missing Svelte Condition

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

Misaligned Svelte Field

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

Missing Root Export

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

Validation Process

Analysis Phase

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

Validation Phase

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

Integration with Build System

The validator integrates with the build process:

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

Watch Mode Integration

In watch mode:

• Validator is recreated for each build cycle
• Code analysis is updated incrementally
• Validation runs after each complete rebuild
• Errors are reported but don't stop the watcher

Advanced Validation

Export Pattern Matching

The validator uses regex patterns to match export paths:

// Converts export patterns to regex for validation
// "./dist/*.js" becomes /^\.\/dist\/.*\.js$/
function export_to_regex(exportPath: string): RegExp;

Conditional Export Traversal

Recursively traverses export conditions to extract:

• All export paths
• All condition names
• Nested export structures

Configuration Impact

Validation behavior changes based on configuration:

• Svelte Files: Requires svelte export condition
• TypeScript: Validates .d.ts file generation
• Custom Extensions: Validates custom file type handling
• Preprocessing: Accounts for preprocessed output

Types

interface ValidatorResult {
  analyse_code(name: string, code: string): void;
  validate(): void;
}

interface Options {
  cwd: string;
  input: string;
  output: string;
  preserve_output: boolean;
  types: boolean;
  tsconfig?: string;
  config: Config;
}