Automatic Semicolon Insertion: 7 Rules and Classic Traps

Chapter 31: Automatic Semicolon Insertion (ASI) — The Most Dangerous Implicit Rule in the Spec

JavaScript is not a "semicolons optional" language — it's a language with "implicit semicolon insertion." These two descriptions have a fundamental difference.

Core question of this chapter: How do the three rules of ASI (Automatic Semicolon Insertion) defined in ECMAScript §12.10 produce counter-intuitive behavior, and why do even experienced developers get burned by return, [, and ( ?

After reading this chapter you will understand:

• The three ASI trigger conditions in ECMAScript §12.10 and their precise boundaries
• Why lines starting with (, [, /, +, - never trigger ASI (the complete mechanism)
• Spec-defined behavior when return/throw/break/continue are followed by a newline
• The real underlying reason Prettier and ESLint recommend semicolons
• The complete prerequisites for no-semicolon style to operate safely

Level 1 · What You Need to Know (1-3 Years Experience)

The core fact about ASI is: when the JavaScript engine parses source code left-to-right, if a token at a given position violates the current grammar rules, the engine attempts to insert a semicolon at that position and retry. This is not the engine "forgiving" you for not writing a semicolon — it's the engine actively rewriting your code's structure.

The Most Common Manifestation of ASI

// What you write
let a = 1
let b = 2
console.log(a + b)

// What the engine actually processes
let a = 1;
let b = 2;
console.log(a + b);

Most of the time, ASI produces results that match your expectations. The danger comes from a minority of scenarios where ASI inserts semicolons in different positions than you intend.

Five Categories of Dangerous Line-Start Characters

The following five characters at the start of a line never trigger ASI, because they can legally continue the previous line:

These five character categories have caused production incidents in many "no-semicolon" style codebases.

The Most Typical Accident Scenarios

// Scenario 1: IIFE pattern — chain reaction without semicolons
const a = 1
const b = 2

(function() {
  console.log('IIFE')
})()

What the engine actually parses:

const a = 1;
const b = 2(function() {    // ❌ 2 is treated as a function call! TypeError: 2 is not a function
  console.log('IIFE')
})();

// Scenario 2: Array after chained method call
const result = [1, 2, 3]
  .map(x => x * 2)

const first = result
[0]  // ❌ Actually result.map(x => x * 2)[0], not result[0]

// Scenario 3: return followed by newline (the most insidious)
function getObject() {
  return
  {
    name: 'Alice'
  }
}

console.log(getObject())  // undefined, not { name: 'Alice' }

Safe Writing Patterns

// Method 1: Always write semicolons
const a = 1;
(function() { console.log('IIFE'); })();

// Method 2: no-semicolon style with defensive semicolons before dangerous characters
const a = 1
;(function() { console.log('IIFE'); })()
;[1, 2, 3].forEach(x => console.log(x))

// Method 3: Never put a newline between return and the value
function getObject() {
  return {
    name: 'Alice'  // Correct: { is on the same line as return
  };
}

Level 2 · How It Works (3-5 Years Experience)

The Three Rules of ASI (Simplified §12.10)

The ECMAScript specification defines three rules that cover all ASI trigger scenarios:

Rule 1: Line Terminator Trigger

When the parser encounters a token (called the "offending token") that is not allowed by any production of the grammar, and there is at least one line terminator between the offending token and the previous token, a semicolon is inserted before the offending token.

Condition: newline after previous token + current token cannot continue syntax
Result: insert semicolon before current token

Rule 2: End of Input Stream Trigger

When the parser reaches the end of the input stream and the current program cannot be parsed as a complete program, a semicolon is inserted at the end.

Condition: end of file + current syntax is incomplete
Result: insert semicolon at end of file

Rule 3: Restricted Productions

Certain specific syntactic constructs are marked as "restricted productions." In these constructs, line terminators are not allowed at specific positions. If a line terminator appears at such a position, a semicolon is forcibly inserted there, regardless of whether the following token could continue the syntax.

Restricted productions list:

Detailed Analysis of Restricted Productions

// throw followed by newline: immediate SyntaxError
function f() {
  throw
    new Error('msg')  // SyntaxError: Illegal newline after throw
}

// break followed by newline: label lost
outer: for (let i = 0; i < 3; i++) {
  inner: for (let j = 0; j < 3; j++) {
    if (i === 1 && j === 1) {
      break
      outer  // ← this line never executes! break already ended on previous line
    }
  }
}

// Postfix ++ with newline: becomes prefix
let x = 5
let y = x
++  // this ++ is parsed as prefix
// Actual parsing: y = x; ++undefined → parse-level analysis is more complex

Postfix Operators and the Subtle Relationship with ASI

let x = 5
let y = x  // ASI inserts semicolon: let y = x;
++x        // prefix ++, x becomes 6, y is 5

// Compare: same line
let x = 5
let y = x++  // postfix ++, y is 5, x becomes 6

Postfix ++/-- are restricted productions — line terminators are not allowed between the operand and ++. So:

x
++
y
// Parsed as: x; ++y; (two statements, y prefix-incremented)
// NOT: x++; y; (x postfix-incremented followed by y)

Complete ASI Determination Flow

Parser reads next token
        │
        ▼
  Can current token continue syntax?
    /               \
  Yes               No
  │                  │
  Continue         Newline before current token?
                  /              \
                Yes               No
                │                  │
        Is restricted production?  Report SyntaxError
           /          \
         Yes            No
          │              │
    Insert semicolon   Insert semicolon
    Retry parse        Retry parse

Scenarios That Absolutely Will Not Trigger ASI

Understanding "will not trigger" is just as important as understanding "will trigger":

// 1. Semicolons in for loop headers cannot be supplied by ASI
for (let i = 0     // ← syntax requires ;, but this is not ASI, must be explicit
     ; i < 10
     ; i++) {}

// 2. Empty statement semicolons
;  // this semicolon must be explicitly written, not supplied by ASI

// 3. Inside multi-line expressions
const x = 1 +
          2  // no semicolon inserted, because 1 + is valid (right side expects operand)

Level 3 · How the Spec Defines It (Senior Developers)

ECMAScript §12.10 Original Text

The ECMAScript 2024 specification's definition of ASI (§12.10 Automatic Semicolon Insertion):

12.10.1 Rules of Automatic Semicolon Insertion

In the following cases, a semicolon is automatically inserted into the token stream of the source text:

Rule 1: When, as the Script or Module is parsed from left to right, a token (called the offending token) is encountered that is not allowed by any production of the grammar, then a semicolon is automatically inserted before the offending token if one or more of the following conditions is true:

• The offending token is separated from the previous token by at least one LineTerminator.
• The offending token is }.
• The previous token is ) and the inserted semicolon would then be parsed as the terminating semicolon of a do-while statement (13.7.4).

Rule 2: When, as the Script or Module is parsed from left to right, the end of the input stream of tokens is encountered and the parser is unable to parse the input token stream as a single instance of the goal nonterminal, then a semicolon is automatically inserted at the end of the input stream.

Rule 3: When, as the Script or Module is parsed from left to right, a token is encountered that is allowed by some production of the grammar, but the production is a restricted production and the token would be the first token for a terminal or nonterminal immediately following the annotation [no LineTerminator here] within the restricted production (and therefore such a token is called a restricted token), and the restricted token is separated from the previous token by at least one LineTerminator, then a semicolon is automatically inserted before the restricted token.

Commentary on Rule 1: The precise conditions are: current token violates grammar AND (① there's a newline between them, ② OR current token is }, ③ OR it's the closing ) of a do-while). Note the special case of } — it triggers ASI even without a newline:

