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

loading-suspense — правило для Claude Code: Suspense в R3F

Правило loading-suspense требует оборачивать асинхронные компоненты React Three Fiber в Suspense с заглушкой: без границы сцена останется пустой, пока грузится модель или текстура.

MIT ★ 4 719 обновлён 2026-10-24

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

Что делает loading-suspense

Правило для сцен на React Three Fiber. Компонент, который тянет ассеты через useGLTF или useTexture, приостанавливает рендер, пока файл не догрузится. Поэтому его нужно ставить внутрь <Suspense> с запасным вариантом — иначе показывать в этот момент нечего.

Внутри лежат готовые куски кода: одна модель внутри Canvas, несколько асинхронных компонентов на общей границе, вложенные границы, где окружение грузится отдельно, а персонаж держит видимый загрузчик. Прогресс собирается из useProgress в @react-three/drei: хук отдаёт active, progress и имя текущего item.

Сбои закрывает ErrorBoundary из пакета react-error-boundary поверх Suspense, с кнопкой повтора. Этот пакет придётся добавить в зависимости: React своего ErrorBoundary не отдаёт. Ещё приём — предзагрузка на уровне модуля: useGLTF.preload('/model.glb') кладёт ассет в кеш, и компонент дальше рендерится сразу.

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

  • обернуть модель из useGLTF в границу Suspense с заглушкой
  • показать прогресс загрузки сцены через useProgress
  • развести загрузку окружения и персонажа по вложенным границам
  • поймать ошибку загрузки .glb и дать кнопку повтора
  • убрать мигание заглушки предзагрузкой текстур

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

  • Оберни компонент с useGLTF в <Suspense> и сделай wireframe-заглушку на время загрузки
  • Добавь ErrorBoundary из react-error-boundary вокруг сцены с моделью
  • Предзагрузи /model.glb через useGLTF.preload, чтобы сцена не мигала

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

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

.claude/rules/loading-suspense.md

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

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

Вопросы о loading-suspense

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

Положите файл правила по пути .claude/rules/loading-suspense.md. Оттуда он и подхватывается.

Что делает loading-suspense?

Напоминает агенту держать асинхронные компоненты R3F внутри Suspense с fallback и даёт примеры для загрузчиков, вложенных границ и ошибок.

Нужен ли пакет react-error-boundary?

Да, если хотите ловить сбои загрузки: в примере ErrorBoundary импортируется из react-error-boundary. Без него хватит Suspense с заглушкой.

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

loading-suspense.md · MIT
# loading-suspense

**Wrap async components in Suspense.**

## Why It Matters

R3F integrates with React Suspense for loading states. Components using `useGLTF`, `useTexture`, or other async loaders will suspend and need a Suspense boundary with a fallback.

## Basic Example

```jsx
import { Suspense } from 'react';
import { Canvas } from '@react-three/fiber';
import { useGLTF } from '@react-three/drei';

function Model() {
  const { scene } = useGLTF('/model.glb');
  return <primitive object={scene} />;
}

function App() {
  return (
    <Canvas>
      <Suspense fallback={<LoadingFallback />}>
        <Model />
      </Suspense>
    </Canvas>
  );
}

function LoadingFallback() {
  return (
    <mesh>
      <boxGeometry />
      <meshBasicMaterial wireframe color="white" />
    </mesh>
  );
}
```

## Multiple Async Components

```jsx
function Scene() {
  return (
    <Suspense fallback={<Loader />}>
      <Environment preset="city" />
      <Model url="/character.glb" />
      <Ground />
    </Suspense>
  );
}
```

## Nested Suspense Boundaries

```jsx
function Scene() {
  return (
    <>
      {/* Environment loads first */}
      <Suspense fallback={null}>
        <Environment preset="sunset" />
      </Suspense>

      {/* Main content with visible loader */}
      <Suspense fallback={<Loader />}>
        <Character />
        <Props />
      </Suspense>

      {/* Background loads last, no blocking */}
      <Suspense fallback={null}>
        <BackgroundDetails />
      </Suspense>
    </>
  );
}
```

## Using useProgress

```jsx
import { useProgress, Html } from '@react-three/drei';

function Loader() {
  const { active, progress, errors, item, loaded, total } = useProgress();

  return (
    <Html center>
      <div className="loader">
        <div className="progress-bar">
          <div
            className="progress-fill"
            style={{ width: `${progress}%` }}
          />
        </div>
        <p>{progress.toFixed(0)}% loaded</p>
        <p className="loading-item">{item}</p>
      </div>
    </Html>
  );
}

function App() {
  return (
    <Canvas>
      <Suspense fallback={<Loader />}>
        <Scene />
      </Suspense>
    </Canvas>
  );
}
```

## Error Boundaries

