Tiered compilation

Start simple, then specialize

A JavaScript engine is the program inside a browser or Node that runs your code. When a page loads, the engine does not know which functions will matter. A small helper might run once. A function that draws each frame of an animation might run thousands of times.

The engine can run a function in two broad ways:

• Read it one step at a time. This starts at once, but runs slowly.
• First turn it into machine code, the instructions the computer's chip runs directly. This takes time first, but then runs fast.

Turning code into machine code is called compiling. The time it takes is the compile cost. Tiered compilation is the engine's plan: start every function the cheap way, watch which ones run a lot, and spend compile time only on those.

This lesson covers:

• interpreters, compilers, and JIT compilers;
• the tier names in V8, SpiderMonkey, and JavaScriptCore;
• the counters that decide when code moves up a tier.

The next lessons go deeper on type feedback and inline caches. Later lessons cover what the engine does when its guesses about your code turn out wrong. For the bigger picture, go back to Meet the engines, Bytecode & interpreters, and Startup performance.

There are three ways to run code. Each one pays its cost at a different time:

• An interpreter runs bytecode, a simple list of steps the engine makes from your code. It runs one step at a time. It starts almost at once. But every step costs a little extra, because the interpreter must look up what each step means.
• An ahead-of-time compiler turns the whole program into machine code before it runs. The result runs fast. But doing this for every function on a page would make the page slow to start.
• A just-in-time (JIT) compiler compiles while the program is already running. It waits until a function has run enough to show that the compile cost will pay back.

The code below is a cost model. It uses made-up time units to show the idea. It is not real engine timing.

1function totalTime(compileCost, callCost, calls) {2  return compileCost + callCost * calls;3}4 5console.log(totalTime(0, 5, 4));      // interpreter: cheap start6console.log(totalTime(120, 0.6, 4));  // top tier: too much compile cost7console.log(totalTime(120, 0.6, 400)); // top tier: compile cost pays back

• Line 1 defines totalTime. It takes the compile cost, the cost of one call, and the number of calls.
• Line 2 adds the compile cost to the cost of all the calls.
• Line 5 is the interpreter: nothing to compile, 5 units per call, 4 calls. It prints 20.
• Line 6 is the top tier with only 4 calls: 120 to compile, 0.6 per call. It prints 122.4. The compile cost is far bigger than the time the fast calls save.
• Line 7 is the top tier with 400 calls. It prints 360. The interpreter would need 2000 units for 400 calls, so here compiling pays back.

Each row of the next table is one tier. Read across to see how long the tier takes to build, how fast its code runs, and what code it suits. Not every function climbs all the tiers; most stay low.

V8 is the engine in Chrome and Node. It has four tiers, in this order:

• Ignition is the interpreter. It runs bytecode.
• Sparkplug is a baseline compiler. It turns bytecode straight into simple machine code, without trying to make it clever. V8 announced it in 2021. It is quick enough to help code that only runs for a short time.
• Maglev is a mid-tier optimizing compiler. An optimizing compiler uses what it has seen the code do to make faster machine code. Maglev makes good-enough code quickly. It arrived in Chrome M117 in 2023.
• TurboFan is the top tier. It spends the most compile time to make the fastest code.

TurboFan's inside is changing too. Before a compiler makes machine code, it turns your code into a working form of its own. TurboFan used a form called "Sea of Nodes". V8's 2025 post "Land ahoy: leaving the Sea of Nodes" describes the move to a new back end called Turboshaft. Turboshaft uses a form that keeps the code's steps in order, called a control-flow graph.

Other engines use the same plan with different names.

SpiderMonkey is Firefox's engine. It keeps a warm-up counter for each function. The counter goes up each time the function starts, and each time one of its loops goes round. SpiderMonkey's tiers are:

• the C++ interpreter;
• the Baseline Interpreter;
• the Baseline Compiler;
• Ion, the optimizing compiler.

In 2020, the Warp project changed how Ion gets its information. A part called WarpBuilder saves a copy of the bytecode and of what the code has seen so far. Then Ion's working form of the code, called MIR, is built on a background thread. A background thread is a second line of work, so the page does not have to wait for it.

JavaScriptCore is Safari's engine. Its tiers are LLInt (the interpreter), Baseline JIT, DFG, and FTL. WebKit's 2016 B3 post explains that FTL moved from the LLVM back end to its own B3 back end. WebKit's 2020 post on speculation explains how JavaScriptCore makes careful guesses about your code so it can run it fast.

The details differ, but the shape is the same: a cheap start, a quick baseline tier, then stronger optimizing tiers.

Each row of the next table is one engine. Read across from the tier where code starts to the top tier.

The engine needs a sign that code is hot. The simplest sign is a call counter: each call to a function adds 1. When the count reaches a set number, called a threshold, the engine moves the function to a stronger tier. This is called tiering up.

Real engines use more signals than one counter:

• how many times a function was called;
• how many times its loops went round;
• feedback: notes about the kinds of values the code has seen;
• other rules that each engine picks.

