@elementary-swift/vite-plugin-swift-wasm

A Vite plugin for Swift WebAssembly integration.

Features

• add support for importing an executable target from a local SwiftPM package
• supports JavaScriptKit and BridgeJS through the swift package js plugin (?js)
• supports manual WebAssembly initialization with plain swift build (?init)
• automatically detects matching Swift SDK for WebAssembly and builds a reactor module
• watches changes of *.swift files and triggers instant rebuild and reload
• for release builds: optimizes binary using wasm-opt (must be installed separately)
• for release builds: adds <link rel="preload"> for the WebAssembly module to HTML pages that load it
• supports Embedded Swift build mode (via wasm-embedded Swift SDK)
• automatically links swiftUnicodeDataTables when using Embedded Swift

Installation

npm i -D @elementary-swift/vite-plugin-swift-wasm
# or
# pnpm i -D @elementary-swift/vite-plugin-swift-wasm

# TypeScript: Add @elementary-swift/vite-plugin-swift-wasm/client to types configuration

Requires Swift 6.2 or newer from swift.org and a matching Swift SDK for WebAssembly.

Usage

// vite.config.ts
import { defineConfig } from "vite";
import swiftWasm from "@elementary-swift/vite-plugin-swift-wasm";

export default defineConfig({
  plugins: [swiftWasm()],
});

JavaScriptKit / BridgeJS

The ?js mode runs swift package js and re-exports the generated module. The Swift package must have a dependency on JavaScriptKit, which provides the js package command.

// index.ts
import { init } from "virtual:swift-wasm?js&product=MyApp";

const wasmInstance = await init();

// product name can be omitted if only one executable target is in the package
// import { init } from "virtual:swift-wasm?js";

For runtimes that accept a precompiled WebAssembly.Module, such as worker environments, add the &module flag:

import { init } from "virtual:swift-wasm?js&module&product=Worker";

const wasmInstance = await init();

This imports the built WebAssembly file as Worker.wasm?module and passes it as options.module to the js generated initializer. The flag depends only on the bundler's ?module support and does not detect a specific runtime.

The module flag is supported only by ?js; ?init&module is invalid.

Manual WebAssembly initialization

The ?init mode runs a plain swift build and re-exports Vite's manual WebAssembly initialization function.

// index.ts
import myApp from "virtual:swift-wasm?init&product=MyApp";

const wasmInstance = myApp();

const wasmInstanceWithImports = myApp({ someImport, moreImports });

// product name can be omitted if there is only one executable target in the package
// import myApp from "virtual:swift-wasm?init";

Configuration

All options with their default values:

swiftWasm({
  // Path to the Swift package
  packagePath: ".",

  // SwiftPM scratch directory, relative to the package path
  scratchPath: ".build",

  // Additional arguments passed to the Swift build command
  // In ?js mode, these are passed to `swift package` after --swift-sdk.
  extraBuildArgs: [],

  // Options for the `swift package js` plugin (?js mode only)
  js: {
    // WASI runtime of the generated JavaScript: "browser-wasi-shim" or "uwasi"
    // (requires JavaScriptKit 0.59+ and the matching npm package; omitted uses JavaScriptKit's default)
    wasiRuntime: undefined,

    // Additional arguments passed to `swift package js`
    extraArgs: [],
  },

  // Use Embedded Swift variant (production builds only)
  // Produces smaller binaries with reduced runtime overhead
  useEmbeddedSDK: false,

  // Link Swift Unicode data tables when building with Embedded Swift
  // Only relevant when useEmbeddedSDK is true
  linkEmbeddedUnicodeDataTables: true,

  // Optimize the generated WebAssembly module with wasm-opt
  // (production builds only, including ?js mode)
  useWasmOpt: true,

  // Arguments to pass to wasm-opt
  wasmOptArgs: ["-Os", "--strip-debug"],

  // Add <link rel="preload"> for the WebAssembly module to HTML pages that
  // statically import it (production builds only)
  preloadWasm: true,
});

Publishing

pnpm version [patch | minor | major]
git push --follow-tags