Client configuration
Shared API settings, optional token providers, and custom fetch implementations.
Most clients share these base settings:
type CarpoBaseConfig = {
apiUrl: string
projectId: string
environment?: 'production' | 'development'
}apiUrl must be an absolute HTTP or HTTPS origin without a path, query string, or fragment. For example, use https://api.carpo.dev, not https://api.carpo.dev/api.
Optional request settings
| Option | Applies to | Description |
|---|---|---|
fetch | API clients | Use a custom fetch implementation for Carpo API calls |
uploadFetch | Storage clients | Use a custom fetch implementation for signed object transfers |
getAccessToken | Client and Database clients | Return a Project Auth JWT or user scoped API key |
getAccessTokenCacheKey | React Database and Storage clients | Return a stable, non secret identity for query cache isolation |
webSocket | Database and Realtime clients | Create a WebSocket in custom runtimes or tests |
signal | Request methods | Abort an API request or signed transfer |
Browser clients use credentials with cookies by default. For token based Database or Storage calls, the access token getter can return a string, null, or a promise of either. A getter failure is reported as a CarpoApiError with code ACCESS_TOKEN_ERROR.
Better Auth settings
The client Auth factories accept Better Auth's fetchOptions and disableDefaultFetchPlugins. The React Auth factory also accepts sessionOptions. Pass oneTapClientId only when the Project Auth environment has Google One Tap enabled. Additional plugins must match server plugins that are active for the same Project Auth instance.
Server specific settings
createCarpoServerClient() accepts optional database, storage, and functions settings. Database settings follow @libsql/client's Config. Storage settings require a bucketId and project API key provider. Functions settings can supply getAccessToken and a custom fetch.
createCarpoServerRequestClient() requires a Fetch API Request. It accepts optional databaseId, storageBucketId, a custom fetch, oneTapClientId, and Better Auth client plugins. The incoming identity headers are forwarded only to the configured Carpo API origin.