Installation

Quick Setup

The fastest way to start is with the CLI — it scaffolds a complete project with WASM, CORS headers, and a working KaspaStatus component, all pre-configured:

npx vue-kaspa-cli

You'll be prompted for a project name and your framework of choice (Vue 3 or Nuxt 4):

  vue-kaspa-cli — scaffold a Kaspa-connected Vue/Nuxt app

? Project name: kaspa-app
? Framework: Vue

Then:

cd kaspa-app
npm install
npm run dev

Manual setup

Adding vue-kaspa to an existing project? Continue with the steps below.

Prerequisites

• Node.js 18+
• A bundler with WASM support — Vite is recommended

Install the package

sh

$npm install vue-kaspa @vue-kaspa/kaspa-wasm

Both vue-kaspa and @vue-kaspa/kaspa-wasm are required. @vue-kaspa/kaspa-wasm provides the underlying WASM bindings; vue-kaspa wraps them with Vue reactivity.

Vite WASM configuration

@vue-kaspa/kaspa-wasm uses WebAssembly instantiation. Add vite-plugin-wasm to your Vite config:

sh

$npm install -D vite-plugin-wasm

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import wasm from 'vite-plugin-wasm'

export default defineConfig({
  plugins: [vue(), wasm()],

  // Required for SharedArrayBuffer / WASM threading
  server: {
    headers: {
      'Cross-Origin-Embedder-Policy': 'credentialless',
      'Cross-Origin-Opener-Policy': 'same-origin',
    },
  },

  optimizeDeps: {
    exclude: ['@vue-kaspa/kaspa-wasm'],
  },
})

CORS headers in development

The Cross-Origin-Embedder-Policy and Cross-Origin-Opener-Policy headers are required for SharedArrayBuffer support used internally by @vue-kaspa/kaspa-wasm. Without them, WASM initialization will fail in the browser.

CORS headers in production

The server.headers config only applies to the Vite dev server. For production deployments you must set these headers at the hosting layer.

Vercel — create a vercel.json at the project root:

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "Cross-Origin-Embedder-Policy", "value": "credentialless" },
        { "key": "Cross-Origin-Opener-Policy", "value": "same-origin" }
      ]
    }
  ]
}

Other hosts (Netlify, Cloudflare Pages, etc.) have equivalent _headers file or dashboard settings.

TypeScript configuration

Ensure your tsconfig.json targets ES2020 or later (required for BigInt):

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM"],
    "moduleResolution": "bundler"
  }
}

SSR / Nuxt

The Nuxt module handles all WASM/SSR configuration automatically — no manual Vite config needed. This includes vite-plugin-wasm, COOP/COEP headers (dev and production), optimizeDeps.exclude, and SSR externals. Composables are auto-imported.

For custom SSR setups (non-Nuxt), exclude @vue-kaspa/kaspa-wasm from the server bundle:

// vite.config.ts (SSR)
export default defineConfig({
  ssr: {
    external: ['@vue-kaspa/kaspa-wasm'],
  },
})