Skip to main content
rule CX Codex

server-hoist-static-io — Claude Code rule: load static assets once

The server-hoist-static-io rule for Claude Code and Codex moves static asset I/O to module scope, loading files once instead of on every server-function request.

MIT ★ 1,216 updated 2026-10-24

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install react-skills@claude-settings
Open on GitHub

What server-hoist-static-io does

Server functions and route handlers often work with static files—fonts for OG images, logos, configuration files. Reading them per request kills performance, especially in Next.js route handlers or when generating images. This rule recommends moving I/O to module scope instead.

Module-level code runs once when imported, not on each function call. Instead of await fs.readFile() inside a request handler, use module-level promises that resolve once and get reused across requests. For synchronous reads, readFileSync works—it only blocks during module init. Works on Claude Code and Codex. Most effective on Vercel Fluid Compute, where concurrent requests share a function instance and static assets stay in memory across them without cold start penalties. In traditional serverless, cold starts re-run module code, but warm invocations reuse loaded assets until the instance recycles.

What it helps with

  • stop reading font files on every OG image generation
  • load configs and templates once for all requests
  • reduce route handler latency by moving I/O to startup
  • cache static logos and icons in the function instance memory

Example prompts for the agent

  • Move font loading for OG images out of the GET handler to module level
  • Show how to hoist config.json and template.html so they read once
  • Refactor the function so the logo loads at module init, not per request

How to install server-hoist-static-io

1Plugin marketplace

/plugin marketplace add fcakyon/claude-codex-settings
/plugin install react-skills@claude-settings

2Manually: put the files in place

.claude/rules/server-hoist-static-io.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about server-hoist-static-io

How do I install the server-hoist-static-io rule in Claude Code?

Open the command palette, run /plugin marketplace add fcakyon/claude-codex-settings, then /plugin install react-skills@claude-settings. The rule will load from .claude/rules/server-hoist-static-io.md.

What does this rule do?

It teaches you to move static file reads (fonts, logos, configs) to module scope. This way I/O happens once on import, not per request, which improves performance of server functions and route handlers.

When should I not use this pattern?

Don't hoist files that change during runtime or sensitive data that shouldn't stay in memory. For large files that consume too much memory, use caching with TTL instead of keeping them permanently loaded.

Source text

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

Similar IDE rules

All IDE rules for Backend and APIs →

From the same set113

The whole set →
setup setup — a skill for Claude Code and Codex that configures and refreshes Overleaf session tokens for overleaf-skills. Runs when requests return 401 unauthorized or expired sessions. CX Codex +1 ★ 1,216repo stars update-readme update-readme — a command for Claude Code and Codex rebuilds the plugin sections in README.md. It reads the plugin folders and marketplace data. CX Codex +1 ★ 1,216repo stars openship-deploy openship-deploy — a skill for running and maintaining a self-hosted OpenShip instance from the CLI: app deploys, domains, backups, upgrades. CX Codex +1 ★ 1,216repo stars list-performance-function-references list-performance-function-references instructs the AI agent to keep object references stable in virtualized lists. It prevents full list re-renders by moving state derivation into child items. CX Codex +1 ★ 1,216repo stars slides slides assembles PowerPoint decks with PptxGenJS, layout helpers, PNG rendering, and overflow detection for slide content. CX Codex +1 ★ 1,216repo stars ui-menus ui-menus — a rule for Claude Code and Codex that switches menu generation from custom JS components to native platform elements via zeego. Triggered when creating dropdowns or context menus. CX Codex +1 ★ 1,216repo stars schema A skill for Claude Code and Codex reviews and fixes JSON-LD structured data. It helps choose schema types and trace why a page is not getting a rich result. CX Codex +1 ★ 1,216repo stars python-guidelines python-guidelines — a skill that enforces rules for writing and reviewing Python code: fitting new code into existing patterns, blocking premature abstractions, and standardizing docstrings. CX Codex +1 ★ 1,216repo stars

Project sponsors

Companies that keep this analytics open