npm package: @rsvelte/compiler
Description: A high-performance Rust implementation of the Svelte compiler - drop-in replacement
Author: baseballyama
Latest version: 0.2.0

# rsvelte

A high-performance Rust implementation of the Svelte compiler. Drop-in replacement for `svelte/compiler` with up to 100x performance improvement.

## Installation

```bash
npm install @rsvelte/compiler
```

## Usage

### Basic Usage

```js
import { compile, parse, VERSION } from '@rsvelte/compiler';

const result = compile('<h1>Hello {name}!</h1>', {
  filename: 'App.svelte',
  generate: 'client',
});

console.log(result.js.code);
```

### With Vite + vite-plugin-svelte

Use `resolve.alias` to replace the Svelte compiler:

```js
// vite.config.js
import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';

export default defineConfig({
  resolve: {
    alias: {
      'svelte/compiler': '@rsvelte/compiler',
    },
  },
  plugins: [svelte()],
});
```

## API

### `compile(source, options?)`

Compile a Svelte component to JavaScript.

```js
const result = compile(source, {
  dev: false,
  generate: 'client', // 'client' | 'server'
  filename: 'Component.svelte',
  css: 'external', // 'injected' | 'external'
  // ... see CompileOptions for all options
});

// result.js.code - Generated JavaScript
// result.js.map - Source map
// result.css?.code - Generated CSS (if css: 'external')
// result.css?.map - CSS source map
// result.warnings - Compiler warnings
// result.metadata.runes - Whether component uses runes
```

### `compileModule(source, options?)`

Compile a Svelte module (`.svelte.js` / `.svelte.ts`).

```js
const result = compileModule(source, {
  dev: false,
  generate: 'client',
  filename: 'utils.svelte.js',
});
```

### `parse(source, options?)`

Parse a Svelte component into an AST.

```js
const ast = parse('<h1>Hello</h1>', {
  modern: true, // Use modern AST format
});
```

### `preprocess(source, preprocessors, options?)`

Preprocess a Svelte component (async).

```js
const processed = await preprocess(source, [
  {
    markup({ content, filename }) {
      return { code: transformedContent };
    },
    script({ content, filename }) {
      return { code: transformedContent };
    },
    style({ content, filename }) {
      return { code: transformedContent };
    },
  },
], { filename: 'App.svelte' });
```

### `print(ast, options?)`

Print an AST back to source code.

```js
const ast = parse(source, { modern: true });
const { code } = print(ast);
```

### `parseCss(source)`

Parse CSS into an AST.

### `VERSION`

The compiler version string.

```js
import { VERSION } from '@rsvelte/compiler';
console.log(VERSION); // "0.1.0"
```

## Limitations

### Callback Options Not Supported

The following options accept JavaScript callback functions and are **not currently supported** in rsvelte. These options will be silently ignored, and the default behavior will be used instead:

| Option | Description | Default Behavior |
|--------|-------------|-----------------|
| `cssHash` | Custom function to generate CSS hash for scoping | Uses the built-in hash function (same algorithm as the official Svelte compiler default) |
| `warningFilter` | Function to filter compiler warnings | All warnings are included in the result |

**Why?** rsvelte is implemented in Rust and compiled to a native binary. JavaScript callback functions cannot be directly executed inside the Rust runtime. Supporting these would require crossing the Rust-JavaScript boundary for each invocation, which would negate the performance benefits.

**Workaround for `warningFilter`:** Filter warnings from the result after compilation:

```js
const result = compile(source, options);
const filteredWarnings = result.warnings.filter(
  (w) => w.code !== 'a11y-missing-attribute'
);
```

**Workaround for `cssHash`:** Currently no workaround. The default hash function is used. If you require a custom hash, please open an issue.

### Not Yet Implemented

| API | Status |
|-----|--------|
| `migrate()` | Not implemented - throws error |
| `walk()` | Deprecated in Svelte 5 - throws error directing to estree-walker |

## Platform Support

rsvelte ships native binaries for the following platforms:

| Platform | Architecture | Package |
|----------|-------------|---------|
| macOS | ARM64 (Apple Silicon) | `@rsvelte/binding-darwin-arm64` |
| macOS | x64 (Intel) | `@rsvelte/binding-darwin-x64` |
| Linux | x64 | `@rsvelte/binding-linux-x64-gnu` |
| Linux | ARM64 | `@rsvelte/binding-linux-arm64-gnu` |
| Windows | x64 | `@rsvelte/binding-win32-x64-msvc` |

Native binaries are installed automatically via `optionalDependencies`. If no native binary is available for your platform, an error will be thrown at runtime.

## Svelte Compatibility

rsvelte targets compatibility with **Svelte 5** (`svelte/compiler`). It passes 100% of the official Svelte compiler test suite (3028/3028 tests).

## License

MIT