v8-jit

Files (1)

• SKILL.md

SKILL.md (first lines)

# V8 JIT Optimization

Use this skill when writing or optimizing performance-critical code paths in
Next.js server internals — especially per-request hot paths like rendering,
streaming, routing, and caching.

## Background: V8's Tiered Compilation

V8 compiles JavaScript through multiple tiers:

1. **Ignition** (interpreter) — executes bytecode immediately.
2. **Sparkplug** — fast baseline compiler (no optimization).
3. **Maglev** — mid-tier optimizing compiler.
4. **Turbofan** — full optimizing compiler (speculative, type-feedback-driven).

Code starts in Ignition and is promoted to higher tiers based on execution
frequency and collected type feedback. Turbofan produces the fastest machine
code but **bails out (deopts)** when assumptions are violated at runtime.

The key principle: **help V8 make correct speculative assumptions by keeping
types, shapes, and control flow predictable.**

## Hidden Classes (Shapes / Maps)

Every JavaScript object has an internal "hidden class" (V8 calls it a _Map_,
the spec calls it a _Shape_). Objects that share the same property names, added
in the same order, share the same hidden class. This enables fast property
access via inline caches.

### Initialize All Properties in Constructors

```ts
// GOOD — consistent shape, single hidden class transition chain
class RequestContext {
  url: string
  method: string
  headers: Record<string, string>
  startTime: number
  cached: boolean

  constructor(url: string, method: string, headers: Record<string, string>) {
    this.url = url
    this.method = method
    this.headers = headers
    this.startTime = performance.now()
    this.cached = false // always initialize, even defaults
  }
}
```

```ts
// BAD — conditional property addition creates multiple hidden classes
class RequestContext {
  constructor(url, method, headers, options) {
    this.url = url
    this.method = method
    if (options.timing) {
      this.startTime = performance.now() // shape fork!
    }
    if (options.cache) {
      this.cached = false // another shape fork!
    }
    this.headers = headers
  }
}
```

**Rules:**

- Assign every property in the constructor, in the same order, for every
  instance. Use `null` / `undefined` / `false` as default values rather than
  omitting the property.
- Prefer factory functions when constructing hot-path objects. A single factory
  makes it harder to accidentally fork shapes in different call sites.
- Never `delete` a property on a hot object — it forces a transition to
  dictionary mode (slow properties).
- Avoid adding properties after construction (`obj.newProp = x`) on objects
  used in hot paths.
- Object literals that flow into the same function should have keys in the
  same order:
- Use tuples for very small fixed-size records when names are not needed.
  Tuples avoid key-order pitfalls entirely.

```ts
// GOOD — same key order, shares hidden class
const a = { type: 'static', value: 1 }
const b = { type: 'dynamic', value: 2 }

// BAD — different key order, different hidden classes
const a = { type: 'static', value: 1 }
const b = { value: 2, type: 'dynamic' }
```

### Real Codebase Example

`Span` in `src/trace/trace.ts` initializes all fields in the constructor in a
fixed order — `name`, `parentId`, `attrs`, `status`, `id`, `_start`, `now`.
This ensures all `Span` instances share one hidden class.

## Monomorphic vs Polymorphic vs Megamorphic

V8's inline caches (ICs) track the types/shapes seen at each call site or
property access:

| IC State        | Shapes Seen | Speed                                 |
| --------------- | ----------- | ------------------------------------- |
| **Monomorphic** | 1           | Fastest — single direct check         |
| **Polymorphic** | 2–4         | Fast — linear search through cases    |
| **Megamorphic** | 5+          | Slow — hash-table lookup, no inlining |

Once an IC goes megamorphic it does NOT recover (until the function is
re-compiled). Megamorphic ICs also **prevent Turbofan from inlining** the
function.

### Keep Hot Call Sites Monomorphic

```ts
// GOOD — always called with the same argument shape
function processChunk(chunk: Uint8Array): void {

From evgeshniyzik-dev/nextjs, MIT.

More from evgeshniyzik-dev/nextjs