npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@peerfolio/privy-near-connect

v0.0.8

Published

Privy wallet adapter for near-connect

Readme

Privy NEAR Connect

This SDK enables developer's to set up their own NEAR wallet on top of Privy's embedded wallet infrastructure, and connect it to the NEAR ecosystem through the near-connect lib. It includes a customizable sign page plugin that can be hosted by the developer and used to perform signing operations from any dApp.

While most of the examples from this library use React, the library is framework-agnostic. An example React app is also included to demonstrate usage of the sign page plugin. It is hosted here but note that you need to plug in your own Privy credentials to work it.

@peerfolio/privy-near-connect is the official npm package for this repository. The code is maintained in the beneviolabs/privy-near-connect GitHub repository, while the published package uses the @peerfolio npm scope.

Contributing

For development setup, release process, and troubleshooting see CONTRIBUTING.md.

Getting Started

  1. Install @peerfolio/privy-near-connect NPM package into your project
npm install @peerfolio/privy-near-connect
  1. Setup Privy per their docs to obtain your Privy App ID and Client ID.

    2.1 To obtain the App ID. New Application -> Configuration-App Settings -> App ID lives on the Basics tab.

    2.2 On the same UI, obtain the Client ID from Clients tab -> Create Client

  2. Setup near-connect on your app

i. Add a manifest.json to your dApp with the URL of your sign page:

{
"version": "1.0.0",
"wallets": [
  {
    "id": "myprivywallet",
    "name": "My Privy Wallet",
    "icon": "https://yourdapp.com/favicon.ico",
    "description": "Web wallet for NEAR.",
    "website": "https://yourdapp.com",
    "version": "1.0.0",
    "executor": "https://raw.githubusercontent.com/beneviolabs/privy-near-connect/3d56b782669d242a1ea432921e291abc26b4ebc7/executor.js",
    "type": "sandbox",
    "platform": {
      "web": "https://yourdapp.com"
    },
    "features": {
      "signMessage": true,
      "signInWithoutAddKey": true,
      "signInAndSignMessage": true,
      "signInWithFunctionCallKey": true,
      "signAndSendTransaction": true,
      "signAndSendTransactions": true,
      "mainnet": true,
      "testnet": true
    },
    "permissions": {
       // important
      "isPrivyConnect": true,
      "storage": true,
      "allowsOpen": [
        "https://yourdapp.com"
      ]
    },
    "metadata": {
      "signPageURL": "https://yourdapp.com/sign",
      "debug": false
    }
  },
  ]
}

Pin the executor URL to an immutable commit. near-connect fetches and runs the executor script at runtime with no integrity check, so the URL determines what code executes in your users' browsers. Reference a specific commit SHA (.../<commit-sha>/executor.js) rather than a mutable branch like .../refs/heads/release/executor.js — a branch URL silently picks up whatever is pushed to that branch next. Bump the SHA deliberately when you adopt a new executor build, and treat write access to the branch it is built from as security-sensitive.

metadata.debug is an optional runtime switch for executor diagnostics. It defaults to false; set it to true temporarily when debugging popup handshakes or executor messages. Debug logging can include signing request and response objects, so do not enable it in production.

ii. Initialize near-connect in your dApp and specify the wallet from the manifest:

import { NearConnector } from '@hot-labs/near-connect';

const connector = new NearConnector({
  manifest: '/manifest.json',
  network: 'mainnet',
});

// Listen for account sign in
connector.on("wallet:signIn", async () => {
  const w = await connector.wallet();
  const accounts = await w.getAccounts({ network });
  // optionally set wallet reference and accounts in your app context
});

// Initiates connector and triggers "wallet:signIn"
// This will open the sign page in a popup and prompt the user to sign in with their wallet. Once they do, the popup will close and the promise will resolve with their account(s).
// You may want to trigger this in your app's login flow
await connector.connect({ walletId: 'myprivywallet' }); // walletId should match the id field in your manifest for the wallet you set up.
  1. Setup a signing screen route in your app on /sign (or any path you prefer, just make sure to update the manifest.json with the correct URL).
// **Option A**: Build your own custom signing page UI
import { initSigningPage } from '@peerfolio/privy-near-connect/sign-page';
import Privy from '@privy-io/js-sdk-core';
import {useEffect, useState} from 'react';

// Load these from your app's environment/config. For example, in Vite you might use
// `import.meta.env.VITE_PRIVY_APP_ID` and `import.meta.env.VITE_PRIVY_APP_CLIENT_ID`.
// In Next.js the equivalent would typically be
// `process.env.NEXT_PUBLIC_PRIVY_APP_ID` and `process.env.NEXT_PUBLIC_PRIVY_APP_CLIENT_ID`.
const PRIVY_APP_ID = import.meta.env.VITE_PRIVY_APP_ID
const PRIVY_APP_CLIENT_ID = import.meta.env.VITE_PRIVY_APP_CLIENT_ID

