Getting Started

This guide will walk you through the essential steps to integrate DID Space functionality into your React application. You'll learn how to install the necessary package and implement a basic component that allows users to connect to their DID Space and view its details.

Step 1: Installation

First, you need to add the @blocklet/did-space-react package to your project. You can do this using npm or your preferred package manager.

Terminal

npm install @blocklet/did-space-react

Step 2: Create a Connection Component

Now, let's create a simple React component that demonstrates the core functionality. This example will use the DIDSpaceConnect component to establish a connection and the DIDSpaceConnection component to display the space's information once connected.

We will use React's useState hook to manage the connection state.

GettingStartedExample.tsx

import React, { useState } from 'react';
import Toast from '@arcblock/ux/lib/Toast';
import Button from '@mui/material/Button';
import Box from '@mui/material/Box';
import Typography from '@mui/material/Typography';
import { DIDSpaceConnect, DIDSpaceConnection, type DIDSpaceGateway } from '@blocklet/did-space-react';

// A helper function to format errors
const formatError = (error: any): string => {
  return error.message || 'An unknown error occurred.';
};

export default function GettingStartedExample() {
  const [spaceGateway, setSpaceGateway] = useState<DIDSpaceGateway | null>(null);

  const handleSuccess = async ({ spaceGateway: gateway }: { spaceGateway: DIDSpaceGateway }) => {
    try {
      console.log('Successfully connected to DID Space:', gateway);
      setSpaceGateway(gateway);
      Toast.success('Successfully connected to DID Space!');
    } catch (error) {
      console.error(error);
      Toast.error(formatError(error));
    }
  };

  const handleError = (error: Error) => {
    console.error('Connection failed:', error);
    Toast.error(formatError(error));
  };

  const handleDisconnect = () => {
    setSpaceGateway(null);
    Toast.info('Disconnected from DID Space.');
  };

  return (
    <Box sx={{ padding: 2, border: '1px solid #e0e0e0', borderRadius: '8px' }}>
      <Typography variant="h6" gutterBottom>
        DID Space Connection
      </Typography>
      {spaceGateway ? (
        <Box>
          <DIDSpaceConnection endpoint={spaceGateway.endpoint} selected sx={{ marginBottom: 2 }} />
          <Button onClick={handleDisconnect} variant="outlined">
            Disconnect
          </Button>
        </Box>
      ) : (
        <DIDSpaceConnect
          onSuccess={handleSuccess}
          onError={handleError}
          variant="contained"
        />
      )}
    </Box>
  );
}

How It Works

1. State Management

   We use useState<DIDSpaceGateway | null>(null) to keep track of the connected DID Space. Initially, it's null, indicating no connection.

2. Connecting

   The DIDSpaceConnect component renders a button. When a user clicks it and successfully connects, the onSuccess callback is triggered. This callback receives a spaceGateway object containing details about the user's DID Space.

3. Updating State

   Inside handleSuccess, we call setSpaceGateway(gateway) to store the connection details in our component's state. This causes the component to re-render.

4. Displaying Information

   After the re-render, the spaceGateway state is no longer null. The component now displays the DIDSpaceConnection card, passing the endpoint from our spaceGateway object. This card fetches and shows the DID Space's name, DID, and connection status.

5. Disconnecting

   We've added a "Disconnect" button that resets the state to null, which brings the DIDSpaceConnect button back, allowing the user to connect to another space.

Next Steps

You have now implemented a basic DID Space connection flow. To explore more advanced features and customizations, proceed to the detailed component documentation.