@rsvelte/vite-plugin-svelte-native 0.1.0 → 0.1.1

package/README.md

@@ -1,23 +1,84 @@
-# @rsvelte/vite-plugin-svelte
+# @rsvelte/vite-plugin-svelte-native
 
-Workspace package and changesets version anchor for the Vite plugin that delegates to the rsvelte compiler.
+Native (N-API) bindings to the [rsvelte](https://github.com/baseballyama/rsvelte) Svelte 5 compiler, packaged for Node.js. Exposes the same `compile` / `compileModule` / `preprocess` / `hmrDiff` / `resolveId` surface as the official [`svelte/compiler`](https://svelte.dev/docs/svelte-compiler), plus a few low-overhead extras for tooling authors.
 
-## Status
+> **⚠️ Most users should not depend on this directly.** It's the engine that powers [`@rsvelte/vite-plugin-svelte`](https://github.com/baseballyama/vite-plugin-svelte/tree/rsvelte) — if you want to build a SvelteKit / Vite app with the Rust compiler, use that fork instead. Depend on this package if you're writing a build tool, language server, batch compiler, or any other Node.js program that needs to compile `.svelte` files at maximum speed.
 
-`private: true` until distribution is decided. The Rust side already exposes the napi bindings the plugin will use (`compile`, `preprocess`, `hmrDiff`, `resolveId` in `src/napi.rs`; helpers in `src/vps/`).
+## Install
 
-The plan in `docs/ecosystem-implementation-plan.md` (Wave 3) splits this into two npm packages:
+```bash
+npm install @rsvelte/vite-plugin-svelte-native
+# pnpm add @rsvelte/vite-plugin-svelte-native
+# yarn add @rsvelte/vite-plugin-svelte-native
+```
 
-- `@rsvelte/vite-plugin-svelte` (this directory) — the JS-side Vite plugin façade. Maintains the same public API as `@sveltejs/vite-plugin-svelte`, loads the native module, and translates Vite hooks into NAPI calls.
-- `@rsvelte/vite-plugin-svelte-native` — the napi-rs prebuilt-binary package set (one per platform triple), produced by a matrix build.
+The package ships a loader that resolves the right prebuilt `.node` binary for your platform via `optionalDependencies`. Supported targets:
 
-To go live:
+| OS | Architecture |
+|---|---|
+| macOS | arm64, x64 |
+| Linux | x64 (glibc), arm64 (glibc) |
+| Windows | x64 (MSVC) |
 
-1. Add the napi-rs platform matrix build to CI (target the rsvelte crate with `--features napi`).
-2. Create the `@rsvelte/vite-plugin-svelte-native` workspace package and its per-triple siblings.
-3. Add the JS entrypoint here that imports from `@rsvelte/vite-plugin-svelte-native`.
-4. Flip `private` to `false` on both packages.
+If your platform isn't listed, please [open an issue](https://github.com/baseballyama/rsvelte/issues).
 
-## Release flow
+## Quick start
 
-Versioning is handled by the same changesets pipeline as `@rsvelte/compiler`. See `.github/workflows/release.yml`. While this package is `private`, `changeset version` still updates its `version` and `CHANGELOG.md`, but `changeset publish` skips it.
+```js
+const { compile, compileModule, preprocess, VERSION } = require('@rsvelte/vite-plugin-svelte-native');
+
+// Component
+const result = compile('<h1>Hello {name}!</h1>', {
+  filename: 'App.svelte',
+  generate: 'client', // 'client' | 'server' | false
+});
+console.log(result.js.code);
+console.log(result.css?.code);
+
+// Module (.svelte.js / .svelte.ts)
+const mod = compileModule('export const count = $state(0);', {
+  filename: 'counter.svelte.js',
+});
+
+// Pre-process pipeline (markup / script / style)
+const pre = await preprocess(source, [/* PreprocessorGroup[] */], {
+  filename: 'App.svelte',
+});
+
+console.log(VERSION); // upstream Svelte version this binding targets
+```
+
+The shape of `CompileOptions`, `CompileResult`, `Warning`, `PreprocessorGroup`, etc. matches the upstream `svelte/compiler` types. See [`index.d.ts`](./index.d.ts) for the complete surface.
+
+## Why use this over `svelte/compiler`?
+
+- **Faster.** ~2× single-threaded vs the JS compiler on real corpora; ~15× with `compileBatch` across rayon worker threads.
+- **Drop-in.** Same options, same output shape — wire it into an existing build tool with minimal changes.
+- **Zero-overhead batching.** `compileBatch([...inputs])` compiles N files in parallel across rayon workers and crosses the N-API boundary exactly once.
+- **Async-friendly.** `compileAsync` / `compileBatchAsync` run on libuv worker threads — the JS event loop stays free.
+
+## Performance tips for tool authors
+
+This package exposes several levels of compile entry points; pick based on how your tool consumes the result:
+
+| Entry point | When to use |
+|---|---|
+| `compile(source, options)` | Default. Returns the upstream `CompileResult` shape; lazy-decodes the underlying envelope so heavy strings (generated code, source map JSON) are read only when accessed. |
+| `compileAsync(source, options)` | Same shape, runs on a libuv worker thread. Use inside Vite middleware, SSR pre-render, or anywhere you don't want to block the event loop. |
+| `compileBatch([{source, options}, …])` | Compile many files in one N-API call. Per-file failures surface as `Error` instances at the corresponding slot — they don't abort the batch. |
+| `compileBatchAsync([...])` | Same, async / off-thread. |
+| `compileEnvelope(source, options)` | Returns a single `Buffer` containing the raw envelope. Useful for `postMessage` across worker threads with `transfer:` — no copy. Pair with `decodeEnvelope(buf)` on the receiving side. |
+| `compileEnvelopeZeroCopy(...)` | Same as `compileEnvelope` but the returned `Buffer` is a view into `bumpalo` arena memory — skips Rust's `Vec` allocation. Faster, but with subtle GC / detach semantics. |
+| `compileBuffers(...)` | Returns `js.code` / `js.map` / `css.code` / `css.map` as raw `Buffer`s. Skip when you can use `compile()` — kept as an escape hatch. |
+| `compileLegacy(...)` | The old JSON-on-the-boundary path. Kept for parity tests; production callers should not use it. |
+
+For Svelte source-to-TSX conversion use the bundled `svelte2tsx(source, options)`; for HMR-update diffs use `hmrDiff(prev, curr)`. See [`index.d.ts`](./index.d.ts) for full type signatures.
+
+## Compatibility
+
+- **3,341 / 3,341** in-scope tests from the official Svelte 5 compiler test suite pass.
+- `VERSION` tracks the upstream Svelte version (currently `5.51.3`) — it's the *Svelte* compatibility line, not the rsvelte release version.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsvelte/vite-plugin-svelte-native",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "NAPI bindings to the rsvelte compiler — used by the @rsvelte vite-plugin-svelte shim",
   "license": "MIT",
   "repository": {
@@ -27,11 +27,11 @@
     "index.d.ts"
   ],
   "optionalDependencies": {
-    "@rsvelte/vite-plugin-svelte-native-darwin-arm64": "^0.1.0",
-    "@rsvelte/vite-plugin-svelte-native-linux-x64-gnu": "^0.1.0",
-    "@rsvelte/vite-plugin-svelte-native-linux-arm64-gnu": "^0.1.0",
-    "@rsvelte/vite-plugin-svelte-native-darwin-x64": "^0.1.0",
-    "@rsvelte/vite-plugin-svelte-native-win32-x64-msvc": "^0.1.0"
+    "@rsvelte/vite-plugin-svelte-native-darwin-arm64": "^0.1.1",
+    "@rsvelte/vite-plugin-svelte-native-darwin-x64": "^0.1.1",
+    "@rsvelte/vite-plugin-svelte-native-linux-arm64-gnu": "^0.1.1",
+    "@rsvelte/vite-plugin-svelte-native-linux-x64-gnu": "^0.1.1",
+    "@rsvelte/vite-plugin-svelte-native-win32-x64-msvc": "^0.1.1"
   },
   "publishConfig": {
     "access": "public"