```jsx
import { ErrorBoundary } from 'react-error-boundary';

function ModelErrorFallback({ error, resetErrorBoundary }) {
  return (
    <Html center>
      <div>
        <p>Failed to load model</p>
        <button onClick={resetErrorBoundary}>Try again</button>
      </div>
    </Html>
  );
}

function SafeModel({ url }) {
  return (
    <ErrorBoundary
      FallbackComponent={ModelErrorFallback}
      onReset={() => {
        // Reset any state if needed
      }}
    >
      <Suspense fallback={<LoadingBox />}>
        <Model url={url} />
      </Suspense>
    </ErrorBoundary>
  );
}
```

## Preloading to Avoid Suspense

```jsx
import { useGLTF, useTexture } from '@react-three/drei';

// Preload at module level
useGLTF.preload('/model.glb');
useTexture.preload('/texture.png');

// Component won't suspend if already loaded
function Model() {
  const { scene } = useGLTF('/model.glb'); // Instant if preloaded
  return <primitive object={scene} />;
}
```

## Animated Fallback

```jsx
function AnimatedLoader() {
  const meshRef = useRef();

  useFrame((state) => {
    meshRef.current.rotation.x = state.clock.elapsedTime;
    meshRef.current.rotation.y = state.clock.elapsedTime * 0.5;
  });

  return (
    <mesh ref={meshRef}>
      <icosahedronGeometry args={[1, 1]} />
      <meshBasicMaterial wireframe color="cyan" />
    </mesh>
  );
}
```

## References

- [React Suspense](https://react.dev/reference/react/Suspense)
- [Drei useProgress](https://github.com/pmndrs/drei#useprogress)

© zebbern · MIT · zebbern/claude-code-guide

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

Все правила IDE по теме «Фронтенд и UI» →
react-three-fiber freshtechbro Скилл react-three-fiber обучает агента строить декларативные 3D-сцены в React через Three.js, настраивать хуки рендера и загружать модели через Suspense. CX Codex +1 4 300установок r3f-loaders EnzeD Скилл r3f-loaders помогает загружать и переиспользовать 3D-модели в React Three Fiber. Настраивает хуки, предзагрузку, клонирование объектов и показ заглушек. CX Codex +1 2 100установок threejs-r3f AThevon Скилл threejs-r3f для Claude Code помогает создавать 3D-сцены на Three.js и React Three Fiber. Даёт рекомендации по шейдерам, постобработке и производительности. CX Codex +1 1 000установок react-three-fiber-architect Claude Design Skillstack Субагент react-three-fiber-architect для проектирования 3D-сцен на React Three Fiber: разбирает архитектуру, ищет узкие места рендера и предлагает план оптимизации. CX Codex ★ 1 428звёзд репо nextjs-use-search-params-suspense wsimmonds Скилл nextjs-use-search-params-suspense объясняет, как правильно читать параметры URL в клиентских компонентах Next.js: директива 'use client' плюс обёртка Suspense. CX Codex +1 313установок sanity-form-component-suspense sanity-io Скилл sanity-form-component-suspense для Claude Code устраняет предупреждения о нехватке границ Suspense в кастомных полях Sanity Studio. Срабатывает при сдвигах вёрстки из-за React.lazy или хуков App SDK. CX Codex +1 271установок

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

Весь набор →
tsl-material-slots tsl-material-slots — правило для Claude Code со справочником слотов TSL в Three.js. Помогает настраивать шейдерную логику через узлы без ошибок в типах и именах свойств. CX Codex +1 ★ 4 719звёзд репо core-web-vitals Правило core-web-vitals для Claude Code: грузит модели и текстуры в 3D-сценах на Three.js так, чтобы LCP, FID и CLS не проседали. Не даёт тяжёлому 3D тормозить первую отрисовку. CX Codex +1 ★ 4 719звёзд репо postprocessing-optimization Правило postprocessing-optimization для Three.js и React Three Fiber. Помогает оптимизировать постобработку и объединять шейдерные проходы без просадок FPS. CX Codex +1 ★ 4 719звёзд репо timeline-builder Скилл timeline-builder для Claude Code превращает JSON-данные в интерактивную HTML-хронологию с вертикальной, горизонтальной или двусторонней раскладкой. Отображает этапы проекта, историю выпусков и резюме. CX Codex +1 ★ 4 719звёзд репо lighting-shadows-advanced Правило lighting-shadows-advanced для Claude Code настраивает освещение и тени в Three.js с учётом стоимости рендеринга. Оптимизирует тени при множестве источников света. CX Codex +1 ★ 4 719звёзд репо migration-checklist Правило migration-checklist подсказывает агенту, как мигрировать код при обновлении Three.js. Перечисляет breaking changes с r125 и актуальные пути импортов. CX Codex +1 ★ 4 719звёзд репо audio-spatial Правило audio-spatial для Claude Code задаёт шаблоны настройки 3D-звука в Three.js: позиционирование источников, затухание и реакцию на действия пользователя. CX Codex +1 ★ 4 719звёзд репо debug-devtools Правило debug-devtools для Claude Code и Codex добавляет в Three.js-проект средства диагностики производительности, сцены и потери WebGL-контекста. Находит узкие места и проверяет параметры вживую. CX Codex +1 ★ 4 719звёзд репо

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

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