How to fix Triple-slash directive 'reference' must be at top of file in TypeScript
TypeScript requires `/// <reference path="..." />` directives to live before any imports, exports, or executable statements. Drop them farther down the file and the compiler refuses to run, so keep those directives at the very top or move the code into a module that uses imports instead.
Quick fix
Fixes Triple-slash directive 'reference' must be at top of file
- Inspect the file and locate the directive
- Move the directive to the absolute top of the file
- Consider using module imports rather than a triple-slash reference
- Use a separate declaration file for chained references
# Triple-slash directive 'reference' must be at top of fileTriple-slash directive 'reference' must be at top of file
What this error means
A triple-slash reference tells the compiler which declaration files or modules to pull in before processing the rest of the current file. During a preprocessing pass TypeScript scans for these directives and resolves them depth-first, so they must be the first tokens in their file. If you place any import, export, string literal, or other statement before a `/// <reference path="..." />` line, the compiler throws this error because it can no longer trust the directive order.
Typical symptoms
- The TypeScript compiler prints `Triple-slash directive 'reference' must be at top of file' and stops the build
- Your IDE highlights the offending `/// <reference ... />` line in red and visualizes a compile error badge on that file
- Continuous integration or `npm run build` fails immediately when tsc reaches the file with the directive
- A full-screen error like this often fingerprints files that mix triple-slash references with modern imports
- Dependent declaration files are ignored because the directive never runs before other statements
Common causes
- You inserted the `/// <reference path="..." />` line below an import/export, const, require, or other statement instead of above everything else
- You added 'use strict' or some other string literal before the directive, and TypeScript sees that token first
- A code generator emitted a triple-slash directive after a module wrapper or namespace declaration
- You tried to put a triple-slash directive inside a conditional block or after a namespace export instead of leaving it at the top-level head of the file
How to fix "Triple-slash directive 'reference' must be at top of file"
Find every /// <reference path="..." /> in the file and see what sits above it. Any import, export, const declaration, 'use strict' line, or even a blank line with inline code counts as preceding statements that trigger the error. The directive must be the very first non-comment thing in the file before the compiler can evaluate it.
Cut the triple-slash directive and paste it before any other statements, leaving only other triple-slash lines or whitespace above it. If multiple references are required, keep them stacked in the order the compiler should consume them. TypeScript only accepts them as part of the file head, so any rearrangement downstream will re-trigger the error.
If the file also needs imports or exports, prefer import/export syntax over triple-slash references. Imports can live throughout the head of a module and do not require being processed before other statements. Move legacy triple-slash references into dedicated .d.ts files that simply record the directives at the top, then import those typings instead.
When you must keep a triple-slash path, create a bare .d.ts file whose only content is the stack of /// <reference path="..." /> directives. That file can remain at the top of your project, or be listed in tsconfig files or include, so your module files stay clean and can safely use imports without kicking off the triple-slash restriction.
Advanced notes
Triple-slash reference directives are a legacy way to pull in *.d.ts files before module imports existed. The compiler parses them in a preprocessing phase, so they can only ever appear at the head of a file. Modern TypeScript projects almost always rely on import/export syntax, tsconfig typeRoots, or project references instead, which do not have this restriction. If you still need /// <reference path="..." />, limit them to pure declaration files marked with declare statements, or keep them in generated files whose entire contents are the stacked directives so that no other code ever precedes them.
Frequently asked questions
- What does "Triple-slash directive 'reference' must be at top of file" mean?
- A triple-slash reference tells the compiler which declaration files or modules to pull in before processing the rest of the current file. During a preprocessing pass TypeScript scans for these directives and resolves them depth-first, so they must be the first tokens in their file. " /> line, the compiler throws this error because it can no longer trust the directive order.
- How do I fix "Triple-slash directive 'reference' must be at top of file"?
- TypeScript requires /// <reference path="..." /> directives to live before any imports, exports, or executable statements. Drop them farther down the file and the compiler refuses to run, so keep those directives at the very top or move the code into a module that uses imports instead.
- What causes "Triple-slash directive 'reference' must be at top of file"?
- You inserted the /// <reference path="..." /> line below an import/export, const, require, or other statement instead of above everything else You added 'use strict' or some other string literal before the directive, and TypeScript sees that token first A code generator emitted a triple-slash directive after a module wrapper or namespace declaration
- Is the "Triple-slash directive 'reference' must be at top of file" error serious?
- It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.