К основному содержанию
правило CX Codex

async-suspense-boundaries — правило для Claude Code

Правило async-suspense-boundaries направляет Claude Code выносить загрузку данных в отдельные компоненты с Suspense, чтобы каркас страницы рендерился без задержек.

MIT ★ 7 191 обновлён 2026-10-24

Установить в Claude Code · Вручную: положить файлы Все способы и платформы ↓
.claude/rules/async-suspense-boundaries.md
Открыть на GitHub

Что делает async-suspense-boundaries

Правило инструктирует модель не блокировать разметку страницы через await в родительском компоненте. Вместо ожидания данных на верхнем уровне агент оборачивает асинхронные блоки в границы Suspense, отдавая сайдбар, шапку и футер сразу.

В описании даны два базовых паттерна: перенос await в дочерний компонент вроде DataDisplay и передача неразрешённого промиса через пропсы сразу нескольким компонентам с распаковкой через хук use. Второй вариант предотвращает повторные запросы, если данные нужны двум соседним блокам.

Шаблон ускоряет первую отрисовку, но повышает риск сдвига макета (layout shift) при появлении контента. Для критичных к поисковой оптимизации блоков на первом экране и быстрых легковесных запросов правило советует отказаться от Suspense.

Какие задачи решает

  • ускорить первичную отрисовку страницы при долгих сетевых запросах
  • изолировать блокирующий await внутри дочерних компонентов интерфейса
  • разделить один промис между несколькими компонентами через хук use
  • предотвратить задержку шапки и навигации из-за медленного API

Примеры запросов агенту

  • Отрефактори Page.tsx с использованием Suspense, чтобы шапка и футер не ждали загрузки данных
  • Переделай компонент профиля так, чтобы промис fetchData() читался через use() в дочерних блоках
  • Проверь разметку каталога и вынеси долгие сетевые вызовы под границы Suspense

Как установить async-suspense-boundaries

Вручную: положить файлы

.claude/rules/async-suspense-boundaries.md

Поле paths во frontmatter ограничивает файлы

По шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать

Вопросы об async-suspense-boundaries

Как установить async-suspense-boundaries в Claude Code?

Сохраните текст правила в корень проекта по пути .claude/rules/async-suspense-boundaries.md.

Что делает правило async-suspense-boundaries?

Оно запрещает блокировать общую разметку через await на верхнем уровне и требует выносить компоненты с загрузкой в Suspense с фолбэками.

Когда не стоит применять этот паттерн?

Паттерн не подходит, когда данные влияют на геометрию родительской сетки, контент критичен для поисковиков на первом экране или запрос отрабатывает слишком быстро для накладных расходов Suspense.

Исходный текст

async-suspense-boundaries.md · MIT
---
title: Strategic Suspense Boundaries
impact: HIGH
impactDescription: faster initial paint
tags: async, suspense, streaming, layout-shift
---

## Strategic Suspense Boundaries

Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.

**Incorrect (wrapper blocked by data fetching):**

```tsx
async function Page() {
  const data = await fetchData() // Blocks entire page
  
  return (
    <div>
      <div>Sidebar</div>
      <div>Header</div>
      <div>
        <DataDisplay data={data} />
      </div>
      <div>Footer</div>
    </div>
  )
}
```

The entire layout waits for data even though only the middle section needs it.

**Correct (wrapper shows immediately, data streams in):**

```tsx
function Page() {
  return (
    <div>
      <div>Sidebar</div>
      <div>Header</div>
      <div>
        <Suspense fallback={<Skeleton />}>
          <DataDisplay />
        </Suspense>
      </div>
      <div>Footer</div>
    </div>
  )
}

async function DataDisplay() {
  const data = await fetchData() // Only blocks this component
  return <div>{data.content}</div>
}
```

Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.

**Alternative (share promise across components):**

```tsx
function Page() {
  // Start fetch immediately, but don't await
  const dataPromise = fetchData()
  
  return (
    <div>
      <div>Sidebar</div>
      <div>Header</div>
      <Suspense fallback={<Skeleton />}>
        <DataDisplay dataPromise={dataPromise} />
        <DataSummary dataPromise={dataPromise} />
      </Suspense>
      <div>Footer</div>
    </div>
  )
}

function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
  const data = use(dataPromise) // Unwraps the promise
  return <div>{data.content}</div>
}

function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
  const data = use(dataPromise) // Reuses the same promise
  return <div>{data.summary}</div>
}
```

Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.

