Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

ts-add-js-extension

GervinFung135kMIT1.6.6TypeScript support: included

Add .js extension to each relative ESM import and export statement in JavaScript file

esm, tsc, mjs, js, typescript, javascript, js extension, esnext

readme

ts-add-js-extension

Originally, I created this solution for personal use due to my preference of not including the .js extension in TypeScript import/export statements when compiling my TypeScript project to ES Module. This decision was motivated by the belief that it is unnecessary to import/export a JavaScript file that does not exist in the source code folder. Importing or exporting a file that does not exist would be illogical. In essence, a source code should not reference its own build artifacts or output file

Additionally, another option would be to compile the TypeScript project to CommonJS Module. However, I prefer not to take that approach. Instead, this package is designed to cater to TypeScript or JavaScript projects that use ES Module (ESM) format and do not rely on a bundler like esbuild or swc.

Feature

Initially designed for TypeScript projects exclusively, this solution also caters to those who prefer a more convenient approach when working with JavaScript. By automatically appending the .js extension to each relative import and export statement in ES Module JavaScript, you can save yourself the effort of doing it manually. This feature is particularly beneficial for TypeScript projects that target ES Module.

Als, this decision was motivated by the belief that it is unnecessary to import/export a JavaScript file that does not exist in the source code folder. Importing or exporting a file that does not exist would be illogical. In essence, a source code should not reference its own build artifacts or output file

It is worth noting that this package intelligently handles import/export statements and adds /index.js where necessary, allowing you to omit the explicit inclusion of index in the statement.

Additionally, it can determine whether a file with the mjs or js extension is being imported or exported

Usage

The compiled folder for TypeScript or JavaScript can be named according to your preference. In this case, I will use the name "dist" as an example.

Note: For command line arguments, refer here

Declarations

Command line:

{
    "scripts": {
        "<command name can be anything>": "ts-add-js-extension --dir=dist"
    }
}

API:

tsAddJsExtension({
    dir: 'dist',
});

Execution Process

Assuming you have a file called main.ts in the "dist" directory, the file structure would look like this:

dist/
  └─ main.ts

And main.ts contains the following imports and exports, where all the files are TypeScript files:

import { add } from './math';
export { add, sub, mul, div } from './math/index';

import div from './math/div';
export * as div from './math/div';

import word from './word';

console.log(add(2, 1));

When ts-add-js-extension is executed, it will generate the following code for main.js:

import { add } from './math/index.js';
export { add, sub, mul, div } from './math/index.js';

import div from './math/div.js';
export * as div from './math/div.js';

import word from './word/index.mjs';

console.log(add(2, 1));

During the process, ts-add-js-extension will traverse the project and analyze the file extensions of JavaScript files being imported or exported. It will then determine whether to add the .js or .mjs file extension based on the file's original extension.

This ensures that all the JavaScript files in your project have the correct file extension, enhancing compatibility and ensuring proper import/export functionality.

Arguments

Argument Usage Required Status Default Value
dir Specifies the folder where JavaScript file extension needs to be added Yes Active None
include Specifies the folder of files that are imported or included in the dir folder, excluding the specified dir No Deprecated []
showchanges Determines whether to display progress feedback in the format of Num. (File Updated) - (SUCCEED or FAILED) No Deprecated (in favor of showprogress) True
showprogress Determines whether to display progress feedback in the format of Num. (File Updated) - (SUCCEED or FAILED) No Active True

Please note that the status column indicates whether an argument is active or deprecated, and the default value column specifies the default value if not provided

Contributions

I appreciate your active participation in the development process. If you come across any bugs, have feature requests, or need clarification on any aspect of the project, please don't hesitate to open an issue.

Additionally, your contributions to the project are highly valued. If you have ideas or improvements that you would like to implement, I invite you to suggest a pull request. Simply fork the repository, make the necessary code changes, add relevant tests to ensure quality, and push your changes.

Your feedback and contributions play an essential role in making the project better, and I am grateful for your involvement. Thank you for your support and participation in the development of the project.

changelog

1.6.6 (22 May 2025)

  • (Fix) deprecate showchanges and replace with showprogress argument in both CLI and API
  • (Fix) deprecate include argument in both CLI and API
  • (Fix) preserve typeArguments when updating TypeNode

1.6.5 (06 Nov 2024)

  • (Fix) handle dynamic import with static path

1.6.4 (31 Mar 2024)

  • (Fix) join data from createReadStream with array rather than assign to string