function f() { let x = 1 }  // ASI inserts semicolon before }
// equivalent to
function f() { let x = 1; }

Commentary on Rule 3: "Restricted productions" are annotated with [no LineTerminator here] in the grammar. For example, the production for return:

ReturnStatement:
  return ;
  return [no LineTerminator here] Expression ;

This means after the return keyword, if a line terminator appears before the Expression, Rule 3 immediately forces semicolon insertion, resulting in return; (returns undefined).

Interaction Between Lexical Grammar and Syntactic Grammar

ASI occurs at the boundary between the Lexical Grammar and the Syntactic Grammar. The Lexer produces a token stream; the Parser consumes it.

The spec's lexical grammar defines LineTerminator:

LineTerminator ::
  <LF>   (U+000A, LINE FEED)
  <CR>   (U+000D, CARRIAGE RETURN)
  <LS>   (U+2028, LINE SEPARATOR)
  <PS>   (U+2029, PARAGRAPH SEPARATOR)

LineTerminatorSequence ::
  <LF>
  <CR> [lookahead ≠ <LF>]
  <LS>
  <PS>
  <CR><LF>

Note: U+2028 (LINE SEPARATOR) and U+2029 (PARAGRAPH SEPARATOR) are also line terminators. Before ES2019, this caused issues because JSON strings can contain these characters but pre-ES2019 JavaScript string literals could not. ES2019 (ES10) fixed this:

