Skip to main content

Installation & Setup

Prerequisites​

  • React 18+ — the SDK uses createContext, useReducer, and concurrent-mode features
  • Node 18+ — required by the Vite/TypeScript toolchain
  • A Nexla SDK Application — register one in your Nexla account under Settings → SDK Applications. This gives you an Application ID and auto-provisions a service key.

Install the Package​

npm
npm install @nexla/react-sdk
yarn
yarn add @nexla/react-sdk
pnpm
pnpm add @nexla/react-sdk

Optional: Styled Components Peer Dependencies​

The pre-built UI components (NexlaConnectButton, NexlaConnectModal, NexlaConnectorCard, NexlaSnackbar) are built on Radix UI primitives. These are listed as optional peer dependencies, so they are not installed automatically.

If you plan to use the styled components, install them now:

Styled peer dependencies
npm install @radix-ui/react-dialog @radix-ui/react-select @radix-ui/react-toast @radix-ui/react-accordion @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-tooltip

If you only need headless hooks (useNexlaConnect, useCredentials, useConnectorForm), you can skip this step entirely.

Verify the Installation​

src/App.tsx
import { NexlaConnectProvider } from '@nexla/react-sdk';

export default function App() {
  return (
    <NexlaConnectProvider
      serviceKey="YOUR_SERVICE_KEY"
      connectors={['CONNECTOR_KEY']}
      applicationId="YOUR_APPLICATION_ID"
      endUserId="YOUR_END_USER_ID"
    >
      <p>Nexla SDK loaded</p>
    </NexlaConnectProvider>
  );
}

Open your browser console — if there are no import errors you're good to go. Replace the placeholder values with your actual credentials from the Authentication step.

Securing Your Credentials​

Never hardcode your service key or application ID in source code or client-side bundles.

Service key security

Your service key is equivalent to an account credential. Store it as a secret in your backend (e.g. a secrets manager or environment variable on your server), and deliver it to the client only through an authenticated API call. Avoid exposing it in client-side environment variables — any VITE_, REACT_APP_, or NEXT_PUBLIC_ prefixed variable is bundled into client code and visible to end users.

For the best security, generate the short-lived JWT on your backend and pass it to the client so the raw service key never reaches the browser. See Authentication for details.

For local development and demo purposes, environment variables are a convenient option:

.env (local development only)
VITE_NEXLA_SERVICE_KEY=your_service_key_here
VITE_NEXLA_APPLICATION_ID=your_sdk_application_id_here

TypeScript Support​

The SDK ships its own type declarations — no @types/* package needed. Your tsconfig should include:

tsconfig.json (relevant excerpt)
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "jsx": "react-jsx"
  }
}

Next Steps​

  • Authentication — Configure your service key and provider options
  • Quick Start — Make your first credential connection in minutes