Skip to main content

​
Quick Start

1

Create Your React Project

Choose your preferred bundler:
npm create vite@latest my-react-app -- --template react
2

Install Dependencies

cd my-react-app
npm install
npm install @frankieone/one-sdk
3

Start Development

npm run dev  # for Vite
# or
npm start    # for Create React App

​
Configuration

Add this configuration to your vite.config.js:
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  define: {
    "process.env": {},
  },
});
Based on your build tool and/or framework, you may have a different prefix to the environment variables, e.g. if you’re using Vite, your env prefix is going to be “VITE_” instead of “REACT_APP_”
Create a .env file with your credentials:
REACT_APP_CUSTOMER_ID=your_customer_id
REACT_APP_API_KEY=your_api_key
REACT_APP_CHILD_ID=your_child_id    # optional

​
Integration with React

​
Custom Hook Implementation

import OneSdk from "@frankieone/one-sdk";
import { useEffect, useRef, useState } from "react";

interface OneSDKConfig {
  mode: 'development' | 'production';
  recipe: {
    form: {
      provider: {
        name: string;
      };
    };
  };
}

interface UseOneSDKProps {
  config?: OneSDKConfig;
}

const useOneSDK = ({ config }: UseOneSDKProps) => {
  const [oneSDKInstance, setOneSDKInstance] = useState(null);
  const [error, setError] = useState(null);
  const [loading, setLoading] = useState(false);
  const initializedRef = useRef(false);

  const generateToken = async () => {
    try {
      const tokenRawAsync = await fetch(
        "https://backend.latest.frankiefinancial.io/auth/v2/machine-session",
        {
          method: "POST",
          headers: {
            authorization: `machine ${btoa(
              `${process.env.REACT_APP_CUSTOMER_ID}:${process.env.REACT_APP_API_KEY}`
            )}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            permissions: {
              preset: "one-sdk",
              reference: `demo-${new Date().toISOString()}`,
            },
          }),
        }
      );
      return await tokenRawAsync.json();
    } catch (error) {
      setError(error.message);
      return null;
    }
  };

  const generateOneSDKInstance = async () => {
    setLoading(true);
    try {
      const token = await generateToken();
      if (!token) return;

      const defaultConfig = {
        mode: "development",
        recipe: {
          form: {
            provider: {
              name: "react",
            },
          },
        },
      };

      const oneSDKInit = await OneSdk({
        session: token,
        ...(config || defaultConfig),
      });

      setOneSDKInstance(oneSDKInit);
    } catch (error) {
      setError(error.message);
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    if (!initializedRef.current) {
      generateOneSDKInstance();
      initializedRef.current = true;
    }
  }, [config]);

  return { oneSDKInstance, error, loading };
};

export default useOneSDK;

​
Best Practices

Error Handling

  • Always handle token generation errors - Provide meaningful error messages
  • Implement proper error boundaries

Security

  • Never expose API keys in client-side code
  • Use environment variables
  • Implement proper token management

Performance

  • Use React.memo for expensive renders
  • Implement proper cleanup in useEffect
  • Avoid unnecessary re-renders

State Management

  • Use proper state management patterns
  • Implement loading states
  • Handle edge cases properly
Remember to handle token expiration and implement proper refresh mechanisms in a production environment.

​
Troubleshooting

  • Token Generation Fails: Verify your credentials and network connection
  • SDK Initialization Errors: Check configuration object format
  • Component Re-rendering: Implement proper memoization
  • Vite: Ensure variables are prefixed with VITE_
  • Create React App: Ensure variables are prefixed with REACT_APP_
  • Development: Verify .env file location

​
Next Steps

Sample Implementation

View complete implementation examples

API Reference

Explore the complete API documentation