export default function SignPage() {
  const [ready, setReady] = useState(false);

  // Recommended: Optionally check here that user is authed to Privy
  const privyClient = new Privy({
    appId: PRIVY_APP_ID,
    clientId: PRIVY_APP_CLIENT_ID,
    storage: new LocalStorage(),
  });

  useEffect(() => {
    // important if you have a custom domain on privy with
    // httponly cookie access since Privy client will otherwise call auth.privy.io to auth
    // instead of your custom domain, resulting in 401 error.
    privyClient.initialize().then(() => setReady(true));
  }, []);

  let session;

  // You may also specify the wallet to be used for signing here if a user has multiple wallets in their Privy account. Check the jsdoc for this function for details.
  initSigningPage(privyClient, {
    allowedOrigins: ['https://yourdapp.example.com'],
    debug: false,
  }).then((s) => { session = s });

  return ready ? (
    <div>
      <h1>Wanna sign this?</h1>
      {/* Show the requesting origin so users can verify who is asking */}
      <p>Requested by: <strong>{session?.targetOrigin}</strong></p>
      <pre>
        {JSON.stringify(session?.payload, null, 2)}
      </pre>
      <button onClick={() => {session.sign()}}>
        Sign with your wallet
      </button>
      <button onClick={() => {window.close()}}>
        Reject
      </button>
    </div>
  ) : null;
}

// **Option B**: Use the SignPagePlugin component for a pre-built signing page UI
import { SignPagePlugin } from '@peerfolio/privy-near-connect/sign-page-plugin';
import '@radix-ui/themes/styles.css';
import '@peerfolio/privy-near-connect/sign-page-plugin/theme.css';

export default function SignPage() {
  ...
  return (
    <SignPagePlugin
      privy={privyClient}
      options={{ allowedOrigins: ['https://yourdapp.example.com'], debug: false }}
    />
  );
}

SignPageOptions.debug is an optional runtime switch for popup, signing, and account diagnostics. It defaults to false; set it to true only while troubleshooting. Detailed debug output may include signing payloads, linked-account data, and result or error objects, so leave it disabled in production.

This page will be opened in a popup by the near-connect SDK when a signing request is made from the dApp.

  1. Ensure users can log in with whichever preferred auth method(s) you want to support. Here is an example using SMS login:
import { useState } from "react";
import { useLoginWithSms } from "@privy-io/react-auth";

export default function LoginWithSms() {
  const [phoneNumber, setPhoneNumber] = useState("");
  const [code, setCode] = useState("");
  const { state, sendCode, loginWithCode } = useLoginWithSms();

  return (
    <div>
      {/* Prompt your user to enter their phone number */}
      <input onChange={(e) => setPhoneNumber(e.currentTarget.value)} value={phoneNumber} />
      {/* Once a phone number has been entered, send the OTP to it on click */}
      <button onClick={() => sendCode({ phoneNumber })}>Send Code</button>

      {/* Prompt your user to enter the OTP */}
      <input onChange={(e) => setCode(e.currentTarget.value)} value={code} />
      {/* Once an OTP has been entered, submit it to Privy on click */}
      <button onClick={() => loginWithCode({ code })}>Log in</button>
    </div>
  );
}

Once a user auths with Privy, the requisite cookies/local storage will be set on their browser. This allows the sign page to auth during calls to Privy APIs for signing operations.

  1. Use the wallet to sign transactions/messages from your dApp as you normally would:
const w = await connector.wallet();
// This will open the signing page you set up in your app to prompt the user to approve the transaction. Once they approve or reject, the popup will close and the promise will resolve with the signed transaction or reject with an error.
const result = await w.signAndSendTransaction({...txn});

Architecture

Message flow

sequenceDiagram
  autonumber
  participant E as dApp<br>[near-connect (executor.js)]
  participant P as dApp<br>[sign page popup]
  participant PR as Privy (embedded wallet)

  E->>P: window.selector.open(signPageURL)
  P->>PR: mount hidden iframe
  P->>E: postMessage({ type: 'READY' })
  E->>P: popup.postMessage({ type: 'SIGN_REQUEST', payload })
  P->>PR: sign payload
  PR-->>P: signed result
  P->>E: postMessage(result OR error)
  Note over P: window.close()
  Note over E: resolves promise

Cross-origin support

The signing page may be hosted on a different origin from the dApp. allowedOrigins is required for initSigningPage, so developers must explicitly choose either a restrictive allowlist or every domain:

initSigningPage(privy, { allowedOrigins: ['https://dapp.example.com'] });

Or to allow any origin (e.g. for general-purpose wallets), opt in explicitly:

initSigningPage(privy, { allowedOrigins: 'dangerouslyAllowAllOrigins' });

'dangerouslyAllowAllOrigins' is appropriate for general-purpose wallets that accept requests from any dApp. Most single-dApp deployments should use an explicit origin list to prevent a malicious window from sending an unexpected payload.