---
name: aircall-blocks/setup
description: >
  Set up @aircall/blocks in an app already (or simultaneously) adopting @aircall/ds.
  Load when wiring blocks compositions (DashboardPage, DashboardPageHeader,
  DashboardSidebar, empty states, form fields) into a project: installing the
  package, importing its precompiled globals.css after the DS bundle, and the DS
  providers it relies on. Covers both standalone apps and module-federation
  consumers where the host already loads DS globals.
type: core
library: aircall-blocks
requires:
  - aircall-ds/setup
sources:
  - "aircall/hydra:docs/migration-guides/tractor-to-ds/00-setup.md"
  - "aircall/hydra:packages/blocks/package.json"
---

# Setting up @aircall/blocks

This skill builds on aircall-ds/setup. Read it first: blocks compose `@aircall/ds`
primitives and depend on DS being installed and its `globals.css` imported.

## Setup

Install blocks alongside DS:

```bash
pnpm add @aircall/blocks @aircall/ds @aircall/react-icons
```

How you import the CSS depends on whether your app is standalone or a
**module-federation consumer** whose host already loads DS globals.

### Standalone app (owns its own Preflight)

`@aircall/blocks/globals.css` is a **delta build** — it contains only blocks-specific tokens
and utility classes; it does NOT bundle DS. Import DS globals first (Preflight + DS tokens +
DS utilities), then blocks globals (blocks-specific delta). Always import in this order.

```css
/* style.css */
@layer theme, base, components, utilities;
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);
@import '@aircall/ds/globals.css';
@import '@aircall/blocks/globals.css';

@source './src/**/*.{ts,tsx}';
```

Or from a JS/TS entry (no custom Tailwind classes of your own):

```tsx
// main.tsx
import '@aircall/ds/globals.css';
import '@aircall/blocks/globals.css';
```

#### Single-compilation via `theme.css` (recommended for DS + blocks)

The two precompiled bundles above each re-emit the same Tailwind utilities into `@layer
utilities`; at equal specificity the last-loaded bundle can clobber the other's responsive
variants (e.g. blocks' plain `.text-base` beating DS's `md:text-sm` on `Textarea`), and **no
import order fixes it**. To avoid this, import the directive-preserving `theme.css` artifacts
(tokens + dark variant + reset + keyframes only — **no** Preflight, **no** utilities) and let a
single Tailwind pass generate the utilities by `@source`-scanning the library dist:

```css
/* style.css */
@import 'tailwindcss';                      /* consumer owns the single Preflight + engine */
@import '@aircall/ds/theme.css';
@import '@aircall/blocks/theme.css';
@source '../node_modules/@aircall/ds/dist/index.js';
@source '../node_modules/@aircall/blocks/dist/index.js';
```

Here the full `@import 'tailwindcss'` is **correct** (unlike the `globals.css` case) because
`theme.css` ships no Preflight/utilities. `globals.css` still ships unchanged for precompiled-
bundle consumers. Full rationale: `packages/ds/docs/single-compilation-theme-css.md`.

### Module-federation consumer (host already owns the Preflight)

When your app is a remote loaded inside a host that already imports DS globals
(e.g. `dashboard-v4`), **do not re-import DS or blocks globals** in your own
CSS. The host's single Preflight applies to the whole document — re-importing
it duplicates the base reset and causes cascade conflicts (see Common Mistakes
below).

Import only the Tailwind layers you need for your own authored utility classes:

```css
/* style.css */
@layer theme, base, components, utilities;
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);

@source './**/*.{ts,tsx}';
```

> **Note on the `.css` extension**: `@import "tailwindcss/theme"` (no `.css`)
> silently fails in webpack/Rsbuild PostCSS pipelines — the extension is required.

Blocks render under the same DS providers — there is no blocks-specific provider; mount the
DS root providers from `aircall-ds/setup` as needed (`ThemeProvider` / `TooltipProvider` /
`Toaster`). Two DS providers matter specifically once you use blocks:

- **`DsI18nProvider`** (from `@aircall/ds`) — importing `@aircall/blocks` runs
  `import './i18n/register'` at module load (`packages/blocks/src/index.ts`), which registers
  a `blocks` namespace on DS's shared i18next instance. Block strings render localized off the
  self-initialized DS singleton even without a provider; to make DS + blocks strings follow the
  **user's** language (and track switches), mount `DsI18nProvider` **as a descendant of your
  react-i18next `I18nextProvider`** and pass the active language (`language={i18n.language}`).
  Use **either** `DsI18nProvider` **or** `syncDsLanguage(i18n)`, never both. See
  `aircall-ds/setup` for the full provider tree and nesting order.
