All Articles

Relative import paths need explicit file extensions in EcmaScript imports

Matt Pocock
Matt PocockMatt is a well-regarded TypeScript expert known for his ability to demystify complex TypeScript concepts.

The Error

Relative import paths need explicit file extensions in EcmaScript imports when '--moduleResolution' is 'node16' or 'nodenext'.

// Relative import paths need explicit file extensions in
// EcmaScript imports when '--moduleResolution' is 'node16'
// or 'nodenext'.

import { example } from "./foo";

The Solution That Doesn't Work

Adding a .ts extension to the import path doesn't work, and results in the following error:

An import path can only end with a '.ts' extension when 'allowImportingTsExtensions' is enabled.

// An import path can only end with a '.ts' extension when
// 'allowImportingTsExtensions' is enabled.

import { example } from "./foo.ts";

The Solution

Add the .js extension to the import path.

import { example } from "./foo.js";

Why Do We Need to Use JS File Extensions?

This error happens because you've specified moduleResolution: NodeNext. This tells TypeScript that you want your imports and exports to conform strictly to the Node spec.

The Node spec requires that you use .js file extensions for all imports and exports. This was decided so that a relative import path like ./foo.js would work both in Node and the browser.

This also simplifies Node's module resolution strategy - Node doesn't have to do any guesswork to figure out what file to import. Thanks to Gil Tayer for clarifying this for me.

What if I don't want to use JS file extensions?
  • Make sure you're using an external compiler, like esbuild, to compile your TypeScript code.
  • Change your tsconfig.json to use moduleResolution: Bundler instead of moduleResolution: NodeNext.
Matt's signature

Relative import paths need explicit file extensions in EcmaScript imports

share on blueskyshare on twittershare on linkedinshare on reddit

Cursor Rules for Better AI Development

Finding existing community .cursor/rules for TypeScript lacking, I'm sharing my own set to hopefully kickstart a discussion on what makes effective AI coding guidance. These rules focus purely on TypeScript language features, documentation, structure (like Result types), teaching the AI specific nuances (like noUncheckedIndexedAccess), and practical habits, rather than specific frameworks. I also distinguish between shareable, project-specific Workspace Rules (versioned in Git) and personalized Global Rules (living in your IDE) to tailor the AI to your individual style and workflow. You can download my current ruleset using the link in the original post.

Matt Pocock
Matt Pocock

Should You Declare Return Types?

Here's a quick .cursor/rules addition you can make for handling return types in TypeScript.

# Return Types

When declaring functions on the top-level of a module,
declare their return types. This will help future AI
assistants understand the function's purpose.

```ts
const myFunc = (): string => {
  return "hello";
};
```

One exception to this is components which return JSX.
No need to
Matt Pocock
Matt Pocock

TypeScript Announces Go Rewrite, Achieves 10x Speedup

TypeScript announced a full rewrite of TypeScript in Go. In testing, this rewrite has achieved a 10x speedup in some repositories - and up to 15x in others.

Matt Pocock
Matt Pocock

TypeScript 5.8 Ships --erasableSyntaxOnly To Disable Enums

TypeScript 5.8's new erasableSyntaxOnly flag enforces pure type annotations by disabling enums, namespaces, and parameter properties.

Matt Pocock
Matt Pocock