Provider Setup

The DropperProvider is the root component that enables all Dropper functionality in your React application. It provides context, configuration, and React Query integration.

Installation

First, install the React package:

npm install @dropper/react

Basic Setup

Wrap your application with DropperProvider:

import { DropperProvider } from '@dropper/react'

function App() {
  return (
    <DropperProvider publishableKey="pk_dropper_test_xxx">
      <YourApp />
    </DropperProvider>
  )
}

DropperProviderProps

interface DropperProviderProps {
  publishableKey: string    // Required: Your Dropper API key
  appId?: string           // Optional: App ID for multi-tenant apps
  baseUrl?: string         // Optional: Custom API URL
  queryClient?: QueryClient // Optional: Custom React Query client
  theme?: DropperTheme     // Optional: Theme customization
  children: ReactNode      // Your app components
}

Required Props

publishableKey

Your Dropper publishable API key:

<DropperProvider publishableKey="pk_dropper_test_xxx">
  <App />
</DropperProvider>

Optional Props

appId

Specify an app ID for multi-tenant applications:

<DropperProvider
  publishableKey="pk_dropper_test_xxx"
  appId="app_123"
>
  <App />
</DropperProvider>

baseUrl

Use a custom API endpoint:

<DropperProvider
  publishableKey="pk_dropper_live_xxx"
  baseUrl="https://api.dropper.com"
>
  <App />
</DropperProvider>

queryClient

Provide a custom React Query client:

import { QueryClient } from '@tanstack/react-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 10 * 60 * 1000, // 10 minutes
      retry: 2,
    },
  },
})

<DropperProvider
  publishableKey="pk_dropper_test_xxx"
  queryClient={queryClient}
>
  <App />
</DropperProvider>

theme

Customize component appearance:

<DropperProvider
  publishableKey="pk_dropper_test_xxx"
  theme={{
    primary: '#10b981',      // Green theme
    radius: 'lg',            // Large border radius
    mode: 'light',           // Light mode
  }}
>
  <App />
</DropperProvider>

React Query Integration

DropperProvider automatically sets up React Query with optimized defaults:

Default Configuration

{
  queries: {
    retry: 3,
    retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
    staleTime: 5 * 60 * 1000,  // 5 minutes
    refetchOnWindowFocus: false,
  },
  mutations: {
    retry: 1,
  },
}

Benefits

  • Automatic Caching: File and folder data is cached automatically
  • Background Refetching: Data stays fresh without user interaction
  • Optimistic Updates: UI updates immediately, syncs in background
  • Error Retry: Failed requests retry automatically with exponential backoff

Environment Variables

Store your API key securely:

Next.js

# .env.local
NEXT_PUBLIC_DROPPER_KEY=pk_dropper_test_xxx

<DropperProvider publishableKey={process.env.NEXT_PUBLIC_DROPPER_KEY!}>
  <App />
</DropperProvider>

Vite

# .env
VITE_DROPPER_KEY=pk_dropper_test_xxx

<DropperProvider publishableKey={import.meta.env.VITE_DROPPER_KEY}>
  <App />
</DropperProvider>

Create React App

# .env
REACT_APP_DROPPER_KEY=pk_dropper_test_xxx

<DropperProvider publishableKey={process.env.REACT_APP_DROPPER_KEY!}>
  <App />
</DropperProvider>

Complete Examples

Next.js App Router

// app/layout.tsx
import { DropperProvider } from '@dropper/react'
import '@dropper/react/dist/index.css'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <DropperProvider
          publishableKey={process.env.NEXT_PUBLIC_DROPPER_KEY!}
          theme={{ primary: '#3b82f6' }}
        >
          {children}
        </DropperProvider>
      </body>
    </html>
  )
}

Next.js Pages Router

// pages/_app.tsx
import type { AppProps } from 'next/app'
import { DropperProvider } from '@dropper/react'
import '@dropper/react/dist/index.css'

export default function App({ Component, pageProps }: AppProps) {
  return (
    <DropperProvider publishableKey={process.env.NEXT_PUBLIC_DROPPER_KEY!}>
      <Component {...pageProps} />
    </DropperProvider>
  )
}

Vite + React

// main.tsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import { DropperProvider } from '@dropper/react'
import '@dropper/react/dist/index.css'
import App from './App'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <DropperProvider publishableKey={import.meta.env.VITE_DROPPER_KEY}>
      <App />
    </DropperProvider>
  </React.StrictMode>
)

Create React App

// index.tsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import { DropperProvider } from '@dropper/react'
import '@dropper/react/dist/index.css'
import App from './App'

const root = ReactDOM.createRoot(document.getElementById('root')!)
root.render(
  <React.StrictMode>
    <DropperProvider publishableKey={process.env.REACT_APP_DROPPER_KEY!}>
      <App />
    </DropperProvider>
  </React.StrictMode>
)

Multiple Providers

For multi-tenant applications, use multiple providers:

function App() {
  const [currentTenant, setCurrentTenant] = useState('tenant1')
  
  const tenantKeys = {
    tenant1: 'pk_dropper_test_tenant1_xxx',
    tenant2: 'pk_dropper_test_tenant2_xxx',
  }
  
  return (
    <DropperProvider
      key={currentTenant}
      publishableKey={tenantKeys[currentTenant]}
      appId={currentTenant}
    >
      <YourApp />
    </DropperProvider>
  )
}

Import Styles

Don't forget to import the CSS:

import '@dropper/react/dist/index.css'

Or in your global CSS:

@import '@dropper/react/dist/index.css';

TypeScript Support

The provider is fully typed:

import type { DropperProviderProps } from '@dropper/react'

const config: DropperProviderProps = {
  publishableKey: 'pk_dropper_test_xxx',
  theme: {
    primary: '#3b82f6',
    radius: 'md',
  },
}

<DropperProvider {...config}>
  <App />
</DropperProvider>

Error Handling

Handle provider initialization errors:

function App() {
  const [error, setError] = useState<Error | null>(null)
  
  if (error) {
    return <div>Failed to initialize Dropper: {error.message}</div>
  }
  
  if (!process.env.NEXT_PUBLIC_DROPPER_KEY) {
    return <div>Missing DROPPER_KEY environment variable</div>
  }
  
  return (
    <DropperProvider publishableKey={process.env.NEXT_PUBLIC_DROPPER_KEY}>
      <YourApp />
    </DropperProvider>
  )
}

Best Practices

1. Place Provider High in Component Tree

Wrap your entire app or layout:

// Good: Wrap entire app
<DropperProvider>
  <App />
</DropperProvider>

// Avoid: Wrapping individual pages
<Page>
  <DropperProvider>
    <FileUpload />
  </DropperProvider>
</Page>

2. Use Environment Variables

Never hardcode API keys:

// Good
<DropperProvider publishableKey={process.env.NEXT_PUBLIC_DROPPER_KEY!} />

// Bad
<DropperProvider publishableKey="pk_dropper_test_xxx" />

3. Import Styles Once

Import CSS in your root file:

// app/layout.tsx or main.tsx
import '@dropper/react/dist/index.css'

4. Customize Theme

Provide consistent theming:

<DropperProvider
  publishableKey={key}
  theme={{
    primary: '#your-brand-color',
    radius: 'md',
  }}
>
  <App />
</DropperProvider>

What's Provided

The provider makes available:

  • DropperClient: Core API client
  • React Query: Automatic data fetching and caching
  • Theme: Consistent styling across components
  • Context: Shared configuration for all components

Next Steps