The optimizing compile can run on a background thread. Meanwhile, the main thread (the one running your page) keeps running the older, slower code until the new code is ready.

1const thresholds = { baseline: 6, mid: 30, top: 90 };2let tier = "interpreter";3let invocationCount = 0;4 5function scoreCart(items) {6  invocationCount += 1;7  if (invocationCount === thresholds.baseline) tier = "baseline";8  if (invocationCount === thresholds.mid) tier = "mid";9  if (invocationCount === thresholds.top) tier = "top";10  return { tier, total: items.reduce((sum, item) => sum + item.price, 0) };11}12 13for (let call = 1; call <= 8; call += 1) {14  const report = scoreCart([{ price: call }, { price: 2 }]);15  console.log(call, report.tier, report.total);16}

• Line 1 sets the thresholds: baseline at call 6, mid tier at call 30, top tier at call 90.
• Line 2 starts the function in the "interpreter" tier.
• Line 6 adds 1 to invocationCount on every call. An invocation is a call.
• Lines 7 to 9 switch the tier when the count reaches a threshold.
• Lines 14 and 15 call the function 8 times and print the call number, the tier, and the total.

Calls 1 to 5 print interpreter. Call 6 prints 6 baseline 8. The number 6 is only a choice made for this model. What matters is that the tier changes because of what the running code did.

1const observedInputs = new Set();2 3function add(left, right) {4  observedInputs.add(typeof left + "/" + typeof right);5  const state = observedInputs.size === 1 ? "stable" : "mixed";6  return String(left + right) + " " + state;7}8 9console.log(add(2, 3));10console.log(add(4, 5));11console.log(add("4", 5));

This model keeps a Set, a list with no repeats, of the kinds of values add has seen. typeof gives the kind of a value, such as "number" or "string".

• Line 4 saves the pair of kinds, such as "number/number".
• Line 5 says "stable" if only one pair was ever seen, and "mixed" if more than one was.
• Lines 9 and 10 pass two numbers. They print 5 stable and 9 stable.
• Line 11 passes the string "4" and the number 5. + joins them into "45". A new pair is seen, so it prints 45 mixed.

So the engine watches two different signals:

• Running often (heat) tells it that compiling may pay back.
• Seeing the same kinds of values (feedback) tells it that fast code made just for those kinds is likely to work.

Real engines keep much richer feedback than this Set.

1const thresholds = { baseline: 6, mid: 30, top: 90 };2let tier = "interpreter";Run3let invocationCount = 0;4 5function scoreCart(items) {6  invocationCount += 1;7  if (invocationCount === thresholds.baseline) tier = "baseline";8  if (invocationCount === thresholds.mid) tier = "mid";9  if (invocationCount === thresholds.top) tier = "top";10  return { tier, total: items.reduce((sum, item) => sum + item.price, 0) };11}12 13for (let call = 1; call <= 8; call += 1) {14  const report = scoreCart([{ price: call }, { price: 2 }]);15  console.log(call, report.tier, report.total);16}

Counting calls is not enough. One call can run a long loop. So engines also watch how far loops get. In the next model, a number called interruptBudget goes down on every step of the loop. When it reaches 0, the engine knows the loop is hot.

