loading-suspense — правило для Claude Code: Suspense в R3F
Правило loading-suspense требует оборачивать асинхронные компоненты React Three Fiber в Suspense с заглушкой: без границы сцена останется пустой, пока грузится модель или текстура.
MIT ★ 4 719 обновлён 2026-10-24
.claude/rules/loading-suspense.mdЧто делает 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
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/loading-suspense.mdcВо frontmatter: description, globs, alwaysApply
Вручную: положить файлы
.github/instructions/loading-suspense.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.devin/rules/loading-suspense.mdВручную: положить файлы
.clinerules/loading-suspense.mdПо шагам, с командами для каждой платформы: 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