JS with Types Start

TypeScript error

TS8008: A type alias in a .js file

  • Error TS8008
  • Tested with TypeScript 5.9

error TS8008: Type aliases can only be used in TypeScript files. is reported for a type Status = ... declaration in a .js file. It is TypeScript syntax, and JavaScript would reject it.

The JSDoc equivalent is /** @typedef {...} Status */: the type inside the braces is written exactly as on the right of the =. In a module, the typedef is exported automatically and other files can import it with @import.

At a glance

CodeTS8008
MessageType aliases can only be used in TypeScript files.
TypeScript's categoryerror
Listed underJavaScript files only
Turned on by No option: every checked file reports it
In .js files Reported when the file is checked: checkJs in jsconfig.json, or // @ts-check at the top of the file

The message is TypeScript's own text from its diagnostic messages file (Apache-2.0).

What it looks like

order.js Error confirmed 5.9.3 TypeScript 5.9.3, run 21 October 2026: order.js(2,6): error TS8008: Type aliases can only be used in TypeScript files. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. order.js(2,6): error TS8008: Type aliases can only be used in TypeScript files. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. order.js(2,6): error TS8008: Type aliases can only be used in TypeScript files. checked 21 October 2026 
type Status = "pending" | "shipped" | "cancelled";error TS8008: Type aliases can only be used in TypeScript files.

/** @param {Status} status */
export function label(status) {
  return status.toUpperCase();
}
A type alias in a .js file.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": ["*.js"]
}

What causes it

  • A type alias was pasted from TypeScript code.

How to fix it

Write it as a @typedef

Move the type into a @typedef comment, keeping the name. Unions, object types, generics (with @template) and utility types all work inside the braces.

order.js TypeScript 5.9.3 TypeScript 5.9.3, run 21 October 2026: No errors. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. No errors. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. No errors. checked 21 October 2026 
/** @typedef {"pending" | "shipped" | "cancelled"} Status */

/** @param {Status} status */
export function label(status) {
  return status.toUpperCase();
}
The alias as a @typedef.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": ["*.js"]
}

Gotchas

  • A @typedef is visible in the whole file regardless of where it is written, like a type alias; it does not need to come before its use.
  • In a file that is a script rather than a module, a top-level @typedef is global to the project.

  • JSDoc tag

    @typedef

    The JSDoc @typedef tag names a reusable type: an object type built from @property lines, a union or anything else. Every @typedef in a module is exported.

  • JSDoc tag

    @import

    The JSDoc @import tag (TypeScript 5.5 and later) brings types from another module into a .js file with ES import syntax and nothing imported at run time.

  • JSDoc tag

    @template

    The JSDoc @template tag declares type parameters for generic functions, classes and typedefs, with constraints and defaults. Syntax and checked examples.

  • TypeScript error

    TS8006: interface, enum or namespace in a .js file

    TS8006 means an interface, enum or namespace declaration was written in a .js file. Use @typedef for shapes and a frozen object with @enum for values.

  • Type expression

    Union types

    A union type says a value is one of several types: {string | number} in JSDoc, written as in TypeScript. How to write one, and how to narrow it before use.

Sources

Last reviewed 20 October 2026.