ES2019 §B.1.2: The source code for ECMAScript programs is now allowed to contain the Unicode code points U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR in string literals.

ASI Implementation in V8

In V8's source code, ASI handling occurs in the Expect() and ExpectSemicolon() functions in the parser:

src/parsing/parser-base.h
  → ParserBase::ExpectSemicolon()
    → Check if current token is Token::SEMICOLON
    → If not, check for line terminator flag (has_line_terminator_before_next_)
    → Determine whether to insert virtual semicolon based on rules

V8's lexer sets the has_line_terminator_before_next_ flag when scanning tokens, which the parser uses for ASI decisions. This design makes ASI checking O(1) — no backtracking required.

ASI and Strict Mode

Strict mode does not change ASI triggering rules, but some ASI results produce different errors in strict mode:

'use strict'
with (obj) {  // SyntaxError in strict mode, unrelated to ASI
  x = 1
}

Interestingly, the 'use strict' directive itself depends on ASI (ASI inserts a semicolon after the string literal statement), creating an interesting self-referential relationship: the strict mode declaration uses the very feature it governs.

Level 4 · Edge Cases and Traps (All Experience Levels)

Trap 1: ASI Disasters After Module Bundling

Suppose you write two independent files in no-semicolon style, and a bundler concatenates them:

// file1.js (no-semicolon style, runs fine on its own)
const x = getData()
export default x

// file2.js (no-semicolon style, runs fine on its own)
[1, 2, 3].forEach(process)

After concatenation:

const x = getData()
export default x
[1, 2, 3].forEach(process)
// ↑ export default x[1, 2, 3].forEach(process) — semantics completely changed!

This bug produces no build-time error. At runtime, x is not correctly exported, [1,2,3] is parsed as an index operation, and forEach is treated as property access. In real production incidents, debugging this type of bug takes an average of 2-4 hours, because single-file tests work completely normally.

Fix: Bundlers like Rollup automatically insert semicolons at module boundaries, but only when configured correctly. Webpack's concatenateModules optimization (scope hoisting) also handles this, but behavior varies between versions.

Trap 2: JSON.parse and ASI — No Relationship, But Easy to Confuse

// You might think newlines in JSON files trigger ASI
// In reality JSON is not JavaScript at all — there is no ASI

const data = JSON.parse(`
{
  "name": "Alice"
  "age": 30
}
`)
// SyntaxError: JSON.parse fails — JSON does not support ASI!
// JSON commas are mandatory, not optional

This trap catches developers who confuse JavaScript config objects with JSON. Commas between JSON key-value pairs are required by the JSON specification (RFC 8259), completely unrelated to JavaScript ASI.

Trap 3: ASI Behavior in Class Field Declarations (ES2022 Feature)

class Counter {
  count = 0

  // Does ASI insert a semicolon here?
  increment() {
    this.count++
  }
}

Class field declarations use the ClassElement production. When ES2022 introduced class fields, ASI behavior between field declarations required careful specification. The spec clarifies: newlines after field declarations trigger ASI, which usually matches expectations.

The danger appears in:

