Configuration

Learn how to configure the DocCentral for your application's specific needs.

Basic Configuration

The SDK is configured through the DocCentralProvider component. At minimum, you need to provide your API key:

import { DocCentralProvider } from '@doccentral/react';

function App() {
  return (
    <DocCentralProvider apiKey="pk_live_your_api_key_here">
      <YourApplication />
    </DocCentralProvider>
  );
}

Provider Props

The DocCentralProvider accepts the following configuration options:

Prop	Type	Default	Description
`apiKey`*	`string`	-	Your DocCentral API key. Use publishable keys (pk_) for client-side.
`apiBaseUrl`	`string`	"https://api.doccentral.io"	Base URL for API requests. Override for self-hosted or staging environments.
`debug`	`boolean`	false	Enable debug mode for detailed console logging.
`timeout`	`number`	30000	Request timeout in milliseconds.
`customHeaders`	`Record<string, string>`	{}	Custom headers to include in all API requests.
`onReady`	`() => void`	-	Callback fired when SDK initialization completes successfully.
`onError`	`(error: string) => void`	-	Callback fired when SDK initialization fails.

Full Configuration Example

app/providers.tsxtypescript

1'use client';
2
3import { DocCentralProvider } from '@doccentral/react';
4import { ReactNode } from 'react';
5
6interface ProvidersProps {
7  children: ReactNode;
8}
9
10export function Providers({ children }: ProvidersProps) {
11  const handleReady = () => {
12    console.log('DocCentral initialized successfully');
13    // You can trigger analytics, update UI state, etc.
14  };
15
16  const handleError = (error: string) => {
17    console.error('DocCentral initialization failed:', error);
18    // Handle error - show user notification, redirect, etc.
19  };
20
21  return (
22    <DocCentralProvider
23      apiKey={process.env.NEXT_PUBLIC_DOCCENTRAL_API_KEY!}
24      apiBaseUrl={process.env.NEXT_PUBLIC_DOCCENTRAL_API_URL}
25      debug={process.env.NODE_ENV === 'development'}
26      timeout={60000} // 60 seconds for large documents
27      customHeaders={{
28        'X-Client-Version': '1.0.0',
29        'X-Client-Platform': 'web',
30      }}
31      onReady={handleReady}
32      onError={handleError}
33    >
34      {children}
35    </DocCentralProvider>
36  );
37}

Environment-Based Configuration

Configure different settings for development, staging, and production:

lib/doccentral-config.tstypescript

type Environment = 'development' | 'staging' | 'production';

interface DocCentralConfig {
  apiKey: string;
  apiBaseUrl: string;
  debug: boolean;
  timeout: number;
}

const configs: Record<Environment, DocCentralConfig> = {
  development: {
    apiKey: process.env.NEXT_PUBLIC_DOCCENTRAL_API_KEY_DEV!,
    apiBaseUrl: 'http://localhost:3001',
    debug: true,
    timeout: 60000,
  },
  staging: {
    apiKey: process.env.NEXT_PUBLIC_DOCCENTRAL_API_KEY_STAGING!,
    apiBaseUrl: 'https://staging-api.doccentral.io',
    debug: true,
    timeout: 30000,
  },
  production: {
    apiKey: process.env.NEXT_PUBLIC_DOCCENTRAL_API_KEY!,
    apiBaseUrl: 'https://api.doccentral.io',
    debug: false,
    timeout: 30000,
  },
};

export function getDocCentralConfig(): DocCentralConfig {
  const env = (process.env.NEXT_PUBLIC_ENV || 'development') as Environment;
  return configs[env];
}

Initialization Flow

When the SDK initializes, it follows this sequence:

Mount: Provider mounts and begins initialization
Validate API Key Format: Checks if key starts with pk_ or sk_
API Validation: Sends request to /sdk/validate-key endpoint
Store Organization Info: Caches organization ID, name, and scopes
Ready: Calls onReady callback (if provided)

Initialization State

Use the useSDK hook to access initialization state:

isValidating - true while validating API key
isInitialized - true after successful initialization
validationError - error message if validation failed

Handling Initialization States

'use client';

import { useSDK } from '@doccentral/react';

function DocumentApp() {
  const { isValidating, isInitialized, validationError } = useSDK();

  // Show loading while validating
  if (isValidating) {
    return (
      <div className="flex items-center justify-center h-64">
        <div className="animate-spin h-8 w-8 border-4 border-blue-500 border-t-transparent rounded-full" />
        <span className="ml-3">Initializing DocCentral...</span>
      </div>
    );
  }

  // Show error if validation failed
  if (validationError) {
    return (
      <div className="bg-red-50 border border-red-200 rounded-lg p-4">
        <h3 className="text-red-800 font-semibold">SDK Initialization Failed</h3>
        <p className="text-red-700 mt-1">{validationError}</p>
        <button 
          onClick={() => window.location.reload()} 
          className="mt-3 text-red-600 underline"
        >
          Try Again
        </button>
      </div>
    );
  }

  // Render application when ready
  if (isInitialized) {
    return <YourDocumentComponents />;
  }

  return null;
}

Custom API Base URL

For self-hosted deployments or staging environments:

<DocCentralProvider
  apiKey="pk_live_..."
  apiBaseUrl="https://doccentral.your-company.com/api"
>
  {children}
</DocCentralProvider>

CORS Configuration

If using a custom API URL, ensure CORS is properly configured on your server to allow requests from your application's domain.

Next Steps

Environment Variables

Learn about all environment variables used by the SDK.

Learn more

DocCentralProvider Reference

Complete API reference for the provider component.

Learn more

Authentication

Learn about API key management and authentication.

Learn more