server-hoist-static-io — правило для Claude Code
Правило server-hoist-static-io для Claude Code и Codex, которое помогает избежать повторных операций чтения файлов и сетевых запросов.
MIT ★ 1 216 обновлён 2026-10-24
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install react-skills@claude-settingsЧто делает server-hoist-static-io
При разработке серверных функций и обработчиков маршрутов часто приходится работать со статическими файлами: шрифты для OG-изображений, логотипы, конфигурации. Если читать их на каждый запрос, это убивает производительность — особенно заметно в Next.js route handlers или при генерации изображений. Правило рекомендует переместить I/O операции на уровень модуля.
Модульный код выполняется один раз при первом импорте, а не на каждый вызов функции. Вместо await fs.readFile() внутри обработчика запроса используй промисы на уровне модуля, которые разрешаются один раз и переиспользуются во всех запросах. Для синхронного чтения подойдёт readFileSync, блокирующий только на этапе инициализации модуля.
Правило работает на Claude Code и Codex. Особенно эффективно на Vercel Fluid Compute, где несколько конкурентных запросов делят один экземпляр функции — статика остаётся в памяти без холодного старта. В традиционном serverless каждый холодный старт переопределяет модульный код, но тёплые вызовы переиспользуют загруженные ресурсы до переработки инстанса.
Какие задачи решает
- избежать повторного чтения файлов шрифтов в генераторе OG-изображений
- загрузить конфиги и шаблоны один раз для всех запросов
- снизить задержку обработчика маршрута, переместив I/O на инициализацию
- кэшировать статические логотипы и иконки в памяти инстанса
Примеры запросов агенту
- Помогите переместить загрузку шрифтов для OG-изображений из обработчика GET на уровень модуля
- Покажите, как хоустить
config.jsonиtemplate.htmlчтобы они читались один раз - Переделайте функцию так, чтобы логотип загружался при инициализации модуля, а не при каждом запросе
Как установить server-hoist-static-io
1Через маркетплейс плагинов
/plugin marketplace add fcakyon/claude-codex-settings/plugin install react-skills@claude-settings2Вручную: положить файлы
.claude/rules/server-hoist-static-io.mdПоле paths во frontmatter ограничивает файлы
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/server-hoist-static-io.mdcВо frontmatter: description, globs, alwaysApply
Вручную: положить файлы
.github/instructions/server-hoist-static-io.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.devin/rules/server-hoist-static-io.mdВручную: положить файлы
.clinerules/server-hoist-static-io.mdПо шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать
Вопросы о server-hoist-static-io
Как установить правило server-hoist-static-io в Claude Code?
Откройте командную палитру Claude Code, введите /plugin marketplace add fcakyon/claude-codex-settings, затем /plugin install react-skills@claude-settings. После этого правило загрузится из файла .claude/rules/server-hoist-static-io.md.
Что делает это правило?
Правило обучает поднимать операции чтения статических файлов (шрифты, логотипы, конфиги) на уровень модуля. Благодаря этому I/O выполняется один раз при импорте, а не при каждом запросе, что улучшает производительность серверных функций.
Когда НЕ стоит использовать это правило?
Не поднимай на уровень модуля файлы, которые меняются во время работы приложения, а также чувствительные данные, которые не должны оставаться в памяти. Для больших файлов, которые потребляют много памяти, лучше использовать кэширование с TTL вместо постоянной загрузки.
Исходный текст
server-hoist-static-io.md · MIT
---
title: Hoist Static I/O to Module Level
impact: HIGH
impactDescription: avoids repeated file/network I/O per request
tags: server, io, performance, next.js, route-handlers, og-image
---
## Hoist Static I/O to Module Level
**Impact: HIGH (avoids repeated file/network I/O per request)**
When loading static assets (fonts, logos, images, config files) in route handlers or server functions, hoist the I/O operation to module level. Module-level code runs once when the module is first imported, not on every request. This eliminates redundant file system reads or network fetches that would otherwise run on every invocation.
**Incorrect (reads font file on every request):**
```typescript
// app/api/og/route.tsx
import { ImageResponse } from 'next/og'
export async function GET(request: Request) {
// Runs on EVERY request - expensive!
const fontData = await fetch(
new URL('./fonts/Inter.ttf', import.meta.url)
).then(res => res.arrayBuffer())
const logoData = await fetch(
new URL('./images/logo.png', import.meta.url)
).then(res => res.arrayBuffer())
return new ImageResponse(
<div style={{ fontFamily: 'Inter' }}>
<img src={logoData} />
Hello World
</div>,
{ fonts: [{ name: 'Inter', data: fontData }] }
)
}
```
**Correct (loads once at module initialization):**
```typescript
// app/api/og/route.tsx
import { ImageResponse } from 'next/og'
// Module-level: runs ONCE when module is first imported
const fontData = fetch(
new URL('./fonts/Inter.ttf', import.meta.url)
).then(res => res.arrayBuffer())
const logoData = fetch(
new URL('./images/logo.png', import.meta.url)
).then(res => res.arrayBuffer())
export async function GET(request: Request) {
// Await the already-started promises
const [font, logo] = await Promise.all([fontData, logoData])
return new ImageResponse(
<div style={{ fontFamily: 'Inter' }}>
<img src={logo} />
Hello World
</div>,
{ fonts: [{ name: 'Inter', data: font }] }
)
}
```
**Correct (synchronous fs at module level):**
```typescript
// app/api/og/route.tsx
import { ImageResponse } from 'next/og'
import { readFileSync } from 'fs'
import { join } from 'path'
// Synchronous read at module level - blocks only during module init
const fontData = readFileSync(
join(process.cwd(), 'public/fonts/Inter.ttf')
)
const logoData = readFileSync(
join(process.cwd(), 'public/images/logo.png')
)
export async function GET(request: Request) {
return new ImageResponse(
<div style={{ fontFamily: 'Inter' }}>
<img src={logoData} />
Hello World
</div>,
{ fonts: [{ name: 'Inter', data: fontData }] }
)
}
```
**Incorrect (reads config on every call):**
```typescript
import fs from 'node:fs/promises'
export async function processRequest(data: Data) {
const config = JSON.parse(
await fs.readFile('./config.json', 'utf-8')
)
const template = await fs.readFile('./template.html', 'utf-8')
return render(template, data, config)
}
```
**Correct (hoists config and template to module level):**
```typescript
import fs from 'node:fs/promises'
const configPromise = fs
.readFile('./config.json', 'utf-8')
.then(JSON.parse)
const templatePromise = fs.readFile('./template.html', 'utf-8')
export async function processRequest(data: Data) {
const [config, template] = await Promise.all([
configPromise,
templatePromise,
])
return render(template, data, config)
}
```
When to use this pattern:
- Loading fonts for OG image generation
- Loading static logos, icons, or watermarks
- Reading configuration files that don't change at runtime
- Loading email templates or other static templates
- Any static asset that's the same across all requests
When not to use this pattern:
- Assets that vary per request or user
- Files that may change during runtime (use caching with TTL instead)
- Large files that would consume too much memory if kept loaded
- Sensitive data that shouldn't persist in memory
With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute), module-level caching is especially effective because multiple concurrent requests share the same function instance. The static assets stay loaded in memory across requests without cold start penalties.
In traditional serverless, each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.
© fcakyon · MIT · fcakyon/claude-codex-settings