1.6.3 (31 Jan 2024)

  • (Fix) Handle .jsx and .mjs also

1.6.2 (31 Jan 2024)

  • (Fix) Remove faulty postinstall command

1.6.1 (31 Jan 2024)

  • (Fix) Read the proper code structure to know which part of import/export to update

1.6.0 (13 Oct 2023)

  • (Feat) Append .js extension to directory with type declaration/definitions only
  • (Refactor) Removed functionality to append .js to mjs files, since typescript compiler force us to append .mjs extensions

1.5.7 (27 Jul 2023)

  • (Fix) Append .js extension to mjs files

1.5.7 (26 Jul 2023)

  • (Fix) Remove accidentally-committed temp files

1.5.6 (15 Jul 2023)

  • (Fix) Move typescript from devDependencies to dependencies

1.5.5 (5 Jul 2023)

  • (Fix) Parse array of value with space

1.5.4 (23 June 2023)

  • (Fix) Properly parse token of and replace with =, so --dir build becomes --dir=build internally

1.5.3 (22 June 2023)

  • (Fix) Accept token of as same level as =, so --dir=build and --dir build is the same

1.5.2 (22 June 2023)

  • (Fix) To be able to use on Windows

1.5.1 (4 June 2023)

  • (Fix) Add relative paths to package.json exports

1.5.0 (21 May 2023)

  • (Feat) Remove @typescript-eslint/typescript-estree, just use tsc to produce AST and manipulate import/export

1.4.0 (20 May 2023)

  • (Feat) Remove 'readline' and use raw output for log Num. (File Updated) - (SUCCEED or FAILED)

1.3.4 (15 May 2023)

  • (Fix) Remove dts folder and create dts folders for cjs and mjs folder

1.3.3 (6 Mar 2023)

  • (Fix) Auto detect whether a file imported/exported is with .js or .mjs extension, so there is no need to specify what extension to be added

1.3.2 (27 Oct 2022)

  • (Chore) Remove useless log

1.3.1 (27 Oct 2022)

  • (Fix) Create Progress instance when there is at least one file to change

1.3.0 (27 Oct 2022)

  • (Feat) Remove console-table-printer and replace it with manual progress log

1.2.6 (27 Oct 2022)

  • (Fix) Optionally target mjs or js file, defaults to js file if parameters are not pass into

1.2.5 (25 Oct 2022)

  • (Chore) Remove unnecessary log

1.2.4 (18 Oct 2022)

  • (Feat) Provide API function parseConfig & tsAddJsExtension
  • (Fix) Relative import . can be detected

1.2.3 (10 Sept 2022)

  • (Fix) README JS code block render
  • (Fix) Remove / from file path that ends with / as it cannot be detected as a folder
  • (Chore) Improve README
  • (Chore) Remove parse-dont-validate as parsing can be done manually

1.2.2 (6 Sept 2022)

  • (Fix) README JS code block render
  • (Chore) Simplify some code

1.2.1 (31 July 2022)

  • (Chore) Remove tsbuild-config from build

1.2.0 (6 May 2022)

  • (Feat) Auto add /index.js for import/export statement as we can omit index at the end of import/export
  • (Feat) Show import/export that has changed, can optionally turn it off as it's on by default

1.1.0 (6 May 2022)

  • (Fix) Read all javascript files to make sure relative imported file is JavaScript file before adding .js extension
  • (Feat) Allow import from different root folder, for example, it is possible to add .js extension for imported JavaScript files from common into src folder

1.0.2 (20 Feb 2022)

  • (Fix) Merge PR https://github.com/P-YNPM/ts-add-js-extension/pull/2 to add ExportAllDeclaration to handle additional export JavaScript

1.0.1 (11 Feb 2022)

  • (Feat) Made write file asynchronous to speed up writing

1.0.0 (13 Jan 2022)

  • (Fix!) Removed minification, perform only single function -> Add .js extension to each relative import/export statement

0.0.5 (4 Dec 2021)

  • (Chore) Change file in bin folder to JavaScript file and changed to import, not require

0.0.4 (4 Dec 2021)

  • (Chore) Updated parse-dont-validate package version in package.json

0.0.3 (4 Dec 2021)

  • (Feat) Added main entry point

0.0.2 (4 Dec 2021)

  • (Feat) Added minification and remove comment option based on AST

0.0.1 (29 Nov 2021)

  • (Chore) Added Git URL

0.0.0 (29 Nov 2021)

  • (Feat) Initial public release