{"id":16847,"library":"local-first-auth","title":"Local First Auth Client Library","description":"The `local-first-auth` library provides a client-side implementation of the Local First Auth specification, enabling web applications to integrate authentication without relying on backend servers, passwords, or third-party providers. Currently at version 2.2.1, it focuses on providing a lightweight, DID-based (Decentralized Identifier, specifically `did:key`) authentication flow where user profiles and cryptographic keys are generated and stored locally on the user's device. This approach is ideal for temporary or in-person community applications like meetups, social clubs, or game nights, offering a simple 3-step onboarding process. A key differentiator is its serverless nature and focus on local data storage, which simplifies development for specific use cases. However, users must be aware that clearing browser data will result in the loss of their account keys, making it unsuitable for applications requiring persistent or multi-device account access. The library offers both React components and vanilla JavaScript functions for integration, shipping with TypeScript types.","status":"active","version":"2.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/antler-browser/local-first-auth","tags":["javascript","local-first-auth","local-first","authentication","did","decentralized-identity","web-app","onboarding","typescript"],"install":[{"cmd":"npm install local-first-auth","lang":"bash","label":"npm"},{"cmd":"yarn add local-first-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add local-first-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for using the `local-first-auth/react` components.","package":"react","optional":false}],"imports":[{"note":"This is a named export for the React component. The library primarily uses ESM; CommonJS `require` is not directly supported without a transpilation layer.","wrong":"import Onboarding from 'local-first-auth/react';\nconst { Onboarding } = require('local-first-auth/react');","symbol":"Onboarding","correct":"import { Onboarding } from 'local-first-auth/react'"},{"note":"This is the factory function for vanilla JavaScript integration. The library primarily uses ESM; CommonJS `require` is not directly supported without a transpilation layer.","wrong":"import createOnboarding from 'local-first-auth';\nconst { createOnboarding } = require('local-first-auth');","symbol":"createOnboarding","correct":"import { createOnboarding } from 'local-first-auth'"},{"note":"Used to retrieve the currently authenticated user's profile and signed JWT. Requires the user to have completed onboarding. Primarily ESM.","wrong":"const { getProfileDetails } = require('local-first-auth');","symbol":"getProfileDetails","correct":"import { getProfileDetails } from 'local-first-auth'"}],"quickstart":{"code":"import { useState } from 'react';\nimport { Onboarding } from 'local-first-auth/react';\n\nfunction App() {\n  // Check if localFirstAuth is already initialized in the browser's window object.\n  // This helps determine if the user has an existing local-first profile.\n  const hasLocalFirstAuth = typeof window !== 'undefined' && window.localFirstAuth;\n  const [showOnboarding, setShowOnboarding] = useState(!hasLocalFirstAuth);\n\n  if (showOnboarding) {\n    return (\n      <Onboarding\n        // Callback function invoked upon successful completion of the onboarding process.\n        // The 'profile' object contains details like name, avatar, and DID.\n        onComplete={(profile) => {\n          console.log('Profile created:', profile);\n          // Hide the onboarding component after completion.\n          setShowOnboarding(false);\n        }}\n        // Customize the primary accent color of the onboarding UI.\n        customStyles={{ primaryColor: '#403B51' }}\n      />\n    );\n  }\n\n  // Render your main application content once onboarding is complete or skipped.\n  return (\n    <div>\n      <h1>Welcome to Your App!</h1>\n      <p>Local-first authentication is active.</p>\n      {/* Your application's main components would go here */}\n      <button onClick={() => setShowOnboarding(true)}>Show Onboarding Again</button> {/* For demonstration */}\n    </div>\n  );\n}","lang":"typescript","description":"Demonstrates how to integrate the `Onboarding` component into a React application, managing its visibility based on existing local-first authentication state and handling successful profile creation."},"warnings":[{"fix":"Advise users about data persistence limitations or explicitly design your application for temporary/one-time authentication scenarios where account recovery or multi-device access is not critical.","message":"User authentication keys are stored locally (e.g., in IndexedDB or Local Storage) and will be permanently lost if the user clears their browsing data. This requires users to create a new account.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Do not use `local-first-auth` for applications requiring robust, persistent, or multi-device user accounts. For such use cases, traditional authentication systems are more appropriate. This library excels in specific local-first, in-person scenarios.","message":"This library is designed for single-device, temporary authentication and does not support persistent accounts across multiple devices or easy account recovery. It is fundamentally different from traditional email/password or OAuth systems.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you are using ECMAScript Module (ESM) imports: `import { Onboarding } from 'local-first-auth/react'` and that your build tools (e.g., Webpack, Rollup) are configured to handle ESM properly.","cause":"Attempting to import the `Onboarding` React component using a CommonJS `require` syntax or incorrect named/default import in an environment expecting ESM.","error":"TypeError: (0 , _localFirstAuth_react__WEBPACK_IMPORTED_MODULE_0__.Onboarding) is not a function"},{"fix":"Install React in your project: `npm install react` (for React v18) or `npm install react@^19.0.0` (for React v19).","cause":"The `local-first-auth` package has a `peerDependency` on React, meaning React must be installed by your project, but it's missing.","error":"Module not found: Can't resolve 'react' in 'node_modules/local-first-auth/react'"}],"ecosystem":"npm","meta_description":null}