.JS File Format – File structure

Source text

To the language, a program is a sequence of Unicode code points (ECMA-262, Source Text). Any code point from U+0000 to U+10FFFF may appear where the grammar allows it, including lone surrogates. No normalisation is applied, so two identifiers that look the same but use different code points are different names.

The standard defines four types of source code (Types of Source Code):

Since a file is one Script or one Module, the goal symbol the parser starts from decides what the text may contain.

Script:
    [ScriptBody]
ScriptBody:
    StatementList

Module:
    [ModuleBody]
ModuleBody:
    ModuleItemList
ModuleItemList:
    ModuleItem
    ModuleItemList ModuleItem
ModuleItem:
    ImportDeclaration
    ExportDeclaration
    StatementListItem

Both bodies are optional, so an empty file is a valid script and a valid module.

Scripts and modules

The same text can be valid as both and mean different things. Nothing in the file says which it is, unless it uses syntax only one goal allows.

The Modules page covers import, export and how modules are linked. The Variables and scope page covers the global object.

{
  "name": "example",
  "type": "module",
  "exports": "./index.js"
}

File extensions and media type

The media type is text/javascript (RFC 9239, May 2022), which also lists .js and .mjs. Older names such as application/javascript are now marked obsolete.

The hashbang line

A file meant to run directly on Unix-like systems may start with a line that names its interpreter. ECMA-262 has allowed this since ES2023 as a Hashbang Comment.

HashbangComment::
    #! [SingleLineCommentChars]

#!/usr/bin/env node
console.log('run directly from the shell');

• The #! must be the very first two code points of the source text. Nothing may come before it, not even white space or a byte order mark.
• The line is discarded like any other comment, up to the first line terminator.
• It is allowed at the start of a script and of a module only. A #! anywhere else is a syntax error, and new Function does not accept one.

Encoding and the byte order mark

ECMA-262 treats the text as code points, and says the encoding used to store it is not relevant to the language. In practice the encoding is UTF-8, and RFC 9239 gives these rules for files served with the JavaScript media type:

1. A leading byte order mark takes precedence: EF BB BF is UTF-8, FF FE is UTF-16 little-endian, and FE FF is UTF-16 big-endian.
2. Otherwise a valid charset parameter is used, for scripts only.
3. Otherwise the text is assumed to be UTF-8.

A module must be UTF-8, and other encodings fail. A script should be UTF-8, and others are discouraged. Save every source file as UTF-8.

The byte order mark is U+FEFF (ZWNBSP), which the language classes as white space, so a leading one does no harm. It does stop a hashbang from being recognised, because #! must come first.

Directives

A directive prologue is the longest run of expression statements, each only a string literal, at the start of a script, a module or a function body (Directive Prologues and the Use Strict Directive). Each one is a directive.

'use strict';                   // a Use Strict Directive
'custom directive';             // another directive: ignored by the language

function f() {
  "use strict";                 // applies to the function only
}

• A Use Strict Directive is a directive whose text is exactly use strict, written "use strict" or 'use strict' with no escape sequences and no line continuation. Upper case does not count.
• Other strings in the prologue are valid and do nothing to the language. Some tools give them meaning.
• A string that comes after any other statement is not a directive, just an expression statement with no effect.
• A function with a "use strict" directive may not have non-simple parameters, that is, default values, rest parameters or destructuring. It is a syntax error since ES2016.
• Module code and the code of class definitions are always strict, with or without the directive.

The Strict mode page lists everything the directive changes.

Typical layout

There are no sections in the file format, but files usually follow this order:

1. An optional hashbang.
2. An optional licence comment. Minifiers keep comments starting /*! by convention.
3. Any directives.
4. In a module, the import declarations. They may appear anywhere at the top level and are hoisted, but are normally written first.
5. Declarations and statements, with export on the declarations or in a list at the end.

#!/usr/bin/env node
/*! A small example. MIT licence. */
import { readFile } from 'node:fs/promises';

export async function wordCount(path) {
  const text = await readFile(path, 'utf8');
  return text.split(/\s+/).length;
}

console.log(await wordCount(process.argv[2]));