Registry / auth-security / local-first-auth

local-first-auth

library2.2.1jsnpmunverified

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.

auth-security web-framework

npm install local-first-auth

github ↗package ↗

INSTALL

IMPORT

SIG · LOCAL-FIRST-AUTH

local-first-auth

auth-securityjavascriptv2.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Onboarding

✓ import { Onboarding } from 'local-first-auth/react'

✗ import Onboarding from 'local-first-auth/react'; const { Onboarding } = require('local-first-auth/react');

This is a named export for the React component. The library primarily uses ESM; CommonJS `require` is not directly supported without a transpilation layer.

createOnboarding

✓ import { createOnboarding } from 'local-first-auth'

✗ import createOnboarding from 'local-first-auth'; const { createOnboarding } = require('local-first-auth');

This is the factory function for vanilla JavaScript integration. The library primarily uses ESM; CommonJS `require` is not directly supported without a transpilation layer.

getProfileDetails

✓ import { getProfileDetails } from 'local-first-auth'

✗ const { getProfileDetails } = require('local-first-auth');

Used to retrieve the currently authenticated user's profile and signed JWT. Requires the user to have completed onboarding. Primarily ESM.

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.

import { useState } from 'react'; import { Onboarding } from 'local-first-auth/react'; function App() { // Check if localFirstAuth is already initialized in the browser's window object. // This helps determine if the user has an existing local-first profile. const hasLocalFirstAuth = typeof window !== 'undefined' && window.localFirstAuth; const [showOnboarding, setShowOnboarding] = useState(!hasLocalFirstAuth); if (showOnboarding) { return ( <Onboarding // Callback function invoked upon successful completion of the onboarding process. // The 'profile' object contains details like name, avatar, and DID. onComplete={(profile) => { console.log('Profile created:', profile); // Hide the onboarding component after completion. setShowOnboarding(false); }} // Customize the primary accent color of the onboarding UI. customStyles={{ primaryColor: '#403B51' }} /> ); } // Render your main application content once onboarding is complete or skipped. return ( <div> <h1>Welcome to Your App!</h1> <p>Local-first authentication is active.</p> {/* Your application's main components would go here */} <button onClick={() => setShowOnboarding(true)}>Show Onboarding Again</button> {/* For demonstration */} </div> ); }

Debug

Known issues

gotchaUser 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.

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.

affects: >=1.0.0

gotchaThis 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.

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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: (0 , _localFirstAuth_react__WEBPACK_IMPORTED_MODULE_0__.Onboarding) is not a function

Attempting to import the `Onboarding` React component using a CommonJS `require` syntax or incorrect named/default import in an environment expecting ESM.

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.

Module not found: Can't resolve 'react' in 'node_modules/local-first-auth/react'

The `local-first-auth` package has a `peerDependency` on React, meaning React must be installed by your project, but it's missing.

fix

Install React in your project: `npm install react` (for React v18) or `npm install react@^19.0.0` (for React v19).

Upgrade

Version history

2.2.1latest on npm

Audit

Dependencies

reactrequiredPeer dependency required for using the `local-first-auth/react` components.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/antler-browser/local-first-auth ↗

packagehttps://www.npmjs.com/package/local-first-auth ↗