> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socket.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# SocketFi React SDK Installation, Setup, and Config

> Install @socketfi/react, configure your Client ID environment variable, and initialize the SocketFi client in your project in minutes.

Installing the SocketFi React SDK takes three steps: add the package, set your environment variables, and create a shared client instance. Once that's done, every component in your app can authenticate users and submit transactions through a single import.

## Install the package

<CodeGroup>
  ```bash npm theme={null}
  npm install @socketfi/react
  ```

  ```bash yarn theme={null}
  yarn add @socketfi/react
  ```

  ```bash pnpm theme={null}
  pnpm add @socketfi/react
  ```
</CodeGroup>

## Prerequisites

Before initializing the client, make sure you have:

* A SocketFi account and a registered application in the [Developer Portal](https://portal.socketfi.com)
* Your application's **Client ID** (found on the application detail page)
* React 18 or later installed in your project
* TypeScript configured (recommended)

## Set up environment variables

Store your Client ID in an environment variable rather than hard-coding it. The variable name you use depends on your build tool.

<Tabs>
  <Tab title="Vite">
    Add the following to your `.env` file:

    ```bash theme={null}
    VITE_SOCKETFI_CLIENT_ID=your_client_id_here
    ```

    Access it in your code with:

    ```typescript theme={null}
    import.meta.env.VITE_SOCKETFI_CLIENT_ID
    ```
  </Tab>

  <Tab title="Next.js">
    Add the following to your `.env.local` file:

    ```bash theme={null}
    NEXT_PUBLIC_SOCKETFI_CLIENT_ID=your_client_id_here
    ```

    Access it in your code with:

    ```typescript theme={null}
    process.env.NEXT_PUBLIC_SOCKETFI_CLIENT_ID
    ```
  </Tab>
</Tabs>

<Warning>
  Never commit your `.env` or `.env.local` files to source control. Add them to `.gitignore`. Your Client ID ties requests to your registered application, so treat it like an API key.
</Warning>

## Initialize the SocketFi client

Create a dedicated file (e.g. `lib/socketfi.ts`) that exports a single shared client instance. Import this instance wherever you need SDK functionality.

```typescript lib/socketfi.ts theme={null}
import { SocketFi } from "@socketfi/react";

export const socketfi = new SocketFi({
  clientId: import.meta.env.VITE_SOCKETFI_CLIENT_ID,
  network: "TESTNET",
});
```

### Configuration options

<ParamField path="clientId" type="string" required>
  Your SocketFi application Client ID, obtained from the Developer Portal. This value identifies your app during hosted authentication and transaction approval flows.
</ParamField>

<ParamField path="network" type="&#x22;TESTNET&#x22; | &#x22;MAINNET&#x22;" required>
  The Stellar/Soroban network to target. Use `"TESTNET"` during development and `"MAINNET"` for production. Defaults to `"TESTNET"`.
</ParamField>

<ParamField path="brand.appName" type="string">
  The name of your application. Displayed on hosted authentication, sign-up, and transaction approval screens.
</ParamField>

<ParamField path="brand.primaryColor" type="string">
  A hex color code (e.g. `"#4F46E5"`) used as the primary accent color across hosted SocketFi screens.
</ParamField>

<ParamField path="onSuccess" type="(session: Session) => void">
  A global callback invoked after every successful authentication. Useful for updating application-level state without coupling the callback to a specific component.
</ParamField>

<ParamField path="onError" type="(error: Error) => void">
  A global callback invoked when any SDK flow fails. You should still use `try/catch` around individual calls for component-level error handling.
</ParamField>

### Full configuration example

```typescript lib/socketfi.ts theme={null}
import { SocketFi } from "@socketfi/react";

export const socketfi = new SocketFi({
  clientId: import.meta.env.VITE_SOCKETFI_CLIENT_ID,
  network: "TESTNET",

  brand: {
    appName: "Acme Pay",
    primaryColor: "#4F46E5",
  },

  onSuccess(session) {
    console.log("SocketFi session created:", session);
  },

  onError(error) {
    console.error("SocketFi error:", error);
  },
});
```

## Minimal working example

With the client initialized, you can authenticate a user from any component:

```typescript App.tsx theme={null}
import { socketfi } from "./lib/socketfi";

export default function App() {
  async function handleLogin() {
    try {
      const session = await socketfi.authenticate();
      console.log("Signed in:", session.userProfile.id);
    } catch (error) {
      console.error("Login failed:", error);
    }
  }

  return <button onClick={handleLogin}>Continue with SocketFi</button>;
}
```

<Tip>
  Switch `network` to `"MAINNET"` and update your environment variable when you're ready for production. No other code changes are required.
</Tip>