---
title: SDK overview
description: "@coduck/sdk gives your deployed app auth, forms, file storage, and analytics with zero config."
category: sdk
order: 1
agent: "@coduck/sdk reference. Auto-installed + env-configured at deploy. Modules: root client (coduck.meta), @coduck/sdk/server (cookie auth: getSession/signInWithPassword/signUpWithPassword/signOut), @coduck/sdk/client (useUser hook), @coduck/sdk/auth (low-level AuthClient), @coduck/sdk/forms, @coduck/sdk/storage, @coduck/sdk/analytics. Server modules need CODUCK_API_KEY; auth needs CODUCK_AUTH_KEY (deploy-only)."
---

# SDK overview

`@coduck/sdk` is the official SDK for apps deployed on CoDuck. It gives your project **auth, forms, file storage, and analytics** backed by the platform — no separate backend to stand up.

When CoDuck generates and deploys your project, the SDK is already installed and configured. You just import the module you need.

## Install

In a CoDuck-deployed project the SDK and its env vars are wired up automatically. To add it to a project by hand:

```bash
npm install @coduck/sdk
```

## How it configures itself

At deploy time CoDuck injects these env vars, and the SDK reads them automatically — you rarely construct a client yourself:

| Variable | Scope | Purpose |
|---|---|---|
| `CODUCK_API_KEY` | server only | Authenticates server-side calls (forms read, storage, analytics, project meta) |
| `CODUCK_AUTH_KEY` | server only | Tenant key for auth. **Only injected on deploy** — auth does not work in the in-editor preview |
| `CODUCK_PROJECT_ID` / `NEXT_PUBLIC_CODUCK_PROJECT_ID` | server / browser | Identifies your project |
| `CODUCK_API_URL` / `NEXT_PUBLIC_CODUCK_API_URL` | server / browser | SDK API base (defaults to `https://api.coduck.ai/sdk`) |

> **Server vs. browser.** Most SDK calls require `CODUCK_API_KEY`, so they must run on the server (route handlers, server actions, server components). The only browser-safe call is `forms.submit()`. Auth additionally needs `CODUCK_AUTH_KEY`, which means **sign-in only works once the project is deployed**, not in the live preview.

## The client

```ts
import { coduck } from '@coduck/sdk';

const meta = await coduck.meta();
// → { projectId, projectName, deploymentSubdomain, deploymentStatus, apiKeyPrefix }
```

Or construct one explicitly (tests, scripts, non-Next runtimes):

```ts
import { CoDuck } from '@coduck/sdk';

const c = new CoDuck({
  apiKey: process.env.CODUCK_API_KEY,
  apiUrl: 'https://api.coduck.ai/sdk',
  projectId: process.env.CODUCK_PROJECT_ID,
});
```

## Modules

| Import | What it does |
|---|---|
| [`@coduck/sdk/server`](/docs/sdk/auth#server-helpers) | Cookie-based auth for Next.js server code |
| [`@coduck/sdk/client`](/docs/sdk/auth#client-hook) | `useUser()` React hook |
| [`@coduck/sdk/auth`](/docs/sdk/auth#low-level-client) | Low-level auth client (tokens) |
| [`@coduck/sdk/forms`](/docs/sdk/forms) | Capture + read form submissions |
| [`@coduck/sdk/storage`](/docs/sdk/storage) | Per-project file storage |
| [`@coduck/sdk/analytics`](/docs/sdk/analytics) | Custom event tracking |

## Errors

SDK calls throw `CoDuckError` (with a `code`) on failure — e.g. `NO_API_KEY`, `NO_AUTH_KEY`, `NO_PROJECT_ID`, or `HTTP_<status>`:

```ts
import { CoDuckError } from '@coduck/sdk';

try {
  await coduck.meta();
} catch (err) {
  if (err instanceof CoDuckError) console.error(err.code, err.message);
}
```