Vite + TypeScript Integration

This guide explains how to integrate the Lucia SDK into a Vite + TypeScript project. New to Lucia? Start with the Quickstart for the 5-minute path.

Prerequisites

• A Vite + TypeScript project
• A Lucia API key from your dashboard (Settings → API Keys)
• Environment variables configured in your .env file

Installation and Setup

1. Install the SDK:

npm install lucia-sdk
# or
yarn add lucia-sdk

2. Initialize the SDK in your application entry point (typically App.tsx):

import LuciaSDK from 'lucia-sdk';

LuciaSDK.init({
  apiKey: import.meta.env.VITE_LUCIA_API_KEY,
});

Optional: you can pass a debug URL in the initialization parameters. This is typically only for internal use.

import LuciaSDK from 'lucia-sdk';

LuciaSDK.init({
  apiKey: import.meta.env.VITE_LUCIA_API_KEY,
  debugURL: import.meta.env.VITE_LUCIA_DEBUG_URL,
});

Tracking Wallet Interactions

The SDK provides methods to link wallet connections and user information to the same customer profile. Here's how to implement wallet tracking in your login function:

interface WalletLoginParams {
  connectedAccount: string;
  walletName: "Metamask" | "Phantom";
}

async function handleWalletLogin({ connectedAccount, walletName }: WalletLoginParams) {
  try {
    // Link the wallet connection to this customer
    await LuciaSDK.sendWalletInfo(connectedAccount, 101, walletName);

    // Handle wallet-specific logic
    switch (walletName) {
      case "Phantom": {
        const solBalance = await connection.getBalance(new PublicKey(connectedAccount));
        const tokenAccount = await fetchTokenAccounts();

        // Attach user information including balances
        await LuciaSDK.userInfo(connectedAccount, {
          solBalance,
          tokenAccount,
        });
        break;
      }

      case "Metamask": {
        // Add Metamask-specific tracking here
        await LuciaSDK.userInfo(connectedAccount, {
          // Add relevant Ethereum wallet data
        });
        break;
      }
    }
  } catch (error) {
    console.error('Error during wallet login tracking:', error);
  }
}

These are the lines that specifically interact with the SDK:

await LuciaSDK.sendWalletInfo(connectedAccount, 101, walletName);

await LuciaSDK.userInfo(connectedAccount, {
  solBalance,
  tokenAccount,
});

API Reference

sendWalletInfo

Links a wallet connection to the customer profile:

LuciaSDK.sendWalletInfo(
  walletAddress: string,  // The wallet address of the user
  chainId: number,        // Blockchain network ID
  walletProvider: string  // Wallet provider name
): Promise<void>

userInfo

Associates user-specific information:

LuciaSDK.userInfo(
  userId: string,     // The user's ID, e.g. email, wallet address, etc.
  userInfo: object    // Additional user information, e.g. name, contact details, etc.
): Promise<void>

Best Practices

• Error handling: always wrap SDK calls in proper error handling.
• Environment variables: keep API keys and URLs in environment variables.

Troubleshooting

If you encounter issues:

• Verify your API key and debug URL are correct.
• Check the browser console for error messages (enable debug: true in init).
• Ensure all required dependencies are installed.

Check our open source codebase on GitHub.