- **`NotificationQueueProvider` + `NotificationSlot`** (from `@aircall/ds`) — needed only if
  your block compositions surface notifications/banners: wrap `NotificationQueueProvider`
  (props `{ children }`) above any notification caller, and render a `NotificationSlot
  slot="page"` (props `{ slot: string; className? }`) inside it.

Source: `packages/blocks/src/index.ts`; `@aircall/ds` `DsI18nProvider` / `NotificationQueueProvider`.

## Core Patterns

### Use a block composition

```tsx
import {
  DashboardPageHeader,
  DashboardPageHeaderTitle,
} from '@aircall/blocks';

function CampaignsHeader() {
  return (
    <DashboardPageHeader>
      <DashboardPageHeaderTitle size="lg">Campaigns</DashboardPageHeaderTitle>
    </DashboardPageHeader>
  );
}
```

## Common Mistakes

### HIGH — Re-importing DS/blocks globals in a module-federation consumer

Wrong — in a consumer whose host already loads DS globals:

```css
@import 'tailwindcss';
@import '@aircall/ds/globals.css';
@import '@aircall/blocks/globals.css';
```

Correct — consumer owns only its own utilities, no Preflight:

```css
@layer theme, base, components, utilities;
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);
@source './**/*.{ts,tsx}';
```

In a module-federation setup, CSS from each remote lands in the **same document**
as the host. DS globals ships a Preflight (`@layer base { * { border-color: var(--color-border); } }`)
that sets the token-based border color globally. If the consumer also imports DS globals
(or the full `@import 'tailwindcss'`), it emits a second `@layer base` reset. Because
webpack/Rsbuild emits deep dependencies first and the consumer's own CSS last, the
consumer's Preflight (`border-color: currentColor`) ends up later in the output — and
later wins. DS component borders (Card, etc.) lose their token color and become invisible.

### HIGH — Importing blocks globals before DS globals (or omitting DS globals)

Wrong — wrong order, or omitting DS globals:

```css
@import '@aircall/blocks/globals.css';
@import '@aircall/ds/globals.css';
```

```css
/* missing DS globals entirely */
@import '@aircall/blocks/globals.css';
```

Correct — DS globals first, then blocks globals:

```css
@import '@aircall/ds/globals.css';
@import '@aircall/blocks/globals.css';
```

`@aircall/blocks/globals.css` is a delta build — it contains only blocks-specific tokens
and utility classes. It depends on DS globals being loaded first to provide Preflight and
DS token definitions. Loading blocks before DS means DS's base reset (`border-color:
var(--color-border)`) lands after blocks and within the same `@layer base`, and component
tokens like `--background` and `--border` may not be defined when blocks tries to use them.

Source: aircall/hydra:docs/migration-guides/tractor-to-ds/00-setup.md (§3)

### MEDIUM — Using bare specifiers without `.css` in Rsbuild/webpack

Wrong:

```css
@import 'tailwindcss/theme';
@import 'tailwindcss/utilities';
```

Correct:

```css
@import 'tailwindcss/theme.css';
@import 'tailwindcss/utilities.css';
```

The bare form (no `.css`) silently produces no output in webpack/Rsbuild PostCSS
pipelines — classes like `flex`, `gap-4`, `text-sm` are never generated. Always
use the `.css` extension when splitting Tailwind imports.

### MEDIUM — Installing @aircall/blocks without @aircall/ds

Wrong:

```bash
pnpm add @aircall/blocks
```

Correct:

```bash
pnpm add @aircall/blocks @aircall/ds
```

Blocks import from `@aircall/ds` at runtime; without it the blocks barrel fails to resolve its peer and the build breaks.

Source: aircall/hydra:packages/blocks/package.json (peerDependencies)

### MEDIUM — Expecting a separate BlocksProvider

Wrong: searching for a `BlocksProvider` to mount.

Correct: blocks render under the DS providers from aircall-ds/setup; mount those, not a blocks-specific provider.

There is no blocks-specific provider; assuming one wastes time and produces dead wiring.

Source: aircall/hydra:docs/migration-guides/tractor-to-ds/00-setup.md (§4)