@vue-solana/core

vue-solana

Vue and Nuxt libraries for building Solana applications.

Vue Solana provides RPC reads, account reads, balance reads, browser extension wallets, Android mobile wallets, iOS browser wallets, message signing, and transaction helpers for Vue and Nuxt apps.

Packages

• @vue-solana/core: framework-agnostic Solana configuration, RPC, and wallet primitives.
• @vue-solana/vue: Vue plugin and composables.
• @vue-solana/nuxt: Nuxt module wrapping the Vue package with auto-imported composables.

Which Package Should I Use?

Use @vue-solana/core directly if you only need Solana APIs such as createSolanaClient, Address, and transactions plus shared Vue Solana helpers.

Use @vue-solana/core if you want shared Solana config, cluster endpoint defaults, wallet types, and transaction helpers without Vue.

Use @vue-solana/vue in Vue apps.

Use @vue-solana/nuxt in Nuxt apps.

@vue-solana/core builds on top of @solana/kit and re-exports all of @solana/kit from its kit subpaths, so apps can use one Vue Solana package entry point and never install @solana/kit themselves.

Since v3.0.0 every @vue-solana/* package is ESM only. There is no require export condition and no top-level main, so require("@vue-solana/vue") fails with No "exports" main defined. Vite and Nuxt apps are unaffected; pin to ^2 if you must stay on CommonJS. See the Kit Migration guide for the v1 → v2 and v2 → v3 maps.

Clusters

Supported clusters:

• mainnet: Solana's production cluster. This is Solana's official mainnet cluster name. Use it for production apps and real SOL. The legacy mainnet-beta spelling is still accepted and redirects to the same endpoint.
• devnet: developer network with free test SOL.
• testnet: validator and protocol testing network.
• localnet: local validator, usually http://127.0.0.1:8899.

Use mainnet in Vue Solana code. This is Solana's official mainnet cluster name. The legacy mainnet-beta spelling is still accepted and redirects to the same endpoint. See Solana Concepts For Vue Developers for more background.

Client-Sent Transactions

createSolanaClient() composes the official @solana/kit-plugin-rpc stack by default: solanaRpc(), rpcTransactionPlanner(), and rpcTransactionPlanSendingExecutor(). The old custom fallback sender is not used. Vue's useSendTransaction() and useSendTransactions() composables use this official sender, wait for confirmed commitment, and expose the submitted signature in the result without a wallet popup.

Direct core/Vue clients accept payer as a Kit TransactionSigner or payerSecretKey as a base64 64-byte Ed25519 keypair. Nuxt's ModuleOptions intentionally omits both and does not forward them through public runtime config. Never put a raw secret or payerSecretKey in Nuxt public runtime config; use a client-only ephemeral signer installed with solana.clientPlugin: false. A client-sent transaction always requires a payer on the client, so a message carrying its own embedded signer is not a substitute. Keep funded production keys on a trusted server or relayer.

Install

For Vue:

pnpm add @vue-solana/vue

For Nuxt:

npx nuxt module add @vue-solana/nuxt

Wallet Support

Current wallet support:

• Browser extension wallets through Wallet Standard packages: @wallet-standard/app, @wallet-standard/base, @wallet-standard/features, and Solana signing features from @solana/wallet-standard-features.
• Android native mobile wallets through @solana-mobile/wallet-standard-mobile, which registers Solana Mobile Wallet Adapter as a Wallet Standard wallet on Android Chrome and Chrome PWAs.
• iOS browser wallets for Phantom, Solflare, and Backpack through wallet-specific universal links.
• Manual/custom wallet objects that implement the SolanaWallet interface.

Not supported yet, but planned:

• Desktop native app wallets. These require wallet-specific protocol links or future native Wallet Standard registration.
• A built-in wallet modal. Apps should build their own selection UI with useWallets().

All supported wallet sources use the same public flow: useWallets() for discovery and selection, then useWallet() for active wallet state, connect(), disconnect(), capability flags, and signing. Use useSignMessage() or Nuxt's useSolanaSignMessage() for wallet-auth message challenges when the active wallet reports canSignMessage.

Import Paths

Root package exports remain supported for compatibility. New code can use direct subpath exports for narrower imports:

import { createSolanaContext } from "@vue-solana/core/rpc";
import type { SolanaConfig } from "@vue-solana/core/types";
import { createSolanaClient } from "@vue-solana/vue/kit";
import { installSolanaBufferPolyfill } from "@vue-solana/vue/buffer-polyfill";
import { useAccountInfo } from "@vue-solana/vue/useAccountInfo";
import { useProgramAccounts } from "@vue-solana/vue/useProgramAccounts";
import { useRpc } from "@vue-solana/vue/useRpc";
import { useSignatureStatus } from "@vue-solana/vue/useSignatureStatus";
import { useSignMessage } from "@vue-solana/vue/useSignMessage";
import { useWallet } from "@vue-solana/vue/useWallet";

Vue apps can import Kit primitives from @vue-solana/vue/kit and the Buffer helper from @vue-solana/vue/buffer-polyfill without installing @vue-solana/core or buffer directly. Nuxt apps use the equivalent @vue-solana/nuxt/kit and @vue-solana/nuxt/buffer-polyfill subpaths. Direct @vue-solana/core/* imports remain supported for lower-level core usage.

The Nuxt module auto-imports composables from these direct Vue subpaths and keeps its runtime plugin client-only. Auto-imported composables are SSR-safe, but real RPC and wallet work should run after hydration.

Use useProgramAccounts() carefully on public RPC nodes. Prefer narrow filters, dataSlice, and dedicated RPC infrastructure for production account scans.

Documentation

The dedicated Nuxt Content docs app lives at apps/docs. It adapts the current knowledge bundle material into a navigable documentation site for the full Vue Solana ecosystem.

Live demo: vue-solana-docs.vercel.app/demo

Run it locally:

pnpm dev:docs

Docs app pages:

• Docs overview
• Getting Started
• Solana For Vue Developers
• Clusters
• Wallets
• @vue-solana/core
• @vue-solana/vue
• @vue-solana/nuxt
• Live demo
• Vue Vite example docs
• Nuxt example docs
• E2E Testing
• Troubleshooting

Root knowledge-bundle/ is kept as OKF-formatted reference material for AI agents:

• Knowledge Bundle Index
• Getting Started
• Solana Concepts For Vue Developers
• API Reference
• @vue-solana/core API
• @vue-solana/vue API
• @vue-solana/nuxt API
• Wallet Support
• Troubleshooting
• Agent Skill
• @vue-solana/core README
• @vue-solana/vue README
• @vue-solana/nuxt README

Plans live in the top-level plans/ directory:

• Roadmap
• React Parity Plan
• Native Wallet Plan
• Solana Pay QR Plan
• Archived plans: plans/archived/ (completed Kit migration, SPL tokens, standalone installs, v1 roadmap)

Agent Skill

This repository includes an installable Agent Skill for AI coding agents that support the Agent Skills format. The skill gives agents Vue Solana setup patterns, wallet flow guidance, Nuxt SSR caveats, transaction gotchas, and verification commands.

# Install all skills
npx skills add vue-solana/vue-solana

# Install the Vue Solana skill
npx skills add vue-solana/vue-solana --skill vue-solana

# List available skills
npx skills add vue-solana/vue-solana --list

# Install globally
npx skills add vue-solana/vue-solana --global

Skill source: skills/vue-solana/SKILL.md

More details: Agent Skill docs

Development

pnpm install
pnpm lint
pnpm format
pnpm test
pnpm typecheck
pnpm build:packages
pnpm smoke:standalone-installs
pnpm test:e2e
pnpm dev:docs

pnpm test:e2e builds both example apps and runs the Playwright suite against deterministic RPC, RPC-subscription (websocket), and mock-wallet fixtures. Use pnpm test:e2e:integration to run the suite against real devnet instead. See the E2E Testing guide for the mock surface.

pnpm install runs the root prepare script and installs the Husky Git hooks. If hooks are missing after changing package managers or reinstalling dependencies, run pnpm prepare from the repository root.

Pre-commit checks run through lint-staged and only lint/format staged files. Run pnpm lint, pnpm format, pnpm test, pnpm typecheck, and pnpm build:packages before opening larger pull requests.

Run pnpm smoke:standalone-installs before release-facing package changes. It builds and packs @vue-solana/core, @vue-solana/vue, and @vue-solana/nuxt, installs each tarball into a fresh temporary TypeScript consumer, and typechecks representative root, kit, and buffer-polyfill imports without workspace aliases or repo-local shims. Set KEEP_STANDALONE_SMOKE=1 to keep the temporary projects for debugging.

CI And Releases

GitHub Actions runs CI on pull requests and pushes to main:

pnpm lint
pnpm format
pnpm test
pnpm typecheck
pnpm build:packages

Package releases are managed with Changesets. For package-facing changes, add a changeset before opening a pull request:

pnpm changeset

Add a changeset for changes that affect published packages, including runtime behavior fixes, public API changes, package dependency changes that affect consumers, and package README/docs updates that should appear in published package metadata.

Do not add a changeset for repository-only changes such as CI updates, tests-only changes, formatting, linting, or root documentation that does not affect a published package.

When changes with pending changesets land on main, the release workflow opens or updates a version PR. Merging that version PR publishes changed packages to npm using npm Trusted Publishing with GitHub Actions OIDC.

Release flow:

1. Open a pull request with package changes and a changeset.
2. Merge the pull request into main after CI passes.
3. Wait for the Release workflow to open or update the chore: version packages PR.
4. Review and merge the version PR.
5. Confirm the next Release workflow run publishes the changed packages.

To verify a release, check GitHub Actions for the latest Release workflow run. The version PR run should create or update the release PR, and the version PR merge run should publish packages. You can also verify published versions on npm:

pnpm view @vue-solana/core version
pnpm view @vue-solana/vue version
pnpm view @vue-solana/nuxt version

Before publishing, configure a trusted publisher on npm for each published package:

• @vue-solana/core
• @vue-solana/vue
• @vue-solana/nuxt

Use these npm trusted publisher settings:

• Publisher: GitHub Actions
• Organization or user: vue-solana
• Repository: vue-solana
• Workflow filename: release.yml
• Allowed action: npm publish

The release workflow does not use a long-lived NPM_TOKEN secret.

Release candidates

To publish a pre-release from a branch instead of waiting for main, use Changesets pre-release mode. The version is bumped to a prerelease of the pending release (for example 4.0.0-rc.0) and published under its own npm dist-tag, so the latest tag keeps pointing at the last stable release.

The Taskfile.yml wraps the whole flow. It needs go-task on PATH (brew install go-task):

task rc:status     # show the current pre-release state, versions, and pending changesets
task rc:enter      # enter pre-release mode
task rc:bump       # next candidate number (4.0.0-rc.0 -> 4.0.0-rc.1)
task rc:verify     # dry-run: show exactly what would be published
task rc:publish    # publish to npm under the rc dist-tag
task rc:dispatch   # trigger the CI Release workflow for this branch and tag
task rc:exit       # leave pre-release mode, keeping the pending changeset
task rc:reset      # restore the branch to its pre-candidate state (versions, changelogs, pre.json)

The dist-tag is configurable per run: task rc:enter RC_TAG=next, or export RC_TAG.

The underlying commands, if you prefer to run them directly:

pnpm changeset pre enter rc     # writes .changeset/pre.json with the rc tag
pnpm version-packages            # core/vue/nuxt -> 4.0.0-rc.0, plus CHANGELOG entries
pnpm build:packages
pnpm changeset publish           # publishes under the "rc" dist-tag

Consumers install a release candidate with an explicit tag:

npm install @vue-solana/core@rc

Do not pass --tag to changeset publish while in pre mode; Changesets rejects it and takes the tag from .changeset/pre.json. Every release candidate needs its own version number, so bump again by adding a changeset and running pnpm version-packages again (4.0.0-rc.0 -> 4.0.0-rc.1). task rc:bump does that for you with a throwaway changeset.

Publish the release candidate from CI to use npm Trusted Publishing instead of a local token. Run the Release workflow manually (workflow_dispatch) on the release branch and set the tag input; the workflow verifies that every package version matches that tag and then publishes with that dist-tag:

# GitHub Actions -> Release -> Run workflow -> branch: release/v4.0.0 -> tag: rc
# or, from the branch: task rc:dispatch
npm view @vue-solana/core dist-tags

To return to normal releases, leave pre mode and version again:

pnpm changeset pre exit
pnpm version-packages            # -> 4.0.0

Pre-release commits live on the release branch only. Do not merge the prerelease versions into main: the stable release is versioned from the pending changesets on main. Use task rc:reset to put the branch back into that shape (versions at the last stable release, changeset still pending, no pre.json) before merging it, so the normal "chore: version packages" flow still publishes 4.0.0 to latest on its own.

Example Apps

Small usage snippets are included in the package docs for quick reference. For a complete runnable flow, use the example apps:

• Live demo: vue-solana-docs.vercel.app/demo
• Vue Vite example: examples/vue-vite
• Nuxt example: examples/nuxt
• Documentation app: apps/docs

Run them from the repository root:

pnpm dev:vue
pnpm dev:nuxt
pnpm dev:docs

Known Issues

@solana/web3-compat Removed in v2

v2.0.0 removed @solana/web3-compat from every package. The context no longer carries a connection, the legacy web3 subpaths are deleted, and the wallet exposes publicKey: Address (a branded string) instead of a PublicKey class.

v1.x packages (and the @solana/web3-compat packages they shipped) had broken TypeScript metadata and shipped temporary declaration shims. If you are still on v1.x, follow the Kit Migration guide and upgrade to v2.

The buffer polyfill (@vue-solana/core/buffer-polyfill) remains available for browser runtimes that lack a global Buffer, and is the only remaining declaration-shim path.