Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.awfixer.me/llms.txt

Use this file to discover all available pages before exploring further.

Module resolution in JavaScript is a complex topic. The ecosystem is currently in the midst of a years-long transition from CommonJS modules to native ES modules. TypeScript enforces its own set of rules around import extensions that aren’t compatible with ESM. Different build tools support path re-mapping via disparate non-compatible mechanisms. JSTime aims to provide a consistent and predictable module resolution system that just works. Unfortunately it’s still quite complex.

​
Syntax

Consider the following files. 
import { hello } from "./hello";

hello();
When we run index.ts, it prints “Hello world”. 
$ jstime index.ts
Hello world!
In this case, we are importing from ./hello, a relative path with no extension. To resolve this import, JSTime will check for the following files in order:
  • ./hello.ts
  • ./hello.tsx
  • ./hello.js
  • ./hello.mjs
  • ./hello.cjs
  • ./hello/index.ts
  • ./hello/index.js
  • ./hello/index.json
  • ./hello/index.mjs
Import paths are case-insensitive. 
import { hello } from "./hello";
import { hello } from "./HELLO";
import { hello } from "./hElLo";
Import paths can optionally include extensions. If an extension is present, JSTime will only check for a file with that exact extension. 
import { hello } from "./hello";
import { hello } from "./hello.ts"; // this works
There is one exception: if you import from "*.js{x}", JSTime will additionally check for a matching *.ts{x} file, to be compatible with TypeScript’s ES module support. 
import { hello } from "./hello";
import { hello } from "./hello.ts"; // this works
import { hello } from "./hello.js"; // this also works
JSTime supports both ES modules (import/export syntax) and CommonJS modules (require()/module.exports). The following CommonJS version would also work in JSTime. 
const { hello } = require("./hello");

hello();
That said, using CommonJS is discouraged in new projects.

​
Resolution

JSTime implements the Node.js module resolution algorithm, so you can import packages from node_modules with a bare specifier. 
import { stuff } from "foo";
The full specification of this algorithm are officially documented in the Node.js documentation; we won’t rehash it here. Briefly: if you import from "foo", JSTime scans up the file system for a node_modules directory containing the package foo. Once it finds the foo package, JSTime reads the package.json to determine how the package should be imported. To determine the package’s entrypoint, JSTime first reads the exports field and checks for the following conditions. 
{
  "name": "foo",
  "exports": {
    "jstime": "./index.js",
    "worker": "./index.js",
    "node": "./index.js",
    "require": "./index.js", # if importer is CommonJS
    "import": "./index.mjs", # if importer is ES module
    "default": "./index.js",
  }
}
Whichever one of these conditions occurs first in the package.json is used to determine the package’s entrypoint. JSTime respects subpath "exports" and "imports". Specifying any subpath in the "exports" map will prevent other subpaths from being importable. 
{
  "name": "foo",
  "exports": {
    ".": "./index.js",
    "./package.json": "./package.json" // subpath
  }
}
Shipping TypeScript — Note that JSTime supports the special "jstime" export condition. If your library is written in TypeScript, you can publish your (un-transpiled!) TypeScript files to npm directly. If you specify your package’s *.ts entrypoint in the "jstime" condition, JSTime will directly import and execute your TypeScript source files.
If exports is not defined, JSTime falls back to "module" (ESM imports only) then "main". 
{
  "name": "foo",
  "module": "./index.js",
  "main": "./index.js"
}

​
Path re-mapping

In the spirit of treating TypeScript as a first-class citizen, the JSTime runtime will re-map import paths according to the compilerOptions.paths field in tsconfig.json. This is a major divergence from Node.js, which doesn’t support any form of import path re-mapping. 
{
  "compilerOptions": {
    "paths": {
      "config": ["./config.ts"],         // map specifier to file
      "components/*": ["components/*"],  // wildcard matching
    }
  }
}
If you aren’t a TypeScript user, you can create a jsconfig.json in your project root to achieve the same behavior.

​
CommonJS

JSTime has native support for CommonJS modules. ES Modules are the recommended module format, but CommonJS modules are still widely used in the Node.js ecosystem. JSTime supports both module formats. In JSTime’s JavaScript runtime, require can be used by both ES Modules and CommonJS modules. If the target module is an ES Module, require returns the module namespace object (equivalent to import * as). If the target module is a CommonJS module, require returns the module.exports object (as in Node.js).
Module Typerequire()import * as
ES ModuleModule NamespaceModule Namespace
CommonJSmodule.exportsdefault is module.exports, keys of module.exports are named exports

​
What is a CommonJS module?

In 2016, ECMAScript added support for ES Modules. ES Modules are the standard for JavaScript modules. However, millions of npm packages still use CommonJS modules. CommonJS modules are modules that use module.exports to export values. Typically, require is used to import CommonJS modules. 
// my-commonjs.cjs
const stuff = require("./stuff");
module.exports = { stuff };
The biggest difference between CommonJS and ES Modules is that CommonJS modules are synchronous, while ES Modules are asynchronous. There are other differences too, like ES Modules support top-level await and CommonJS modules don’t. ES Modules are always in strict mode, while CommonJS modules are not. Browsers do not have native support for CommonJS modules, but they do have native support for ES Modules (<script type="module">). CommonJS modules are not statically analyzable, while ES Modules only allow static imports and exports.

​
Importing CommonJS from ESM

You can import or require CommonJS modules from ESM modules. 
import { stuff } from "./my-commonjs.cjs";
import Stuff from "./my-commonjs.cjs";
const myStuff = require("./my-commonjs.cjs");

​
Importing ESM from CommonJS

// this works in JSTime but not Node.js
const { stuff } = require("./my-esm.mjs");

​
Top-level await

If you are using top-level await, you must use import() to import ESM modules from CommonJS modules. 
import("./my-esm.js").then(({ stuff }) => {
  // ...
});

// this will throw an error if "my-esm.js" uses top-level await
const { stuff } = require("./my-esm.js");
JSTime’s JavaScript runtime has native support for CommonJS. When JSTime’s JavaScript transpiler detects usages of module.exports, it treats the file as CommonJS. The module loader will then wrap the transpiled module in a function shaped like this:

​
Importing CommonJS from CommonJS

You can require() CommonJS modules from CommonJS modules.
const { stuff } = require("./my-commonjs.cjs");

(function (module, exports, require) {
  // transpiled module
})(module, exports, require);
module, exports, and require are very much like the module, exports, and require in Node.js. These are assigned via a with scope in C++. An internal Map stores the exports object to handle cyclical require calls before the module is fully loaded.Once the CommonJS module is successfully evaluated, a Synthetic Module Record is created with the default ES Module export set to module.exports and keys of the module.exports object are re-exported as named exports (if the module.exports object is an object).When using JSTime’s bundler, this works differently. The bundler will wrap the CommonJS module in a require_${moduleName} function which returns the module.exports object.