Littlefish NFT Wallet Auth Framework (Beta)

0.1.52 verified Sat May 09 auth: no javascript

A React-based open-source authentication framework for Cardano NFT and wallet integration, currently at v0.1.52 beta. Provides frontend wallet connection UI components (WalletProvider, WalletConnectButton, WalletConnectPage) and server-side auth functions (signup, login, verifySignature) tailored for Cardano blockchain. Ships TypeScript types, requires React 18, and is designed for Next.js App Router. Differentiates from generic web3 auth libraries by targeting Cardano ecosystem specifically, with built-in hex-to-ASCII decoding and CIP-8 message signing.

Common errors

error Module not found: Can't resolve 'littlefish-nft-auth-framework-beta' ↓

cause Importing from the package root without specifying /frontend or /server subpath.

fix

Use: import { ... } from 'littlefish-nft-auth-framework-beta/frontend' or '/server'.

error TypeError: (0 , _frontend.useWallet) is not a function ↓

cause Using default import instead of named import for useWallet.

fix

Use: import { useWallet } from 'littlefish-nft-auth-framework-beta/frontend'.

error Error: WalletProvider must be used within a client component ↓

cause Using WalletProvider in a server component without the 'use client' directive.

fix

Add "use client"; at the top of the file that renders WalletProvider.

error Unhandled Runtime Error: Cannot read properties of undefined (reading 'connect') ↓

cause Calling connectWallet before the wallet extension is installed or injected (e.g., Nami not installed).

fix

Check if the wallet exists: if (window.cardano && window.cardano[wantedWallet]) before calling connectWallet.

Warnings

breaking Package is in beta (v0.1.52) and the API may change without following semver. Do not use in production without pinning exact version. ↓

fix Pin to exact version in package.json: "littlefish-nft-auth-framework-beta": "0.1.52"

gotcha WalletConnectButton and WalletConnectPage require being inside a WalletProvider. If rendered outside, they will throw or produce no UI. ↓

fix Ensure all components using wallet hooks or buttons are children of <WalletProvider>.

gotcha Import paths are case-sensitive and versioned: frontend exports are at 'littlefish-nft-auth-framework-beta/frontend', server exports at 'littlefish-nft-auth-framework-beta/server'. Misspelling will result in module-not-found errors. ↓

fix Use exactly: 'littlefish-nft-auth-framework-beta/frontend' and 'littlefish-nft-auth-framework-beta/server'.

breaking The package is ESM-only and does not provide a CommonJS bundle. Using require() will throw a runtime error. ↓

fix Use ESM import syntax or dynamic import() if the consuming project is CJS.

deprecated As of v0.1.52, the `assets` type in useWallet returns arrays of [policyID, assetName, amount] instead of the documented interface. The documented Asset interface may be added in a future version. ↓

fix Treat assets as Array<[string, string, number]> for now; check CHANGELOG for interface updates.

gotcha The connectWallet function takes a walletName string (e.g., 'nami', 'eternl') but does not validate it against detected wallets. Passing an unsupported name will silently fail. ↓

fix Only call connectWallet with a value from the `wallets` array returned by useWallet.

Install

npm install littlefish-nft-auth-framework-beta

yarn add littlefish-nft-auth-framework-beta

pnpm add littlefish-nft-auth-framework-beta

Imports

WalletProvider

wrong

import { WalletProvider } from 'littlefish-nft-auth-framework-beta'

correct

import { WalletProvider } from 'littlefish-nft-auth-framework-beta/frontend'

WalletProvider is only available from the /frontend subpath; importing from the main package will not work.

useWallet

wrong

import useWallet from 'littlefish-nft-auth-framework-beta/frontend'

correct

import { useWallet } from 'littlefish-nft-auth-framework-beta/frontend'

useWallet is a named export, not a default export.

signupUser

wrong

import { signupUser } from 'littlefish-nft-auth-framework-beta'

correct

import { signupUser } from 'littlefish-nft-auth-framework-beta/server'

Server-side functions are exported from the /server subpath to avoid including Node dependencies in browser bundles.

WalletConnectButton

wrong

const WalletConnectButton = require('littlefish-nft-auth-framework-beta/frontend')

correct

import { WalletConnectButton } from 'littlefish-nft-auth-framework-beta/frontend'

This package is ESM-only; require() will fail. Use dynamic import() or ESM.

Quickstart

Sets up WalletProvider in a Next.js 13+ App Router layout and uses useWallet hook with WalletConnectButton on a page. Demonstrates best practices for client-side rendering and provider wrapping.

// providers.tsx
"use client";
import { WalletProvider } from 'littlefish-nft-auth-framework-beta/frontend';

export default function Providers({ children }: { children: React.ReactNode }) {
  return <WalletProvider>{children}</WalletProvider>;
}

// app/layout.tsx
import Providers from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <Providers>
          {children}
        </Providers>
      </body>
    </html>
  );
}

// page.tsx
"use client";
import { useWallet, WalletConnectButton } from 'littlefish-nft-auth-framework-beta/frontend';

export default function Home() {
  const { isConnected, assets, wallets, connectWallet, disconnectWallet } = useWallet();
  return (
    <div>
      <WalletConnectButton />
      {isConnected && (
        <div>
          <p>Wallet ID: {wallets[0]}</p>
          <button onClick={disconnectWallet}>Disconnect</button>
          <ul>
            {assets.map((asset, i) => (
              <li key={i}>{asset.policyID}: {asset.assetName} ({asset.amount})</li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}