{"id":16774,"library":"better-auth-solana","title":"Better Auth Plugin for Solana Sign-In","description":"better-auth-solana is a specialized plugin for the Better Auth authentication framework, designed to facilitate \"Sign in With Solana\" (SIWS) functionality. Currently at version 1.0.0, it provides a stable, initial release enabling Solana wallet integration into Better Auth applications. The package includes server-side endpoints for managing the SIWS flow (nonce generation, signature verification, wallet linking) and client-side utilities for constructing SIWS messages and interacting with the Better Auth client. It natively handles session establishment and account creation/linking within the Better Auth ecosystem, using its dedicated `siws` plugin namespace. The package is published as ESM-only, aligning with better-auth's modern module strategy.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/beeman/better-auth-solana","tags":["javascript","authentication","better-auth","siws","solana","wallet","typescript"],"install":[{"cmd":"npm install better-auth-solana","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-solana","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-solana","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Solana wallet interactions and signing.","package":"@solana/kit","optional":false},{"reason":"Core authentication framework that this package extends as a plugin.","package":"better-auth","optional":false}],"imports":[{"note":"The server-side plugin for Better Auth; ESM-only since v1.0.0.","wrong":"const { siws } = require('better-auth-solana')","symbol":"siws","correct":"import { siws } from 'better-auth-solana'"},{"note":"Client-side helper for creating structured SIWS input for wallets; ESM-only.","wrong":"const { createSIWSInput } = require('better-auth-solana/client')","symbol":"createSIWSInput","correct":"import { createSIWSInput } from 'better-auth-solana/client'"},{"note":"Client-side plugin to extend `better-auth/client` functionality; ESM-only.","wrong":"const { siwsClient } = require('better-auth-solana/client')","symbol":"siwsClient","correct":"import { siwsClient } from 'better-auth-solana/client'"},{"note":"Utility to format SIWS fields into a canonical message string; ESM-only.","wrong":"const { formatSIWSMessage } = require('better-auth-solana/client')","symbol":"formatSIWSMessage","correct":"import { formatSIWSMessage } from 'better-auth-solana/client'"}],"quickstart":{"code":"import { createAuthClient } from 'better-auth/client'\nimport { createSIWSInput, siwsClient } from 'better-auth-solana/client'\n\n// Placeholder for your wallet's sign function\nasync function signWithYourWallet(siwsInput: any): Promise<{ message: string; signature: string }> {\n  console.log('Signing message with wallet:', siwsInput)\n  // In a real app, this would involve connecting to a Solana wallet (e.g., Phantom, Solflare)\n  // and using its sign message functionality. For demonstration, we'll return a mock.\n  const mockSignature = 'mock_signature_' + Date.now()\n  return { message: JSON.stringify(siwsInput), signature: mockSignature }\n}\n\n// Assume 'address' is the connected Solana wallet address\nconst address = 'GMtGgT8d6R3FwYxK2c3L4p5Q6r7S8t9U0v1W2x3Y4z5'\n\nconst authClient = createAuthClient({\n  plugins: [siwsClient()],\n})\n\nasync function performSolanaSignIn() {\n  try {\n    const nonceResult = await authClient.siws.nonce({\n      walletAddress: address,\n    })\n\n    if (!nonceResult.data) {\n      throw new Error('Failed to request SIWS nonce')\n    }\n\n    const siwsInput = createSIWSInput({\n      address,\n      challenge: nonceResult.data,\n      statement: 'Sign in to Example',\n      domain: 'example.com', // Must match the domain configured on the server\n      uri: 'https://example.com/siws', // The current application URI\n      chainId: 'solana:mainnet', // Solana network chain ID\n      version: '1' // SIWS version\n    })\n\n    const signed = await signWithYourWallet(siwsInput)\n\n    await authClient.siws.verify({\n      message: signed.message,\n      signature: signed.signature,\n      walletAddress: address,\n    })\n\n    const session = await authClient.getSession()\n    console.log('Successfully signed in:', session)\n  } catch (error) {\n    console.error('SIWS sign-in failed:', error)\n  }\n}\n\nperformSolanaSignIn()\n","lang":"typescript","description":"Demonstrates a complete client-side 'Sign in With Solana' (SIWS) flow, including nonce retrieval, message creation, wallet signing (mocked), and session verification with Better Auth."},"warnings":[{"fix":"Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`) or use dynamic `import()` for CJS compatibility layers where appropriate.","message":"The `better-auth-solana` package is ESM-only (ECMAScript Modules) since its initial v1.0.0 release. Attempts to `require()` it in a CommonJS environment will result in module resolution errors.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Run `npm install @solana/kit@^6.8.0 better-auth@^1.5.0 better-auth-solana` (or use `yarn`/`bun`) to ensure all required peer dependencies are present and compatible.","message":"This package has peer dependencies on `@solana/kit` (`^6.8.0`) and `better-auth` (`^1.5.0`). These must be installed separately in your project and meet the specified version constraints for `better-auth-solana` to function correctly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `verify` for initial sign-in flows and `link` only when a user is already logged in and wants to add another wallet address to their existing account.","message":"When using client-side verification, differentiate between `authClient.siws.verify(...)` for establishing a new Better Auth session or logging in, and `authClient.siws.link(...)` for attaching a new Solana wallet to an *already authenticated* Better Auth session.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"When configuring frontend API calls or proxies, ensure the full path including the `/siws/` segment is correctly used for all interactions with the plugin's endpoints.","message":"The plugin uses a fixed `siws` namespace, which means its API endpoints will always be nested under your Better Auth handler's path, e.g., `/api/auth/siws/verify`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Migrate your file or project to use ES Modules (`import ... from '...'`) or dynamically import the package using `await import(...)`.","cause":"Attempting to use `require()` to import `better-auth-solana` or its subpaths in a CommonJS module.","error":"ERR_REQUIRE_ESM"},{"fix":"Verify the server is running and the `siws` plugin is correctly configured. Check network requests in your browser's developer tools for errors from the `/siws/nonce` endpoint and ensure `walletAddress` is valid.","cause":"The server-side `/siws/nonce` endpoint did not return a challenge, possibly due to a network issue, server misconfiguration, or an invalid `walletAddress` provided.","error":"Failed to request SIWS nonce"},{"fix":"Ensure `createSIWSInput` or `createSIWSMessage` is used correctly to generate the message. Confirm the wallet's `signMessage` function is returning the expected message and a valid signature. The `domain`, `uri`, and other SIWS fields must match those expected by the server.","cause":"The `message` or `signature` provided to `authClient.siws.verify` (or `link`) does not match the expected SIWS format or fails signature verification.","error":"Error: Invalid SIWS message format"}],"ecosystem":"npm","meta_description":null}