**When NOT to use this pattern:**

- Critical data needed for layout decisions (affects positioning)
- SEO-critical content above the fold
- Small, fast queries where suspense overhead isn't worth it
- When you want to avoid layout shift (loading → content jump)

**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.

© tech-leads-club · MIT · tech-leads-club/agent-skills

Похожие правила IDE

Все правила IDE по теме «Фронтенд и UI» →
sanity-form-component-suspense sanity-io Скилл sanity-form-component-suspense для Claude Code устраняет предупреждения о нехватке границ Suspense в кастомных полях Sanity Studio. Срабатывает при сдвигах вёрстки из-за React.lazy или хуков App SDK. CX Codex +1 271установок nextjs-use-search-params-suspense wsimmonds Скилл nextjs-use-search-params-suspense объясняет, как правильно читать параметры URL в клиентских компонентах Next.js: директива 'use client' плюс обёртка Suspense. CX Codex +1 313установок loading-suspense zebbern Правило loading-suspense требует оборачивать асинхронные компоненты React Three Fiber в Suspense с заглушкой: без границы сцена останется пустой, пока грузится модель или текстура. CX Codex +1 ★ 4 719звёзд репо streaming-ssr patterns.dev Скилл streaming-ssr для Claude Code и ещё пяти агентных сред. Учит отдавать HTML частями по мере готовности на сервере, чтобы браузер начинал отрисовку раньше. CX Codex +1 964установок shadcn-component-boundaries purrfold Скилл shadcn-component-boundaries задаёт правила размещения UI-компонентов в проектах с shadcn. Изолирует примитивы реестра от продуктового кода и следит за односторонними импортами. CX Codex +1 5 700установок dynamic-import patterns.dev Обучает агента разделять бандл через dynamic import(). Скилл помогает отложить загрузку тяжёлых библиотек и диалогов до действий пользователя. CX Codex +1 1 700установок

Из того же набора130

Весь набор →
architecture-avoid-boolean-props Правило architecture-avoid-boolean-props запрещает раздувать компоненты булевыми пропсами и предлагает собирать варианты через композицию. Пригодится при проектировании React-компонентов. CX Codex +1 ★ 7 191звёзд репо rendering-hydration-no-flicker Правило rendering-hydration-no-flicker учит агента читать локальное хранилище без ошибок серверного рендеринга и без мигания интерфейса до гидратации. CX Codex +1 ★ 7 191звёзд репо bundle-barrel-imports Правило bundle-barrel-imports для Claude Code подсказывает импортировать модули напрямую, а не через barrel-файлы. Указывает прямые пути модулей в React-пакетах и библиотеках с большим числом реэкспортов. CX Codex +1 ★ 7 191звёзд репо patterns-explicit-variants Правило patterns-explicit-variants требует собирать каждый режим компонента отдельным компонентом вместо набора булевых пропсов. По вызову сразу видно, что отрисуется. CX Codex +1 ★ 7 191звёзд репо architecture-compound-components Правило architecture-compound-components предлагает собирать сложные компоненты из частей с общим контекстом. Оно пригодится, когда монолитный компонент обрастает условиями и render props. CX Codex +1 ★ 7 191звёзд репо state-decouple-implementation Правило state-decouple-implementation для Claude Code: провайдер управляет стейтом, UI-компонент знает только интерфейс контекста. Одна смена провайдера — useState, Zustand или серверный sync — не трогает ни одного UI-компонента. CX Codex +1 ★ 7 191звёзд репо rerender-functional-setstate Правило rerender-functional-setstate подсказывает использовать функциональное обновление React-состояния, когда новое значение зависит от текущего. Это помогает избежать устаревших замыканий в обработчиках. CX Codex +1 ★ 7 191звёзд репо state-lift-state Правило state-lift-state учит выносить состояние React в компонент-провайдер, чтобы соседние компоненты вне основного UI читали и меняли его без пропсов и ref. CX Codex +1 ★ 7 191звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой