@vue-solana/nuxt 0.6.2 → 0.6.4

package/README.md

@@ -1,6 +1,11 @@
 # @vue-solana/nuxt
 
-Nuxt module for Solana applications.
+[![npm version](https://img.shields.io/npm/v/@vue-solana/nuxt.svg)](https://www.npmjs.com/package/@vue-solana/nuxt)
+[![npm downloads](https://img.shields.io/npm/dt/@vue-solana/nuxt.svg)](https://www.npmjs.com/package/@vue-solana/nuxt)
+[![license](https://img.shields.io/npm/l/@vue-solana/nuxt.svg)](https://github.com/vue-solana/vue-solana/blob/main/LICENSE)
+[![docs](https://img.shields.io/badge/docs-vue--solana-blue)](https://vue-solana-docs.vercel.app/packages/nuxt)
+
+Nuxt module for Solana wallet, RPC, account, message signing, and transaction composables with auto-imports.
 
 Use this package in Nuxt apps that need the Vue Solana plugin installed automatically plus auto-imported composables for RPC, wallet state, message signing, and transactions.
 
@@ -14,15 +19,31 @@ New to Solana? Start with the official docs and the project concepts guide:
 - [Agent Skill](https://vue-solana-docs.vercel.app/agent-skill)
 - [Live demo](https://vue-solana-docs.vercel.app/demo)
 
+## Features
+
+- Installs the Vue Solana plugin automatically.
+- Auto-imports Solana RPC, wallet, account, balance, message signing, and transaction composables.
+- Uses direct Vue package subpaths to avoid pulling unrelated runtime code into Nuxt bundles.
+- Client-only runtime plugin with SSR-safe inert composable state before hydration.
+- Unified wallet discovery for browser extensions, Android Mobile Wallet Adapter, and supported iOS browser wallets.
+- Nuxt 3 and Nuxt 4 support.
+
+## Compatibility
+
+| Requirement   | Supported                                       |
+| ------------- | ----------------------------------------------- |
+| Nuxt          | `^3.0.0 \|\| ^4.0.0`                            |
+| TypeScript    | TypeScript 5.x recommended                      |
+| Solana client | Provided through `@vue-solana/core`             |
+| Clusters      | `mainnet-beta`, `devnet`, `testnet`, `localnet` |
+
 ## Install
 
 ```sh
-pnpm add @vue-solana/nuxt @vue-solana/vue @vue-solana/core @solana/web3-compat buffer
+npx nuxt module add @vue-solana/nuxt
 ```
 
-```sh
-npm install @vue-solana/nuxt @vue-solana/vue @vue-solana/core @solana/web3-compat buffer
-```
+This installs the package and adds `@vue-solana/nuxt` to the `modules` array in `nuxt.config.ts`.
 
 ## Module Setup
 
@@ -52,6 +73,17 @@ Supported clusters are `mainnet-beta`, `devnet`, `testnet`, and `localnet`. Use
 
 Nuxt module options are stored in public runtime config, so they must be JSON-serializable. Custom `wallet` adapter objects are intentionally excluded from Nuxt config; use the Vue plugin directly in client-only Vue code if you need to inject a custom wallet object.
 
+### Module Options
+
+| Option         | Type                                                    | Default                              | Description                                                                                   |
+| -------------- | ------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------- |
+| `cluster`      | `"mainnet-beta" \| "devnet" \| "testnet" \| "localnet"` | `"devnet"`                           | Solana cluster used when `endpoint` is omitted.                                               |
+| `endpoint`     | `string`                                                | Public endpoint for `cluster`        | HTTP RPC endpoint. Use a dedicated RPC provider for production apps.                          |
+| `wsEndpoint`   | `string`                                                | Derived from `endpoint`              | WebSocket RPC endpoint.                                                                       |
+| `commitment`   | Solana commitment                                       | Solana client default                | Default commitment for created connections.                                                   |
+| `autoConnect`  | `boolean`                                               | `false`                              | Reconnects only a previously selected discovered wallet identity when it is discovered again. |
+| `mobileWallet` | JSON-serializable mobile wallet options or `false`      | Enabled on supported Android clients | Configures or disables Android Mobile Wallet Adapter registration.                            |
+
 For development, use `devnet` and request free test SOL from the official faucet:
 
 ```txt
@@ -75,10 +107,30 @@ The module auto-imports these composables from direct `@vue-solana/vue/*` subpat
 - `useSolanaSignMessage()`
 - `useSolanaSignAndSendTransaction()`
 
+| Composable                           | Purpose                                                                          |
+| ------------------------------------ | -------------------------------------------------------------------------------- |
+| `useSolana()`                        | Full Solana context.                                                             |
+| `useSolanaRpc()`                     | Cluster, endpoint, connection status, latest blockhash, and `checkConnection()`. |
+| `useSolanaConnection()`              | Raw Solana `Connection`.                                                         |
+| `useSolanaAccountInfo()`             | Account info reads and optional subscriptions.                                   |
+| `useSolanaWallet()`                  | Active wallet state and connect/disconnect actions.                              |
+| `useSolanaWallets()`                 | Wallet discovery, selected wallet state, and selection actions.                  |
+| `useSolanaBalance()`                 | Lamport balance reads.                                                           |
+| `useSolanaProgramAccounts()`         | Program account scans with filters and `dataSlice`.                              |
+| `useSolanaTransactionConfirmation()` | Confirmation state for an already submitted signature.                           |
+| `useSolanaSignatureStatus()`         | Signature status reads with optional polling or websocket subscription.          |
+| `useSolanaSignMessage()`             | Wallet message signing.                                                          |
+| `useSolanaSignAndSendTransaction()`  | Wallet transaction signing, sending, and optional confirmation.                  |
+
 The runtime plugin is client-only. Auto-imported composables can be called during SSR and return inert state until hydration provides the real client context. Trigger RPC and wallet work from client lifecycle hooks or user actions.
 
 Android Mobile Wallet Adapter registration also runs only on the client. On Android Chrome and Chrome PWAs, `Mobile Wallet Adapter` can appear in the same `useSolanaWallets()` list as browser extension wallets. On iOS browsers, Phantom, Solflare, and Backpack can appear in the same list through wallet-specific universal links. Desktop native app wallet adapters are planned but not implemented yet.
 
+The package also exposes Solana helper subpaths for Nuxt apps that need transaction primitives or the browser Buffer polyfill without importing lower-level packages directly:
+
+- `@vue-solana/nuxt/web3`
+- `@vue-solana/nuxt/buffer-polyfill`
+
 ## Read RPC State
 
 ```vue
@@ -163,7 +215,7 @@ const { publicKey, connected, canSignMessage, connect, disconnect } = useSolanaW
 </template>
 ```
 
-Browser extension wallets are discovered through the Solana Wallet Standard. Android Mobile Wallet Adapter wallets are registered through `@solana-mobile/wallet-standard-mobile` on supported Android Chrome clients and exposed through the same wallet list. Wallet actions work after selecting a discovered wallet or configuring a custom `SolanaWallet`.
+Browser extension wallets are discovered through the Solana Wallet Standard. Android Mobile Wallet Adapter wallets are registered through `@solana-mobile/wallet-standard-mobile` on supported Android Chrome clients and exposed through the same wallet list. iOS Phantom, Solflare, and Backpack entries are exposed through wallet-specific universal links on iOS browsers. Wallet actions work after selecting a discovered wallet or configuring a custom `SolanaWallet`.
 
 Selected discovered wallets are persisted under `localStorage["vue-solana:selected-wallet"]` as non-sensitive identity metadata: `name`, and `platform`/`source` when available. On reload, Vue Solana restores the selected wallet if the same wallet is discovered again. Set `solana.autoConnect: true` to opt into calling `connect()` for that restored wallet; arbitrary installed wallets are never auto-connected. Calling `selectWallet(null)` or `setWallet(customWallet)` clears the stored selection.
 
@@ -216,37 +268,16 @@ npx skills add vue-solana/vue-solana --skill vue-solana
 
 Docs: [Vue Solana Agent Skill](https://vue-solana-docs.vercel.app/agent-skill)
 
-## Known TypeScript Issue
-
-`@solana/web3-compat@0.0.21` currently has broken TypeScript metadata. Runtime imports still use the real package, but TypeScript consumers may need a local declaration shim.
-
-If TypeScript cannot resolve `@solana/web3-compat`, add `types/web3-compat.d.ts` to your app:
-
-```ts
-declare module "@solana/web3-compat" {
-  export type {
-    AccountInfo,
-    Commitment,
-    RpcResponseAndContext,
-    SendOptions,
-    SignatureResult,
-    SignatureStatus,
-    TransactionSignature,
-  } from "@solana/web3.js";
-  export {
-    Connection,
-    Keypair,
-    PublicKey,
-    SystemProgram,
-    Transaction,
-    TransactionInstruction,
-    VersionedTransaction,
-  } from "@solana/web3.js";
-}
-```
+## Caveats
 
-Make sure your `tsconfig.json` includes `types/**/*.d.ts` or another pattern that includes the shim.
+- The runtime plugin is client-only. Auto-imported composables are SSR-safe, but real RPC and wallet work should run after hydration or in user actions.
+- Nuxt module options are stored in public runtime config, so they must be JSON-serializable.
+- Public Solana RPC endpoints are useful for development, but production apps should use dedicated RPC infrastructure.
+- Broad `useSolanaProgramAccounts()` scans can be expensive or blocked on public RPC nodes. Prefer narrow filters and `dataSlice`.
+- Use `mainnet-beta` for Solana mainnet. `mainnet` is intentionally not accepted as a cluster alias.
+- `@solana/web3-compat@0.0.21` currently has broken TypeScript package metadata. Runtime imports still use the real package, and current Vue Solana packages publish temporary declaration shims for documented imports. See [Troubleshooting](https://vue-solana-docs.vercel.app/troubleshooting) for details.
+- Desktop native app wallets are planned but not implemented yet.
 
 ## Status
 
-This package is early-stage. RPC, balance, browser extension wallet, Android mobile wallet, iOS browser wallet, message signing, and transaction composables are usable in Nuxt apps.
+This package provides RPC, balance, browser extension wallet, Android mobile wallet, iOS browser wallet, message signing, and transaction composables for Nuxt apps.

package/dist/module.cjs

@@ -42,7 +42,10 @@ const VITE_OPTIMIZE_DEPS = [
 const module$1 = kit.defineNuxtModule({
   meta: {
     name: "@vue-solana/nuxt",
-    configKey: "solana"
+    configKey: "solana",
+    compatibility: {
+      nuxt: "^3.0.0 || ^4.0.0"
+    }
   },
   defaults: {
     cluster: "devnet",

package/dist/module.mjs

@@ -39,7 +39,10 @@ const VITE_OPTIMIZE_DEPS = [
 const module$1 = defineNuxtModule({
   meta: {
     name: "@vue-solana/nuxt",
-    configKey: "solana"
+    configKey: "solana",
+    compatibility: {
+      nuxt: "^3.0.0 || ^4.0.0"
+    }
   },
   defaults: {
     cluster: "devnet",

package/dist/runtime/buffer-polyfill.cjs

@@ -0,0 +1,8 @@
+'use strict';
+
+const bufferPolyfill = require('@vue-solana/vue/buffer-polyfill');
+
+
+
+exports.Buffer = bufferPolyfill.Buffer;
+exports.installSolanaBufferPolyfill = bufferPolyfill.installSolanaBufferPolyfill;

package/dist/runtime/buffer-polyfill.d.cts

@@ -0,0 +1,2 @@
+export { Buffer, installSolanaBufferPolyfill } from '@vue-solana/vue/buffer-polyfill';
+import '@vue-solana/vue/web3';

package/dist/runtime/buffer-polyfill.d.mts

@@ -0,0 +1,2 @@
+export { Buffer, installSolanaBufferPolyfill } from '@vue-solana/vue/buffer-polyfill';
+import '@vue-solana/vue/web3';

package/dist/runtime/buffer-polyfill.d.ts

@@ -0,0 +1,2 @@
+export { Buffer, installSolanaBufferPolyfill } from '@vue-solana/vue/buffer-polyfill';
+import '@vue-solana/vue/web3';

package/dist/runtime/buffer-polyfill.mjs

@@ -0,0 +1 @@
+export { Buffer, installSolanaBufferPolyfill } from '@vue-solana/vue/buffer-polyfill';

package/dist/runtime/web3.cjs

@@ -0,0 +1,13 @@
+'use strict';
+
+const web3 = require('@vue-solana/vue/web3');
+
+
+
+exports.Connection = web3.Connection;
+exports.Keypair = web3.Keypair;
+exports.PublicKey = web3.PublicKey;
+exports.SystemProgram = web3.SystemProgram;
+exports.Transaction = web3.Transaction;
+exports.TransactionInstruction = web3.TransactionInstruction;
+exports.VersionedTransaction = web3.VersionedTransaction;

package/dist/runtime/web3.d.cts

@@ -0,0 +1 @@
+export { AccountInfo, Commitment, Connection, Keypair, PublicKey, RpcResponseAndContext, SendOptions, SignatureResult, SignatureStatus, SystemProgram, Transaction, TransactionInstruction, TransactionSignature, VersionedTransaction } from '@vue-solana/vue/web3';

package/dist/runtime/web3.d.mts

@@ -0,0 +1 @@
+export { AccountInfo, Commitment, Connection, Keypair, PublicKey, RpcResponseAndContext, SendOptions, SignatureResult, SignatureStatus, SystemProgram, Transaction, TransactionInstruction, TransactionSignature, VersionedTransaction } from '@vue-solana/vue/web3';

package/dist/runtime/web3.d.ts

@@ -0,0 +1 @@
+export { AccountInfo, Commitment, Connection, Keypair, PublicKey, RpcResponseAndContext, SendOptions, SignatureResult, SignatureStatus, SystemProgram, Transaction, TransactionInstruction, TransactionSignature, VersionedTransaction } from '@vue-solana/vue/web3';

package/dist/runtime/web3.mjs

@@ -0,0 +1 @@
+export { Connection, Keypair, PublicKey, SystemProgram, Transaction, TransactionInstruction, VersionedTransaction } from '@vue-solana/vue/web3';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vue-solana/nuxt",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Nuxt module for Solana applications.",
   "license": "MIT",
   "keywords": [
@@ -23,12 +23,22 @@
   "type": "module",
   "main": "./dist/module.cjs",
   "module": "./dist/module.mjs",
-  "types": "./dist/module.d.ts",
+  "types": "./dist/module.d.mts",
   "exports": {
     ".": {
-      "types": "./dist/module.d.ts",
+      "types": "./dist/module.d.mts",
       "import": "./dist/module.mjs",
       "require": "./dist/module.cjs"
+    },
+    "./buffer-polyfill": {
+      "types": "./dist/runtime/buffer-polyfill.d.ts",
+      "import": "./dist/runtime/buffer-polyfill.mjs",
+      "require": "./dist/runtime/buffer-polyfill.cjs"
+    },
+    "./web3": {
+      "types": "./dist/runtime/web3.d.ts",
+      "import": "./dist/runtime/web3.mjs",
+      "require": "./dist/runtime/web3.cjs"
     }
   },
   "files": [
@@ -38,16 +48,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@vue-solana/core": "0.7.0",
-    "@vue-solana/vue": "0.8.1"
+    "@solana/web3-compat": "^0.0.21",
+    "@vue-solana/vue": "0.8.3"
   },
   "peerDependencies": {
-    "@solana/web3-compat": "^0.0.21",
     "nuxt": "^3.0.0 || ^4.0.0"
   },
   "devDependencies": {
     "@nuxt/kit": "^4.4.6",
-    "@solana/web3-compat": "^0.0.21",
     "nuxt": "^4.4.6",
     "typescript": "^5.8.3",
     "unbuild": "^3.5.0",