ESM Module Compatibility#

matrix-js-sdk is published as an ES module package ("type": "module" in package.json) and its source is compiled to lib/ via Babel. Because Node ESM does not resolve bare directory imports, every internal import in src/ must use an explicit file extension and a full index.ts path for directory entry points.

The Rules#

1. Always include the .ts extension on relative imports.

// ✅ Correct
import { foo } from "./utils.ts";

// ❌ Wrong — no extension
import { foo } from "./utils";

2. Never import a directory with a bare path; always spell out index.ts.

// ✅ Correct
import { Method } from "../http-api/index.ts";

// ❌ Wrong — directory import, breaks Node ESM
import { Method } from "../http-api";

These two rules apply to all files under src/**/*.ts. Test files (spec/**) are exempt. 1

Enforcement#

ESLint#

The n/file-extension-in-import rule (from eslint-plugin-n) is set to "error" with tryExtensions: [".ts"] for all src/**/*.ts files 2. This catches missing extensions at lint time.

Run linting with:

yarn lint:js

TypeScript#

tsconfig.json sets "allowImportingTsExtensions": true, which lets TypeScript accept the .ts suffix without treating it as an error during type-checking.

Why This Matters#

When Babel compiles src/ to lib/, it replaces .ts extensions with .js. If a source file imports ../http-api (no extension), Babel emits the same bare directory path into lib/. Node ESM then throws ERR_UNSUPPORTED_DIR_IMPORT at runtime.

This exact failure occurred in PR #5390 ("Properly support Matrix v1.18 OAuth2 APIs"), which introduced src/oauth/authorize.ts and src/oauth/index.ts with bare ../http-api imports. The bug broke import { createClient } from "matrix-js-sdk" in any Node ESM project on versions 42.0.0 and 42.1.0-rc.0, and was fixed in PR #5460 by changing both lines to ../http-api/index.ts — matching the other 13 http-api imports already in src/. 3

Reference Examples#

Correct imports from existing source files:

• src/oidc/tokenRefresher.ts line 19: import { ... } from "../http-api/index.ts";
• src/oidc/discovery.ts lines 19–21: all imports carry explicit .ts extensions
• src/oidc/index.ts lines 20–25: re-exports using ./authorize.ts, ./discovery.ts, etc.

Quick Reference#