1let tier = "interpreter";2let interruptBudget = 18;3 4function crunchLoop(limit) {5  let total = 0;6  for (let i = 1; i <= limit; i += 1) {7    interruptBudget -= 3;8    if (interruptBudget <= 0 && tier === "interpreter") {9      tier = "baseline"; // model collapses request, compile, install, and OSR entry10      interruptBudget = 18;11    }12    total += i;13  }14  return { tier, total };15}16 17console.log(crunchLoop(8));

• Lines 1 and 2 start in the interpreter with a budget of 18.
• Line 7 takes 3 from the budget on each step of the loop.
• Line 8 checks whether the budget has run out while the loop is still in the interpreter.
• Line 9 switches the tier to "baseline". Line 10 sets the budget back to 18.
• Line 17 calls crunchLoop(8) once. It prints { tier: 'baseline', total: 36 }.

The budget reaches 0 on step 6, so the switch happens in the middle of the loop. Moving a running loop into compiled code, without starting the function over, is called on-stack replacement, or OSR. This lesson shows only the idea. A later lesson shows how it works inside the engine.

1let tier = "interpreter";Run2let interruptBudget = 18;3 4function crunchLoop(limit) {5  let total = 0;6  for (let i = 1; i <= limit; i += 1) {7    interruptBudget -= 3;8    if (interruptBudget <= 0 && tier === "interpreter") {9      tier = "baseline"; // model collapses request, compile, install, and OSR entry10      interruptBudget = 18;11    }12    total += i;13  }14  return { tier, total };15}16 17console.log(crunchLoop(8));

The playground compares three plans on the same cost model:

• Never optimize: every call runs in the interpreter.
• Optimize eagerly: compile every function to the top tier before it runs. "Eagerly" means right away, before knowing whether it is needed.
• Tiered JIT: start in the interpreter, and move a function up only when it crosses a threshold.

Try both programs:

• In the short script, no function runs often enough to pay back a compile. Never optimizing costs the least, and the tiered JIT ties with it.
• In the long session, one function, format, runs 160 times. The tiered JIT costs the least, because it compiles only format.

1const costs = {2  interpreter: { compile: 0, call: 5 },3  baseline: { compile: 15, call: 2 },4  mid: { compile: 40, call: 1.2 },5  top: { compile: 120, call: 0.6 },6};7 8const program = [9  { name: "route", calls: 3 },10  { name: "format", calls: 160 },11  { name: "validate", calls: 3 },12  { name: "paint", calls: 3 },13  { name: "cleanup", calls: 3 },14];15 16// A real engine uses richer counters, feedback, and background compilation.17// This model only shows the compile-time vs run-time trade-off.18console.log("never optimize", 860);19console.log("optimize eagerly", 703.2);20console.log("tiered JIT", 422.6);

Optimizing eagerly pays the top-tier compile cost of 120 for all five functions, even the ones called only 3 times. The tiered JIT pays compile costs only for functions that cross a threshold.

In a real program, other things can change which plan wins:

• feedback that keeps changing;
• compiled code that has to be thrown away;
• compiles that have not finished yet;
• limits on memory.

The idea that stays true: spend compile time where the running code shows it will pay back.

V8 has hidden testing functions whose names start with %. Node lets you use them only when you start it with the flag --allow-natives-syntax. A flag is an option you type after the command. These functions are not part of JavaScript. Without the flag, a browser or Node treats the % as a syntax error.

The lesson tests start separate Node processes to check real facts. First they remove the NODE_TEST_* settings, so the test runner does not change the child process. Then they check only facts that are the same on every run:

• the version numbers;
• which V8 options are on by default;
• status bits from V8 12.4's runtime.h file;
• lines from --trace-opt that mention TurboFan compiling.

1// Node 22.23.1 (V8 12.4). Run only in Node with --allow-natives-syntax.2function hotAdd(x) {3  let total = 0;4  for (let i = 0; i < 30; i += 1) total += (x + i) | 0;5  return total;6}7 8%PrepareFunctionForOptimization(hotAdd);9hotAdd(1);10hotAdd(2);11%OptimizeFunctionOnNextCall(hotAdd);12hotAdd(3);13console.log(%GetOptimizationStatus(hotAdd));

• Line 1 says this runs only in Node with --allow-natives-syntax.
• Line 8 tells V8 to start collecting feedback for hotAdd.
• Line 11 asks V8 to optimize hotAdd on its next call. Line 12 makes that call.
• Line 13 prints the optimization status, one number made of status bits.

A status bit is a yes-or-no answer packed into one number. In V8 12.4 these bits include:

• kIsFunction = 1 << 0: this is a function;
• kOptimized = 1 << 4: it has optimized code;
• kTurboFanned = 1 << 6: that code came from TurboFan.

Forcing optimization this way gives the same result every time, so it works in a test. It is still a lab tool. Do not ship code that uses % functions or depends on a certain tier.

node --allow-natives-syntax --trace-opt tier-up-probe.mjs

Node 22.23.1 (V8 12.4)
[manually marking ... hotAdd ... for optimization to TURBOFAN]
[compiling method ... hotAdd ... (target TURBOFAN)]
[completed compiling ... hotAdd ... (target TURBOFAN)]
status bits include kIsFunction, kOptimized, and kTurboFanned

Tiered compilation explains two things you will meet in real work:

• Why a benchmark (a timing test) needs a warm-up. The first runs are slower while the engine is still moving code up the tiers.
• Why short scripts often never reach a top tier.

It does not mean you should write code for Sparkplug, Maglev, TurboFan, Ion, or FTL. Engine teams change thresholds, tier names, and rules. Your job is to:

• write clear code;
• measure the real thing the user does;
• warm up a benchmark before you time it;
• expect the first few runs to differ from later runs.

Each row of the next table is a situation you may meet. Read across to see what tiering tells you and what to do.

If a benchmark changes after warm-up, see Measuring performance. If a hot function behaves differently after its inputs change, the next lessons on type feedback and inline caches explain what the optimizer looks at.

Common misconceptions

Each row of the next table is one idea. Read across to see what it means and what it does not mean.

Keep the cost model, the tier names, and the counters in mind.

Key takeaways

• An interpreter starts quickly. A compiler makes faster code, but costs time first. A JIT compiler decides, while the program runs, what is worth compiling.
• V8's tiers are Ignition, Sparkplug, Maglev, and TurboFan. TurboFan's back end is moving from Sea of Nodes to Turboshaft.
• SpiderMonkey and JavaScriptCore use other names but the same plan: spend more compile time on hotter code.
• Engines spot hot code by counting calls and loop steps, and by feedback about values. OSR lets a running loop switch tiers.
• Warm up benchmarks, expect short scripts to stay in cheap tiers, and never write real app code for one engine tier.

Up next: Type feedback & feedback vectors.