NEAR Protocol Sign-In Plugin for Better Auth

0.5.2 · active · verified Wed Apr 22

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.

Common errors

```
Error: No accounts found. Please connect a NEAR wallet.
```
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.

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.
```
TypeError: betterAuth.signIn.near is not a function
```
cause The `BetterNearAuthPlugin` was not correctly initialized and registered with your `better-auth` instance, or the `better-auth` instance itself was not properly created.

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()`.
```
Wallet transaction failed: User rejected signature request.
```
cause The user explicitly declined the authentication or signature request presented by their NEAR wallet.

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.

Warnings

breaking 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.
Fix: Ensure your integration exclusively uses the `better-near-auth` plugin methods (e.g., `signIn.near()`) and does not rely on internals of `fastintear`.
gotcha 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.
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.
gotcha 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.
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.
breaking 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.
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.

Install

npm install better-near-auth npm
yarn add better-near-auth yarn
pnpm add better-near-auth pnpm

Imports

BetterNearAuthPlugin
```
import { BetterNearAuthPlugin } from 'better-near-auth';
```
This is the main export for the plugin class, typically instantiated and passed to your Better Auth instance.
init
```
import { init } from 'better-auth';
```
While better-near-auth is a plugin, its usage often starts with initializing the core `better-auth` library, which then registers the plugin.
signIn
```
const { signIn } = useAuth(); // or similar access from better-auth instance
```
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()`.

Quickstart

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()`.

import { init } from 'better-auth';
import { BetterNearAuthPlugin } from 'better-near-auth';

const betterAuth = init({
  plugins: [
    new BetterNearAuthPlugin({
      networkId: 'testnet', // or 'mainnet'
      nodeUrl: 'https://rpc.testnet.near.org', // or 'https://rpc.mainnet.near.org'
      walletUrl: 'https://wallet.testnet.near.org', // or 'https://wallet.near.org'
      helperUrl: 'https://helper.testnet.near.org', // or 'https://helper.near.org'
      explorerUrl: 'https://explorer.testnet.near.org' // or 'https://explorer.near.org'
    })
  ],
  // other better-auth configurations
});

async function authenticateWithNear() {
  try {
    console.log('Attempting to sign in with NEAR...');
    const user = await betterAuth.signIn.near();
    console.log('Successfully signed in:', user);
    // You can now access user.id, user.walletId, etc.
  } catch (error) {
    console.error('NEAR authentication failed:', error);
    // Handle specific errors, e.g., user canceled login
  }
}

// Call the authentication function (e.g., on a button click)
authenticateWithNear();

view raw JSON →