Local First Auth Client Library

Common errors

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

  cause 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'

  cause 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).

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install local-first-auth npm
• yarn add local-first-auth yarn
• pnpm add local-first-auth pnpm

Imports

• Onboarding
  wrong:

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

  correct:

  import { Onboarding } from '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
  wrong:

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

  correct:

  import { createOnboarding } from '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
  wrong:

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

  correct:

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

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

Quickstart

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>
  );
}