Littlefish NFT Wallet Auth Framework

1.0.1 verified Sat May 09 auth: no javascript

An open-source NFT and wallet authentication framework specifically for Cardano blockchain applications. Current stable version is 1.0.1. It provides React components (WalletConnectButton, WalletConnectPage), a WalletProvider context, hooks (useWallet), and utility functions for connecting/disconnecting wallets, fetching assets, and decoding hex data. Designed for Next.js with client-side rendering. Key differentiators: tailored for Cardano ecosystem, supports multiple wallets, TypeScript types included, and offers both client and server functions.

Common errors

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

cause Package not installed or import path incorrect.

fix

Run npm install littlefish-nft-auth-framework. Ensure imports use correct subpath: 'littlefish-nft-auth-framework/frontend' for frontend components.

error Error: Hydration failed because the initial UI does not match what was rendered on the server. ↓

cause WalletProvider renders on server (window not available) causing mismatch.

fix

Wrap WalletProvider in a client-only component as shown in quickstart (ClientProviders).

error TypeError: Cannot read properties of undefined (reading 'enable' ) ↓

cause Cardano wallet extension not installed or not detected.

fix

Ensure a compatible Cardano wallet (e.g., Nami, Eternl) is installed and enabled in the browser.

Warnings

gotcha WalletProvider must be wrapped in a client-only boundary (ClientProviders) to avoid hydration mismatches in Next.js App Router. ↓

fix Create a ClientProviders component that mounts the WalletProvider only on the client side, as shown in the quickstart.

gotcha All UI components (WalletConnectButton, WalletConnectPage) and hooks (useWallet) must be imported from 'littlefish-nft-auth-framework/frontend', not the root package. ↓

fix Use import { Component } from 'littlefish-nft-auth-framework/frontend'.

gotcha The useWallet hook and related components rely on Cardano wallet browser extensions (e.g., Nami, Eternl). They will not work in non-browser environments. ↓

fix Only use in a browser context; ensure code is run client-side only.

gotcha The package does not include a default export; all exports are named. ↓

fix Use named imports as shown in the documentation.

Install

npm install littlefish-nft-auth-framework

yarn add littlefish-nft-auth-framework

pnpm add littlefish-nft-auth-framework

Imports

WalletProvider

wrong

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

correct

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

Client-side components must be imported from '/frontend' subpath. The root package export may not include them.

useWallet

wrong

import { useWallet } from 'littlefish-nft-auth-framework'

correct

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

Hook is part of the frontend module, not the root index.

WalletConnectButton

wrong

import WalletConnectButton from 'littlefish-nft-auth-framework/frontend'

correct

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

Named export, not default. Also ensure client-side usage with 'use client' directive.

Quickstart

Sets up WalletProvider with hydration-safe client wrapper and renders WalletConnectButton in Next.js app directory.

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

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

// app/ClientProviders.tsx
"use client";
import Providers from './Providers';
import { useEffect, useState } from 'react';

export default function ClientProviders({ children }: { children: React.ReactNode }) {
  const [hasMounted, setHasMounted] = useState(false);
  useEffect(() => { setHasMounted(true); }, []);
  if (!hasMounted) return null;
  return <Providers>{children}</Providers>;
}

// app/layout.tsx
import ClientProviders from './ClientProviders';

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

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

export default function Home() {
  return <WalletConnectButton />;
}