React Plaid Link Integration

Common errors

• Plaid Link exited: { error_code: 'INVALID_LINK_TOKEN', error_type: 'ITEM_ERROR', ... }

  cause The `link_token` provided to the `usePlaidLink` hook is invalid, expired, or malformed, preventing Plaid Link from initializing correctly.
  fix Verify your backend is generating a valid, non-expired `link_token` using the Plaid API and that it's correctly passed to the `usePlaidLink` hook. Plaid Link tokens typically expire after 30 minutes, so fetch a fresh one for each new Link session.

• Cannot read properties of undefined (reading 'open') OR open is not a function

  cause You are attempting to call the `open()` function returned by `usePlaidLink` before the Plaid Link script has fully loaded and initialized, or `open` was not correctly destructured.
  fix Always check the `ready` boolean flag returned by `usePlaidLink` before calling `open()`. For example, `disabled={!ready}` on your button. Also, ensure `const { open, ready } = usePlaidLink(...)` correctly destructures the hook's return value.

• Invariant Violation: Invalid hook call. Hooks can only be called inside of the body of a function component.

  cause The `usePlaidLink` hook is being called outside of a functional React component or a custom hook, which violates React's Rules of Hooks.
  fix Ensure `usePlaidLink` is invoked directly within the top level of a functional React component or another custom hook, and not inside loops, conditions, or nested functions.

• TypeError: Cannot destructure property 'open' of 'Object(...)' as it is null.

  cause The `usePlaidLink` hook might be returning `null` or `undefined` in some edge cases (e.g., critical initialization failure, or if React context is misconfigured, though less common for this specific error).
  fix Check for errors during `usePlaidLink` initialization (e.g., `error` return value). Ensure your React environment is set up correctly and no other issues are preventing the hook from returning its expected object. This error is rare and often points to a deeper React environment problem.

Warnings

• breaking Major version updates (e.g., from v3 to v4) often introduce breaking changes, particularly in API signatures and the preferred integration approach (e.g., moving from class components to hooks). Existing implementations might require significant refactoring.
  Fix: Consult the official GitHub release notes and migration guides provided by Plaid for `react-plaid-link` when upgrading across major versions to understand specific changes and required updates.
• gotcha The `link_token` is a critical security credential that MUST be generated securely on your server-side application using the Plaid API. It should never be generated client-side directly within your React application due to security risks and API limitations.
  Fix: Implement a secure backend endpoint (e.g., Node.js, Python, Ruby) to call the Plaid API's `/link/token/create` endpoint and return the generated `link_token` to your frontend. Your React app should then fetch this token before initializing `usePlaidLink`.
• gotcha When handling OAuth flows, Plaid Link often needs to be opened immediately upon page load (e.g., after a redirect) rather than waiting for a user interaction. Incorrect handling can lead to broken OAuth experiences.
  Fix: Utilize a `React.useEffect` hook to conditionally call `open()` when the `ready` flag from `usePlaidLink` becomes `true` and a `receivedRedirectUri` is present, as shown in the library's OAuth examples.
• gotcha Ensure your project's `react` and `react-dom` versions are compatible with the `react-plaid-link` peer dependencies (`^16.8.0 || ^17 || ^18 || ^19`). Incompatible peer dependencies can lead to runtime errors, hook issues, or build failures, even if the package installs successfully.
  Fix: Verify the `react` and `react-dom` versions in your `package.json` file. Update them to a compatible range if necessary and run `npm install` or `yarn install` to ensure correct resolution of peer dependencies.

Install

• npm install react-plaid-link npm
• yarn add react-plaid-link yarn
• pnpm add react-plaid-link pnpm

Imports

• usePlaidLink
  wrong:

  const { usePlaidLink } = require('react-plaid-link');

  correct:

  import { usePlaidLink } from 'react-plaid-link';

  This is the primary hook for integrating Plaid Link. It's a named export, not a default export. CommonJS `require` is generally not supported in modern React setups.
• PlaidLinkOnSuccessMetadata
  wrong:

  import { PlaidLinkOnSuccessMetadata } from 'react-plaid-link';

  correct:

  import type { PlaidLinkOnSuccessMetadata } from 'react-plaid-link';

  For importing types, use `import type` for clarity and better tree-shaking/bundler optimizations, especially if the type is not also a runtime value.
• PlaidLinkOnExitMetadata
  wrong:

  import { PlaidLinkOnExitMetadata, PlaidLinkError } from 'react-plaid-link';

  correct:

  import type { PlaidLinkOnExitMetadata, PlaidLinkError } from 'react-plaid-link';

  Similar to other types, prefer `import type` when only using the imported symbols for type annotations in TypeScript.

Quickstart

Demonstrates how to integrate Plaid Link using the `usePlaidLink` hook, fetching a `link_token` (simulated), and handling success, exit, and loading callbacks. It correctly disables the button until Link is ready.

import React, { useEffect, useState } from 'react';
import { usePlaidLink, PlaidLinkOnSuccessMetadata, PlaidLinkOnExitMetadata, PlaidLinkError } from 'react-plaid-link';

const MyPlaidLinkComponent: React.FC = () => {
  // In a real application, the link_token is generated server-side.
  // For this example, replace '<YOUR_GENERATED_LINK_TOKEN>' with a valid token
  // fetched from your backend. If you don't have one, Plaid offers a quickstart
  // for generating development tokens.
  const [linkToken, setLinkToken] = useState<string | null>(null);

  useEffect(() => {
    // Simulate fetching link_token from your backend
    const fetchLinkToken = async () => {
      try {
        // Example: const response = await fetch('/api/create-link-token');
        // const data = await response.json();
        // setLinkToken(data.link_token);
        // Using a placeholder for demonstration purposes
        setLinkToken('link-development-YOURPLAIDCLIENTID'); // Replace with a real token!
      } catch (error) {
        console.error('Error fetching link token:', error);
      }
    };
    fetchLinkToken();
  }, []);

  const { open, ready, error } = usePlaidLink({
    token: linkToken,
    onSuccess: (public_token: string, metadata: PlaidLinkOnSuccessMetadata) => {
      // Send the public_token to your server to exchange for an access_token
      console.log('Plaid Link successful! Public Token:', public_token, 'Metadata:', metadata);
      alert(`Public token received: ${public_token}`);
      // Typically, you'd send this to your backend:
      // fetch('/api/exchange_public_token', {
      //   method: 'POST',
      //   headers: { 'Content-Type': 'application/json' },
      //   body: JSON.stringify({ public_token, metadata }),
      // });
    },
    onExit: (error: PlaidLinkError | null, metadata: PlaidLinkOnExitMetadata) => {
      console.error('Plaid Link exited:', error, 'Metadata:', metadata);
    },
    onEvent: (eventName: string, metadata: any) => {
      console.log('Plaid Link event:', eventName, metadata);
    },
    onLoad: () => {
      console.log('Plaid Link loaded.');
    }
  });

  return (
    <div>
      <h1>Connect to Plaid</h1>
      <button onClick={() => open()} disabled={!ready || !linkToken}>
        Connect Bank Account
      </button>
      {error && <p style={{ color: 'red' }}>Error during Plaid Link initialization: {error.message}</p>}
      {!linkToken && <p>Loading Plaid Link token...</p>}
      {!ready && linkToken && <p>Plaid Link is loading and not yet ready to open.</p>}
    </div>
  );
};

export default MyPlaidLinkComponent;