# Getting Started

This guide will walk you through the essential steps to integrate decentralized identity (DID) authentication into your React application using `@arcblock/did-connect-react`. In just a few minutes, you'll have a fully functional login and logout flow.

### Prerequisites

Before you begin, ensure your development environment meets the following criteria:

- You have a React project set up.
- You have a running Blocklet Server instance that will handle the authentication requests. The library is designed to work seamlessly with a backend powered by Blocklet Server.

## Step 1: Install the Library

First, add the `@arcblock/did-connect-react` package to your project. You can use either npm or yarn.

```bash Install with npm icon=logos:npm
npm install @arcblock/did-connect-react
```

```bash Install with yarn icon=logos:yarn
yarn add @arcblock/did-connect-react
```

## Step 2: Set Up the SessionProvider

The `SessionProvider` is the heart of the library. It's a context provider that manages the user's session state (like login status and user information) and makes it available to all components wrapped within it. You should place it at the root of your application, for instance, in your `App.js` file.

For applications built on Blocklet, the recommended way to initialize the provider is by using the `createAuthServiceSessionContext` factory function.

```javascript App.js icon=logos:react
import React from 'react';
import { createAuthServiceSessionContext } from '@arcblock/did-connect-react/lib/Session';
import Home from './Home'; // We will create this component in the next step

// createAuthServiceSessionContext is optimized for Blocklet environments
const { SessionProvider } = createAuthServiceSessionContext();

function App() {
  return (
    // The serviceHost prop points to the base path of your backend authentication service.
    // For a standard Blocklet, this is usually the blocklet's prefix or '/'.
    <SessionProvider serviceHost="/">
      <Home />
    </SessionProvider>
  );
}

export default App;
```

## Step 3: Implement Login and Logout

Now, let's create a component that allows users to log in and log out. We can access the session data and functions using React's `useContext` hook with the `SessionContext`.

The `session` object gives you everything you need: the current `user`, the `loading` state, and functions like `login()` and `logout()`.

```javascript Home.js icon=logos:react
import React, { useContext } from 'react';
import { SessionContext } from '@arcblock/did-connect-react/lib/Session';
import ConnectButton from '@arcblock/did-connect-react/lib/Button';
import Button from '@arcblock/ux/lib/Button'; // A general-purpose button
import CircularProgress from '@mui/material/CircularProgress';

function Home() {
  // Access the session context
  const { session } = useContext(SessionContext);

  // Destructure for easier access
  const { user, loading, login, logout } = session;

  // Display a loading indicator while the session is being initialized
  if (loading) {
    return <CircularProgress />;
  }

  return (
    <div style={{ padding: '20px', textAlign: 'center' }}>
      {user ? (
        // If the user is logged in, show their DID and a logout button
        <div>
          <h1>Welcome!</h1>
          <p>Your DID: {user.did}</p>
          <Button variant="contained" color="secondary" onClick={logout}>
            Logout
          </Button>
        </div>
      ) : (
        // If not logged in, show the login button
        <div>
          <h1>Please Sign In</h1>
          <ConnectButton onClick={() => login()}>
            Connect Wallet
          </ConnectButton>
        </div>
      )}
    </div>
  );
}

export default Home;
```

When the user clicks the `ConnectButton`, the `login()` function is called. This function handles opening the DID Connect modal, which displays a QR code for the user to scan with their DID Wallet, and manages the entire authentication process.

## Step 4: Access User Data

Once a user has successfully logged in, the `session.user` object will be populated. This object contains the user's profile information retrieved from their DID Wallet.

The `session` object provided by the context is your main interface to the user's authentication state. Here are its key properties:

<x-field-group>
  <x-field data-name="user" data-type="object | null" data-desc="The authenticated user object. It's `null` if no user is logged in.">
    <x-field data-name="did" data-type="string" data-desc="The user's Decentralized Identifier (DID)."></x-field>
    <x-field data-name="fullName" data-type="string" data-desc="The user's full name from their wallet profile."></x-field>
    <x-field data-name="email" data-type="string" data-desc="The user's email from their wallet profile."></x-field>
  </x-field>
  <x-field data-name="loading" data-type="boolean" data-desc="`true` while the session is being initialized or refreshed, `false` otherwise."></x-field>
  <x-field data-name="login" data-type="function" data-desc="A function to initiate the login process, which opens the DID Connect UI."></x-field>
  <x-field data-name="logout" data-type="function" data-desc="A function to log the user out and clear the session."></x-field>
  <x-field data-name="initialized" data-type="boolean" data-desc="`true` once the initial session check is complete."></x-field>
</x-field-group>

## You're All Set!

Congratulations! You have successfully implemented a complete DID-based authentication flow in your React application. Users can now sign in using their DID Wallet, and your application can securely access their session information.

### Next Steps

To dive deeper and explore more advanced features, check out the following sections:

<x-cards>
  <x-card data-title="Session Management (SessionProvider)" data-icon="lucide:key-round" data-href="/core-components/session-provider">
    Learn about all the configuration options for `SessionProvider` to customize session behavior, timeouts, and more.
  </x-card>
  <x-card data-title="Connection UI (DidConnect)" data-icon="lucide:qr-code" data-href="/core-components/did-connect">
    Explore the `DidConnect` component for a declarative way to embed the connection UI directly into your pages.
  </x-card>
</x-cards>