For AI agents: the complete documentation index is available at /tc39-atlas/en/llms.txt, the full documentation bundle is available at /tc39-atlas/en/llms-full.txt, and this page is available as Markdown at /tc39-atlas/en/proposals/stage/unstaged/proposal-modules-pragma.md.
TC39 Atlas
  • English

      • "use module" ?

      Proposal details
      Proposal overview

      The proposal introduces an in-band pragma "use module"; to explicitly declare a source file as a module, addressing ambiguity between scripts and modules. It aims to improve portability and compatibility across host environments without relying on out-of-band mechanisms.

      Note

      The README below comes from the upstream repository and may contain outdated stage or status metadata. Use the proposal details above as the current source of truth.

      ECMAScript proposal: "use module";

      Status

      This proposal is in stage 1 of the TC39 process.

      Motivation

      Since the Script and Module syntaxes have some overlap (in particular, most modules with no import or export declarations are valid scripts), there are situations where either a host environment or simply a human reader may not be able to infer whether a piece of code is intended to be a script vs a module.

      Some host environments may offer out-of-band mechanisms for specifying the mode, such as HTML attributes (<script type=module>), configuration parameters ("module": "main.js"), command-line switches (node -m), or file extensions (.mjs). However, an in-band pragma for enforcing the mode can be useful for a number of reasons:

      • Portability: A source file that wants to work in multiple host environments can be sure to select its mode without being sensitive to configuration parameters where it's used.
      • Compatibility: If a host environment like Node chooses to use file extensions to determine the mode, some content may wish to preserve existing filenames (for example, for clients that require the module by full filename) when migrating to standard modules. An in-band opt-in makes that possible.

      Finally, the fact that this is a pragma means that ecosystems where there is no formal or conceptual ambiguity -- in particular, ecosystems that author entirely using modules -- do not need to pollute their source code.

      Alternatives

      Today, programmers can use a programming pattern to enforce that a file is a module:

      export {};

      This syntax has no effect except to force a parsing error if a host environment attempts to parse it as a script.

      This is suboptimal for readability, since it does not clearly convey what its intended effect is. It is also not applicable for solving the complementary problem of enforcing that a source file is intended to be parsed as script.

      Specification