class Broken {
  [Symbol.iterator]  // field declaration
  = function*() { yield 1 }  // initializer

  // vs

  [Symbol.iterator]() {  // method declaration
    // ...
  }
}

If you put a newline after [Symbol.iterator] and then write = ..., ASI might parse it as a method call rather than a field initializer, causing a SyntaxError. This behavior had discrepancies between engine implementations (V8 bug #9248, fixed in Node.js 12.3).

Trap 4: Iteration Variable Declaration in for...of and for...in

// Especially dangerous in no-semicolon style
const items = [1, 2, 3]
for (const item of items) console.log(item)

// If the above is:
const result = getResult()
for (const item of result) console.log(item)  // 'of' is a keyword here, OK

// But if getResult() return value has a [ after it:
const result = getResult()
[Symbol.iterator]  // ← parsed as getResult()[Symbol.iterator]

Trap 5: Dynamic import() and ASI

// import() is function-call syntax, so import( at line start doesn't trigger ASI
const module = loadConfig()
import('./module.js').then(m => m.default)

// Actual parse: loadConfig()import('./module.js') → SyntaxError
// because import is a keyword, cannot be used as a method call!
// Real error message: SyntaxError: Cannot use import statement outside a module
// or: SyntaxError: Unexpected token 'import'

In practice, when import() starts a line, modern parsers correctly identify it as a dynamic import expression rather than a function call continuation. This behavior only stabilized after ES2020 formally defined it. In Babel-transpiled code, import() becomes require(), which is an actual function call — and a line-starting require( will trigger the above problem.

Prettier and ESLint's Semicolon Policy

Prettier defaults to adding semicolons (semi: true), not because "semicolons are better," but due to these engineering considerations:

1. Bundle safety: Semicolons eliminate ASI boundary issues during file concatenation
2. Diff-friendly: Line-ending semicolons make git diffs cleaner (moving code doesn't require modifying the trailing comma/semicolon of the moved line)
3. Error localization: With semicolons, parse error line numbers are more precise
4. Team consistency: Either choice works; Prettier chose semicolons as the default

ESLint's semi rule supports both "always" and "never", plus an "exceptBeforeBlock" option allowing semicolons to be omitted before { (because { is a safe line-start character).

Standard.js (a popular no-semicolon style guide) has a built-in no-unexpected-multiline rule specifically for detecting the five dangerous line-start character scenarios. In other words, safe no-semicolon style relies on linters to compensate for ASI's dangerous edge cases.

The Engineering Trade-off Between ASI and No-Semicolon Style

Semicolon style
  Advantages: bundle-safe, precise error localization, no need to memorize ASI rules
  Disadvantages: more verbose (1 extra char per line), beginners sometimes miss them

No-semicolon style (Standard.js / optional Airbnb)
  Advantages: cleaner code, unified with Python/Ruby/Swift style
  Disadvantages: must pair with linter rules, dangerous line starts need defensive semicolons,
                 increased bundler dependency

Conclusion: Both styles are viable engineering choices.
            Key requirements: team consistency + linter enforcement + understanding ASI boundaries.
            Using no-semicolon style without understanding ASI is leaving a time bomb.

Chapter Summary

1. ASI is not syntactic sugar — it's a spec-defined syntax repair mechanism: the engine actively inserts semicolons and retries when parsing fails, rather than simply "allowing semicolons to be omitted."

2. Priority of the three rules: Rule 3 (restricted productions) has highest priority and forcibly inserts semicolons even when syntax could continue; Rule 1 requires a newline; Rule 2 handles end of file.

3. Five categories of dangerous line-start characters ((, [, /, +, `) do not trigger ASI because they can legally continue the previous line's syntax — this is the primary risk of no-semicolon style.

4. return, throw, break, continue followed by newlines are restricted productions, immediately triggering semicolon insertion and causing unexpected behaviors like return undefined — the most frequent source of ASI production bugs.

5. The correct engineering approach: regardless of which style you choose, linter enforcement is required (semi: always or no-unexpected-multiline). Understanding ASI rules is for quickly locating problems when rules produce unexpected results — not for challenging the rules.