Cursor rule

1---
2alwaysApply: false
3---
4 
5## Hoist Static I/O to Module Level
6 
7**Impact: HIGH (avoids repeated file/network I/O per request)**
8 
9When 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.
10 
11**Incorrect (reads font file on every request):**
12 
13```typescript
14// app/api/og/route.tsx
15import { ImageResponse } from 'next/og'
16 
17export async function GET(request: Request) {
18  // Runs on EVERY request - expensive!
19  const fontData = await fetch(
20    new URL('./fonts/Inter.ttf', import.meta.url)
21  ).then(res => res.arrayBuffer())
22 
23  const logoData = await fetch(
24    new URL('./images/logo.png', import.meta.url)
25  ).then(res => res.arrayBuffer())
26 
27  return new ImageResponse(
28    <div style={{ fontFamily: 'Inter' }}>
29      <img src={logoData} />
30      Hello World
31    </div>,
32    { fonts: [{ name: 'Inter', data: fontData }] }
33  )
34}
35```
36 
37**Correct (loads once at module initialization):**
38 
39```typescript
40// app/api/og/route.tsx
41import { ImageResponse } from 'next/og'
42 
43// Module-level: runs ONCE when module is first imported
44const fontData = fetch(
45  new URL('./fonts/Inter.ttf', import.meta.url)
46).then(res => res.arrayBuffer())
47 
48const logoData = fetch(
49  new URL('./images/logo.png', import.meta.url)
50).then(res => res.arrayBuffer())
51 
52export async function GET(request: Request) {
53  // Await the already-started promises
54  const [font, logo] = await Promise.all([fontData, logoData])
55 
56  return new ImageResponse(
57    <div style={{ fontFamily: 'Inter' }}>
58      <img src={logo} />
59      Hello World
60    </div>,
61    { fonts: [{ name: 'Inter', data: font }] }
62  )
63}
64```
65 
66**Correct (synchronous fs at module level):**
67 
68```typescript
69// app/api/og/route.tsx
70import { ImageResponse } from 'next/og'
71import { readFileSync } from 'fs'
72import { join } from 'path'
73 
74// Synchronous read at module level - blocks only during module init
75const fontData = readFileSync(
76  join(process.cwd(), 'public/fonts/Inter.ttf')
77)
78 
79const logoData = readFileSync(
80  join(process.cwd(), 'public/images/logo.png')
81)
82 
83export async function GET(request: Request) {
84  return new ImageResponse(
85    <div style={{ fontFamily: 'Inter' }}>
86      <img src={logoData} />
87      Hello World
88    </div>,
89    { fonts: [{ name: 'Inter', data: fontData }] }
90  )
91}
92```
93 
94**Incorrect (reads config on every call):**
95 
96```typescript
97import fs from 'node:fs/promises'
98 
99export async function processRequest(data: Data) {
100  const config = JSON.parse(
101    await fs.readFile('./config.json', 'utf-8')
102  )
103  const template = await fs.readFile('./template.html', 'utf-8')
104 
105  return render(template, data, config)
106}
107```
108 
109**Correct (hoists config and template to module level):**
110 
111```typescript
112import fs from 'node:fs/promises'
113 
114const configPromise = fs
115  .readFile('./config.json', 'utf-8')
116  .then(JSON.parse)
117const templatePromise = fs.readFile('./template.html', 'utf-8')
118 
119export async function processRequest(data: Data) {
120  const [config, template] = await Promise.all([
121    configPromise,
122    templatePromise,
123  ])
124 
125  return render(template, data, config)
126}
127```
128 
129When to use this pattern:
130 
131- Loading fonts for OG image generation
132- Loading static logos, icons, or watermarks
133- Reading configuration files that don't change at runtime
134- Loading email templates or other static templates
135- Any static asset that's the same across all requests
136 
137When not to use this pattern:
138 
139- Assets that vary per request or user
140- Files that may change during runtime (use caching with TTL instead)
141- Large files that would consume too much memory if kept loaded
142- Sensitive data that shouldn't persist in memory
143 
144With 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.
145 
146In traditional serverless, each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.
147