// Next.js Image with priority
import Image from 'next/image';
```
**Correct — Priority loading for LCP image:**
```tsx
```
## Key Rules
1. **Never** lazy-load the LCP image
2. **Always** use `fetchpriority="high"` on LCP images
3. **Always** server-render LCP content
4. **Preload** critical resources in `<head>`
5. **Preconnect** to third-party origins used for LCP
6. Target **<= 2.0s** for 2026 thresholds
### Serve AVIF and WebP formats for 30-50% smaller files than JPEG at equivalent quality — HIGH
# Modern Image Formats
Choose the right image format and quality settings for optimal compression.
## Format Decision Matrix
| Format | Best For | Browser Support | Quality Setting |
|--------|----------|----------------|-----------------|
| AVIF | Photos, gradients | 93%+ (2026) | 60-75 |
| WebP | Universal fallback | 97%+ | 75-82 |
| JPEG | Legacy fallback | 100% | 80-85 |
| PNG | Transparency, icons | 100% | N/A |
| SVG | Icons, logos | 100% | N/A |
## Picture Element with Fallback
```html
```
**Correct — Modern formats with fallback:**
```html
```
## Art Direction with Picture
```html
```
**Incorrect — srcset without sizes lets browser guess:**
```html
```
**Correct — sizes guides browser to optimal choice:**
```html
```
**Key rules:**
- **Always** provide `sizes` alongside `srcset` for width descriptors
- **Use** 3-4 srcset breakpoints (400, 800, 1200, 1600) for most images
- **Use** `<picture>` with `media` for art direction (different crops)
- **Delegate** resizing to a CDN rather than shipping multiple static files
- **Set** explicit `width` and `height` to prevent CLS
### Quantize models to reduce size 2-4x with minimal quality loss for fewer GPUs — MEDIUM
# Model Quantization
Reduce model memory footprint and increase throughput with quantization.
## Method Decision Matrix
| Method | Precision | Speed | Quality | Best For |
|--------|-----------|-------|---------|----------|
| FP16 | 16-bit | Baseline | Best | When VRAM allows |
| FP8 | 8-bit | 1.5x | Near-FP16 | Hopper/Ada GPUs (H100, L40S) |
| AWQ | 4-bit | 1.8x | Good | Production serving, speed priority |
| GPTQ | 4-bit | 1.6x | Better | Quality-sensitive tasks |
| GGUF | 2-8 bit | Varies | Varies | CPU/hybrid inference (llama.cpp) |
## vLLM with AWQ
```bash
# Serve a pre-quantized AWQ model
docker run --gpus '"device=0"' \
-p 8000:8000 \
vllm/vllm-openai:latest \
--model TheBloke/Llama-3.1-8B-Instruct-AWQ \
--quantization awq \
--max-model-len 8192
```
## vLLM with FP8 (Hopper GPUs)
```bash
# FP8 on H100 — native hardware support, no pre-quantized model needed
docker run --gpus all \
-p 8000:8000 \
vllm/vllm-openai:latest \
--model meta-llama/Llama-3.1-70B-Instruct \
--quantization fp8 \
--tensor-parallel-size 4
```
## VRAM Requirements (Approximate)
```
Model FP16 FP8 AWQ/GPTQ (4-bit)
7-8B 16 GB 9 GB 5 GB
13B 26 GB 14 GB 8 GB
70B 140 GB 75 GB 40 GB
Formula: VRAM ≈ params × bytes_per_param × 1.2 (KV cache overhead)
```
## Quality Validation
```python
# Always benchmark quantized vs full precision on YOUR task
def eval_quantized(client, test_cases):
results = []
for case in test_cases:
response = client.chat.completions.create(
model="quantized-model",
messages=case["messages"],
max_tokens=case["max_tokens"],
)
results.append(score(response, case["expected"]))
return sum(results) / len(results)
# Accept quantization if quality >= 95% of FP16 baseline
```
**Incorrect — FP16 on smaller GPUs wastes VRAM:**
```bash
docker run --gpus all \
vllm/vllm-openai:latest \
--model meta-llama/Llama-3.1-70B-Instruct \
--tensor-parallel-size 8
# Requires 140 GB VRAM
```
**Correct — FP8 quantization reduces VRAM by ~45%:**
```bash
docker run --gpus all \
vllm/vllm-openai:latest \
--model meta-llama/Llama-3.1-70B-Instruct \
--quantization fp8 \
--tensor-parallel-size 4
# Requires 75 GB VRAM
```
**Key rules:**
- **Use** FP8 on Hopper/Ada GPUs (best speed/quality tradeoff)
- **Use** AWQ for maximum throughput on older GPUs
- **Use** GPTQ when quality matters more than speed
- **Always** validate quantized model quality on your specific task
- **Pre-quantized** models (e.g., TheBloke) save quantization time
### Apply speculative decoding to generate draft tokens in parallel and reduce inference latency — MEDIUM
# Speculative Decoding
Use speculative decoding to reduce per-token latency without sacrificing output quality.
## How It Works
```
Traditional: token1 → token2 → token3 → token4 (4 forward passes)
Speculative: draft: token1, token2, token3 (fast, cheap)
verify: accept/reject all 3 (1 forward pass)
Result: 3 tokens in ~1.3 forward passes
```
## N-Gram Speculation (No Draft Model)
```bash
# vLLM n-gram speculation — uses prompt tokens as draft source
# Best for repetitive/structured output (JSON, code, templates)
docker run --gpus '"device=0"' \
-p 8000:8000 \
vllm/vllm-openai:latest \
--model meta-llama/Llama-3.1-8B-Instruct \
--speculative-model [ngram] \
--num-speculative-tokens 5 \
--ngram-prompt-lookup-max 4
```
## Draft Model Speculation
```bash
# Use a smaller model as the draft (must share tokenizer)
docker run --gpus '"device=0"' \
-p 8000:8000 \
vllm/vllm-openai:latest \
--model meta-llama/Llama-3.1-70B-Instruct \
--speculative-model meta-llama/Llama-3.1-8B-Instruct \
--num-speculative-tokens 5 \
--tensor-parallel-size 4
```
## Acceptance Rate Tuning
```
--num-speculative-tokens:
3 → Conservative, high acceptance rate (~85%)
5 → Balanced (default recommendation)
8 → Aggressive, lower acceptance rate (~60%)
Monitor via vLLM metrics:
vllm:spec_decode_acceptance_rate → target > 70%
If acceptance < 60%:
1. Reduce --num-speculative-tokens
2. Try n-gram for structured output
3. Verify draft model matches target model's style
```
## When to Use Each Approach
```
N-gram speculation:
+ Structured output (JSON, SQL, code)
+ Repetitive patterns
+ No extra GPU memory needed
- Creative / diverse text
Draft model speculation:
+ General text generation
+ Large target models (70B+)
+ Higher acceptance rates on diverse tasks
- Requires extra GPU memory for draft model
```
**Incorrect — No speculation means sequential token generation:**
```bash
docker run --gpus '"device=0"' \
vllm/vllm-openai:latest \
--model meta-llama/Llama-3.1-8B-Instruct
# 4 tokens = 4 forward passes
```
**Correct — N-gram speculation reduces passes by 30-60%:**
```bash
docker run --gpus '"device=0"' \
vllm/vllm-openai:latest \
--model meta-llama/Llama-3.1-8B-Instruct \
--speculative-model [ngram] \
--num-speculative-tokens 5
# 4 tokens ≈ 1.3 forward passes
```
**Key rules:**
- **Use** n-gram speculation for structured/repetitive output (free, no extra VRAM)
- **Use** draft model speculation for general text with large target models
- **Start** with `--num-speculative-tokens 5` and tune based on acceptance rate
- **Monitor** acceptance rate; reduce tokens if below 60%
- **Output quality** is identical to non-speculative decoding (mathematically guaranteed)
### Deploy vLLM with PagedAttention and continuous batching for 2-4x higher inference throughput — MEDIUM
# vLLM Deployment
Deploy LLMs with vLLM for high-throughput, low-latency inference.
## Docker Deployment
```bash
# Single GPU
docker run --gpus '"device=0"' \
-v ~/.cache/huggingface:/root/.cache/huggingface \
-p 8000:8000 \
vllm/vllm-openai:latest \
--model meta-llama/Llama-3.1-8B-Instruct \
--max-model-len 8192 \
--gpu-memory-utilization 0.90
# Multi-GPU with tensor parallelism
docker run --gpus all \
-v ~/.cache/huggingface:/root/.cache/huggingface \
-p 8000:8000 \
vllm/vllm-openai:latest \
--model meta-llama/Llama-3.1-70B-Instruct \
--tensor-parallel-size 4 \
--max-model-len 8192 \
--gpu-memory-utilization 0.92
```
## Python Client
```python
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="unused")
response = client.chat.completions.create(
model="meta-llama/Llama-3.1-8B-Instruct",
messages=[{"role": "user", "content": "Explain PagedAttention briefly."}],
max_tokens=256,
temperature=0.7,
)
print(response.choices[0].message.content)
```
## Key Architecture Concepts
```
PagedAttention:
- KV cache stored in non-contiguous pages (like OS virtual memory)
- Eliminates memory waste from pre-allocated contiguous blocks
- Enables 2-4x more concurrent sequences
Continuous Batching:
- New requests join running batch immediately
- No waiting for longest sequence to finish
- Throughput: 10-30 requests/second on single A100 (8B model)
Tensor Parallelism:
- Splits model across GPUs (--tensor-parallel-size N)
- Rule: N = number of GPUs, must evenly divide model layers
- Use for models > single GPU VRAM
```
**Incorrect — Default memory utilization wastes KV cache space:**
```bash
docker run --gpus '"device=0"' \
vllm/vllm-openai:latest \
--model meta-llama/Llama-3.1-8B-Instruct
# Uses default 0.70 GPU memory
```
**Correct — Higher utilization enables more concurrent requests:**
```bash
docker run --gpus '"device=0"' \
vllm/vllm-openai:latest \
--model meta-llama/Llama-3.1-8B-Instruct \
--gpu-memory-utilization 0.90 \
--max-model-len 8192
# 2-4x more concurrent requests
```
**Key rules:**
- **Set** `--gpu-memory-utilization 0.90` (leave headroom for KV cache)
- **Use** `--tensor-parallel-size` equal to the number of GPUs
- **Use** the OpenAI-compatible API for drop-in compatibility
- **Monitor** `vllm:num_requests_running` Prometheus metric for load
- **Set** `--max-model-len` to the actual max you need (lower = more concurrent requests)
### Defer component loading with React.lazy to reduce initial bundle size and improve TTI — HIGH
# Lazy Component Loading
Use `React.lazy` with `Suspense` to load components on demand and reduce initial bundle size.
## Basic Pattern
```tsx
import { lazy, Suspense } from 'react';
const Dashboard = lazy(() => import('./Dashboard'));
const Settings = lazy(() => import('./Settings'));
function App() {
return (
{data.name}
;
}
```
**Correct — prefetch on hover and in route loaders:**
```typescript
// 1. Define reusable query options (v5 pattern)
const userQueryOptions = (id: string) => queryOptions({
queryKey: ['user', id] as const,
queryFn: () => fetchUser(id),
staleTime: 5 * 60 * 1000, // Fresh for 5 min
});
// 2. Prefetch on hover
function UserLink({ userId }: { userId: string }) {
const queryClient = useQueryClient();
const prefetchUser = () => {
queryClient.prefetchQuery(userQueryOptions(userId));
};
return (
View User
);
}
// 3. Prefetch in route loader (React Router 7.x)
export const loader = (queryClient: QueryClient) =>
async ({ params }: { params: { id: string } }) => {
await queryClient.ensureQueryData(userQueryOptions(params.id));
return null;
};
// 4. Use with Suspense for instant render
function UserProfile({ userId }: { userId: string }) {
// Data already loaded by prefetch — no loading state!
const { data } = useSuspenseQuery(userQueryOptions(userId));
return {data.name}
;
}
```
**QueryClient configuration:**
```typescript
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 1000 * 60, // 1 min fresh
gcTime: 1000 * 60 * 5, // 5 min in cache (formerly cacheTime)
refetchOnWindowFocus: true, // Refetch on tab focus
retry: 3,
retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
},
},
});
```
**Key rules:**
- Use `queryOptions()` helper for reusable query definitions across prefetch/useQuery/loader
- Prefetch on `onMouseEnter` AND `onFocus` for keyboard users
- Use `ensureQueryData` in loaders (waits for data), `prefetchQuery` for fire-and-forget
- `useSuspenseQuery` for components where data is guaranteed by loader
- `gcTime` (v5) replaces `cacheTime` (v4) — controls how long unused data stays in memory
- `isPending` (v5) replaces `isLoading` for initial load state
### Let React Compiler auto-memoize components, values, callbacks, and JSX automatically — HIGH
# React Compiler
React 19's compiler is the primary approach to render optimization in 2026.
## Decision Tree
```
Is React Compiler enabled?
├─ YES → Let compiler handle memoization automatically
│ Only use useMemo/useCallback as escape hatches
│ DevTools shows "Memo ✨" badge
│
└─ NO → Profile first, then optimize
1. React DevTools Profiler
2. Identify actual bottlenecks
3. Apply targeted optimizations
```
## What the Compiler Memoizes
- Component re-renders
- Intermediate values (like useMemo)
- Callback references (like useCallback)
- JSX elements
## Enabling the Compiler
```tsx
// next.config.js (Next.js 16+)
const nextConfig = {
reactCompiler: true,
}
// Expo SDK 54+ enables by default
```
## Verification
Open React DevTools and look for the "Memo ✨" badge on components. If present, the compiler is successfully memoizing that component.
**Incorrect — Manual memoization when compiler is enabled:**
```tsx
// next.config.js has reactCompiler: true
const value = useMemo(() => compute(data), [data]);
const callback = useCallback(() => handle(), []);
// Compiler already handles this automatically
```
**Correct — Let compiler auto-memoize:**
```tsx
// Compiler handles memoization automatically
function Component({ data }) {
const value = compute(data); // Auto-memoized
const handle = () => {}; // Auto-memoized
return {value}
;
}
// Check DevTools for "Memo ✨" badge
```
## Key Rules
1. **Enable** React Compiler as the first step
2. **Let** the compiler handle memoization automatically
3. **Verify** with DevTools "Memo ✨" badge
4. **Only** use manual memoization as escape hatches
5. **Profile** before adding any manual optimization
### Use manual useMemo and useCallback escape hatches when React Compiler cannot optimize — HIGH
# Manual Memoization Escape Hatches
Use `useMemo`/`useCallback` as escape hatches when React Compiler is insufficient.
## When Manual Memoization Is Needed
```tsx
// 1. Effect dependencies that shouldn't trigger re-runs
const stableConfig = useMemo(() => ({
apiUrl: process.env.API_URL
}), [])
useEffect(() => {
initializeSDK(stableConfig)
}, [stableConfig])
// 2. Third-party libraries without compiler support
const memoizedValue = useMemo(() =>
expensiveThirdPartyComputation(data), [data])
// 3. Precise control over memoization boundaries
const handleClick = useCallback(() => {
// Critical callback that must be stable
}, [dependency])
```
## State Colocation
Move state as close to where it's used as possible:
```tsx
// BAD: State too high - causes unnecessary re-renders
function App() {
const [filter, setFilter] = useState('')
return (
{virtualizer.getVirtualItems().map((virtualRow) => (
{items[virtualRow.index].name}
))}
{items.map(item => (
);
}
```
**Correct — Virtualization renders only visible items:**
```tsx
import { useVirtualizer } from '@tanstack/react-virtual';
function VirtualList({ items }) {
const parentRef = useRef(null);
const virtualizer = useVirtualizer({
count: items.length,
getScrollElement: () => parentRef.current,
estimateSize: () => 50,
overscan: 5,
});
return (
{item.name}
))}
{virtualizer.getVirtualItems().map(virtualRow => (
{items[virtualRow.index].name}
))}
```
**Correct — AVIF/WebP with fallback, sized appropriately:**
```html