{"id":27925,"library":"littlefish-nft-auth-framework-beta","title":"Littlefish NFT Wallet Auth Framework (Beta)","description":"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.","status":"active","version":"0.1.52","language":"javascript","source_language":"en","source_url":"https://github.com/littlefish-foundation/littlefish-nft-auth-framework","tags":["javascript","react","wallet","cardano","blockchain","nft","auth","typescript"],"install":[{"cmd":"npm install littlefish-nft-auth-framework-beta","lang":"bash","label":"npm"},{"cmd":"yarn add littlefish-nft-auth-framework-beta","lang":"bash","label":"yarn"},{"cmd":"pnpm add littlefish-nft-auth-framework-beta","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides React context and hooks for wallet state management","package":"react","optional":false},{"reason":"Required for rendering React components in browser","package":"react-dom","optional":false}],"imports":[{"note":"WalletProvider is only available from the /frontend subpath; importing from the main package will not work.","wrong":"import { WalletProvider } from 'littlefish-nft-auth-framework-beta'","symbol":"WalletProvider","correct":"import { WalletProvider } from 'littlefish-nft-auth-framework-beta/frontend'"},{"note":"useWallet is a named export, not a default export.","wrong":"import useWallet from 'littlefish-nft-auth-framework-beta/frontend'","symbol":"useWallet","correct":"import { useWallet } from 'littlefish-nft-auth-framework-beta/frontend'"},{"note":"Server-side functions are exported from the /server subpath to avoid including Node dependencies in browser bundles.","wrong":"import { signupUser } from 'littlefish-nft-auth-framework-beta'","symbol":"signupUser","correct":"import { signupUser } from 'littlefish-nft-auth-framework-beta/server'"},{"note":"This package is ESM-only; require() will fail. Use dynamic import() or ESM.","wrong":"const WalletConnectButton = require('littlefish-nft-auth-framework-beta/frontend')","symbol":"WalletConnectButton","correct":"import { WalletConnectButton } from 'littlefish-nft-auth-framework-beta/frontend'"}],"quickstart":{"code":"// providers.tsx\n\"use client\";\nimport { WalletProvider } from 'littlefish-nft-auth-framework-beta/frontend';\n\nexport default function Providers({ children }: { children: React.ReactNode }) {\n return {children};\n}\n\n// app/layout.tsx\nimport Providers from './providers';\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n return (\n \n \n \n {children}\n \n \n \n );\n}\n\n// page.tsx\n\"use client\";\nimport { useWallet, WalletConnectButton } from 'littlefish-nft-auth-framework-beta/frontend';\n\nexport default function Home() {\n const { isConnected, assets, wallets, connectWallet, disconnectWallet } = useWallet();\n return (\n
\n );\n}","lang":"typescript","description":"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."},"warnings":[{"fix":"Pin to exact version in package.json: \"littlefish-nft-auth-framework-beta\": \"0.1.52\"","message":"Package is in beta (v0.1.52) and the API may change without following semver. Do not use in production without pinning exact version.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Ensure all components using wallet hooks or buttons are children of .","message":"WalletConnectButton and WalletConnectPage require being inside a WalletProvider. If rendered outside, they will throw or produce no UI.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use exactly: 'littlefish-nft-auth-framework-beta/frontend' and 'littlefish-nft-auth-framework-beta/server'.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use ESM import syntax or dynamic import() if the consuming project is CJS.","message":"The package is ESM-only and does not provide a CommonJS bundle. Using require() will throw a runtime error.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Treat assets as Array<[string, string, number]> for now; check CHANGELOG for interface updates.","message":"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.","severity":"deprecated","affected_versions":">=0.1.0"},{"fix":"Only call connectWallet with a value from the `wallets` array returned by useWallet.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Use: import { ... } from 'littlefish-nft-auth-framework-beta/frontend' or '/server'.","cause":"Importing from the package root without specifying /frontend or /server subpath.","error":"Module not found: Can't resolve 'littlefish-nft-auth-framework-beta'"},{"fix":"Use: import { useWallet } from 'littlefish-nft-auth-framework-beta/frontend'.","cause":"Using default import instead of named import for useWallet.","error":"TypeError: (0 , _frontend.useWallet) is not a function"},{"fix":"Add \"use client\"; at the top of the file that renders WalletProvider.","cause":"Using WalletProvider in a server component without the 'use client' directive.","error":"Error: WalletProvider must be used within a client component"},{"fix":"Check if the wallet exists: if (window.cardano && window.cardano[wantedWallet]) before calling connectWallet.","cause":"Calling connectWallet before the wallet extension is installed or injected (e.g., Nami not installed).","error":"Unhandled Runtime Error: Cannot read properties of undefined (reading 'connect')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}