# SDK and runtime helpers

The SDK, its CLI and the integrations your application uses.

`@frontfriend/sdk@1.3.0` includes the `frontfriend` CLI, the MCP bridge and runtime helpers used by Frontfriend components.

## Choose what to adopt

For design contracts alone, install the SDK without a CSS or rendering dependency:

```bash
pnpm add @frontfriend/sdk@1.3.0
pnpm exec frontfriend setup --ff-id YOUR_DESIGN_SYSTEM_ID --adopt contracts
pnpm exec frontfriend design sync --contracts-only
```

Authenticate on the intended Studio endpoint first, as shown in [Installation](/docs/installation/). Contract sync reads the adopted snapshot when one exists; otherwise it reads working contracts. It does not approve or adopt a new snapshot. Use the [Connect workflow](/docs/design-skills/) to complete onboarding and activation.

For Frontfriend tokens and components, use Tailwind CSS 4 and React 19 or Vue 3 with a supported [primitive target](/docs/primitives/). The SDK runtime supports React 16.8–19; the selected component library determines the React version your application needs. TypeScript and `tw-animate-css` are optional peers: install them for component source operations and generated token styles. Contracts-only projects do not need them. A native shadcn base can keep its own tokens and sources; it does not require the Frontfriend runtime build plugin.

## Build integrations

| Import                       | Purpose                                                                                           |
| ---------------------------- | ------------------------------------------------------------------------------------------------- |
| `@frontfriend/sdk/vite`      | Add `frontfriend()` to a Vite configuration alongside its existing framework and Tailwind plugins |
| `@frontfriend/sdk/next`      | Wrap an existing Next.js configuration with `frontfriend(config)`                                 |
| `@frontfriend/sdk/theme.css` | Import generated theme assets after `tailwindcss` in application CSS                              |

`init` can wire supported Vite and Next.js object configurations. It preserves existing options and reports manual instructions for unsupported config shapes or existing plugin wrappers. Check the diff and keep the rest of your build configuration. See [Installation](/docs/installation/) for full examples.

## Merge utility classes

```ts
import { cn } from '@frontfriend/sdk/cn';

const classes = cn('px-2 py-1 bg-brand-mid', 'px-4');
```

`cn` combines conditional classes and resolves Tailwind utility conflicts. In this example, `px-4` replaces `px-2`.

## Read component configuration

```ts
import { config, ffdc, iconSet } from '@frontfriend/sdk';

const components = ffdc(config);
const button = ffdc(config, 'button');
```

The optional component name applies that component's shared normalization rules. The component form supports `badge`, `button`, `calendar`, `card`, `command`, `date-slider`, `input-group`, `popover`, `separator` and `spinner`. Check for an absent result and treat it as read-only. Change configuration in the Design System and adopt its published Release, rather than editing generated runtime data.

Canonical components already import the required SDK helpers. Keep the imports from your installed target; do not replace them with a different primitive's source. TypeScript declarations are included.

## Package updates and Design System updates

Pin the resolved SDK dependency in your package-manager lockfile. `frontfriend.lock.json` separately records adopted Design System data and a hash of each component file. Upgrading the SDK package does not automatically adopt a new component version. Use [Versions & releases](/docs/versioning/) and the [CLI reference](/docs/cli-reference/) to preview and apply changes.