{"id":16777,"library":"better-near-auth","title":"NEAR Protocol Sign-In Plugin for Better Auth","description":"better-near-auth is a plugin for the Better Auth library, enabling 'Sign in with NEAR' (SIWN) functionality for web3 applications. It abstracts the complexities of interacting with the NEAR Protocol's authentication mechanisms, allowing developers to integrate NEAR login flows into their existing Better Auth setups. The library currently stands at version 0.5.2 and shows an active development cadence with regular patch and minor releases, indicated by recent updates addressing bug fixes and introducing new features like single-step authentication and improved wallet selection logic. Key differentiators include its tight integration with Better Auth, support for modern NEAR authentication patterns (including `signMessage`), and handling of wallet connection and account resolution within the authentication flow.","status":"active","version":"0.5.2","language":"javascript","source_language":"en","source_url":"https://github.com/elliotBraem/better-near-auth","tags":["javascript","better-auth","near","siwn","sign-in-with-near","authentication","blockchain","web3","plugin","typescript"],"install":[{"cmd":"npm install better-near-auth","lang":"bash","label":"npm"},{"cmd":"yarn add better-near-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-near-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core authentication framework this package extends as a plugin.","package":"better-auth","optional":false},{"reason":"Required for type checking, as the library ships with TypeScript types and is intended for use in TypeScript projects.","package":"typescript","optional":false}],"imports":[{"note":"This is the main export for the plugin class, typically instantiated and passed to your Better Auth instance.","symbol":"BetterNearAuthPlugin","correct":"import { BetterNearAuthPlugin } from 'better-near-auth';"},{"note":"While better-near-auth is a plugin, its usage often starts with initializing the core `better-auth` library, which then registers the plugin.","symbol":"init","correct":"import { init } from 'better-auth';"},{"note":"The `signIn` method, extended by the plugin, is accessed from your `better-auth` instance. The specific method to call for NEAR authentication is `signIn.near()`.","symbol":"signIn","correct":"const { signIn } = useAuth(); // or similar access from better-auth instance"}],"quickstart":{"code":"import { init } from 'better-auth';\nimport { BetterNearAuthPlugin } from 'better-near-auth';\n\nconst betterAuth = init({\n  plugins: [\n    new BetterNearAuthPlugin({\n      networkId: 'testnet', // or 'mainnet'\n      nodeUrl: 'https://rpc.testnet.near.org', // or 'https://rpc.mainnet.near.org'\n      walletUrl: 'https://wallet.testnet.near.org', // or 'https://wallet.near.org'\n      helperUrl: 'https://helper.testnet.near.org', // or 'https://helper.near.org'\n      explorerUrl: 'https://explorer.testnet.near.org' // or 'https://explorer.near.org'\n    })\n  ],\n  // other better-auth configurations\n});\n\nasync function authenticateWithNear() {\n  try {\n    console.log('Attempting to sign in with NEAR...');\n    const user = await betterAuth.signIn.near();\n    console.log('Successfully signed in:', user);\n    // You can now access user.id, user.walletId, etc.\n  } catch (error) {\n    console.error('NEAR authentication failed:', error);\n    // Handle specific errors, e.g., user canceled login\n  }\n}\n\n// Call the authentication function (e.g., on a button click)\nauthenticateWithNear();\n","lang":"typescript","description":"This quickstart demonstrates how to initialize Better Auth with the BetterNearAuthPlugin and then initiate a 'Sign in with NEAR' flow. It configures the NEAR network parameters and calls `signIn.near()`."},"warnings":[{"fix":"Ensure your integration exclusively uses the `better-near-auth` plugin methods (e.g., `signIn.near()`) and does not rely on internals of `fastintear`.","message":"The underlying NEAR wallet connection and signing libraries were replaced in v0.3.0. If you were directly interacting with `fastintear`, you will need to update your code to use the new `near-kit` and `hot-connect` abstractions through `better-near-auth`'s API.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Upgrade to version 0.5.1 or newer. If the issue persists, ensure that the wallet selection process is correctly initiated before or during the `signIn.near()` call, possibly by explicitly connecting a wallet first if your UI flow requires it.","message":"When calling `signIn.near()` without a prior wallet connection, the system might fail to properly show the wallet selector or determine the authentication flow, potentially leading to 'No accounts found' errors. This was partially addressed in v0.5.1.","severity":"gotcha","affected_versions":"<0.5.1"},{"fix":"Test your authentication flow thoroughly with various NEAR wallets after upgrading to v0.5.0 to ensure compatibility with the new single-step flow. Report issues if specific wallets do not function as expected.","message":"Version 0.5.0 introduced a 'single-step authentication flow' for wallets supporting `signMessage`. This changes the internal authentication process, which might behave differently than previous versions for certain wallets or setups.","severity":"gotcha","affected_versions":">=0.5.0"},{"fix":"Ensure your development environment uses pnpm for installing `better-near-auth`'s dependencies to avoid potential issues related to package resolution or conflicting lockfiles.","message":"The package manager was migrated from Bun to pnpm in v0.5.0, which might affect development environments that rely on Bun's specific package resolution or lockfile format.","severity":"breaking","affected_versions":">=0.5.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure the wallet selection UI is correctly presented to the user before or during the `signIn.near()` call. Upgrade to `better-near-auth@0.5.1` or newer, which includes fixes for this specific scenario.","cause":"The `signIn.near()` method was called without a user having previously connected or selected a NEAR wallet, or the wallet selector failed to appear/resolve.","error":"Error: No accounts found. Please connect a NEAR wallet."},{"fix":"Verify that `new BetterNearAuthPlugin(...)` is included in the `plugins` array during the `better-auth.init()` call. Also, ensure `betterAuth` is the correct instance returned from `init()` or `useAuth()`.","cause":"The `BetterNearAuthPlugin` was not correctly initialized and registered with your `better-auth` instance, or the `better-auth` instance itself was not properly created.","error":"TypeError: betterAuth.signIn.near is not a function"},{"fix":"Handle this error gracefully in your application's UI, informing the user that the sign-in process was canceled. Provide options for them to retry authentication.","cause":"The user explicitly declined the authentication or signature request presented by their NEAR wallet.","error":"Wallet transaction failed: User rejected signature request."}],"ecosystem":"npm","meta_description":null}