npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

esbuild-fix-imports-plugin

v1.0.6

Published

An ESBuild plugin that fixes import paths by applying fixAliasPlugin, fixFolderImportsPlugin, and fixExtensionsPlugin. It ensures correct file extensions, resolves path aliases, and fixes directory imports in your build output when using 'tsup' with 'bund

Downloads

1,475

Readme

esbuild-fix-imports-plugin

An ESBuild plugin that fixes import paths by applying the following plugins:

  • fixAliasPlugin: Resolves path aliases defined in tsconfig.json.
  • fixFolderImportsPlugin: Replaces imports pointing to directories with explicit paths to the index file.
  • fixExtensionsPlugin: Appends the correct file extensions to relative import paths.

This plugin ensures correct file extensions, resolves path aliases, and fixes directory imports in your build output when using tsup with bundle: false.

Table of Contents

Installation

Install the package via npm:

npm install esbuild-fix-imports-plugin

Or using pnpm:

pnpm add esbuild-fix-imports-plugin

Or using Yarn:

yarn add esbuild-fix-imports-plugin

Usage

In your tsup.config.ts or ESBuild configuration file, import the plugin and add it to your esbuildPlugins array:

// tsup.config.ts

import { defineConfig } from "tsup";
import { fixImportsPlugin } from "esbuild-fix-imports-plugin";

export default defineConfig({
  // ... your other configurations
  esbuildPlugins: [fixImportsPlugin()],
});

This will apply all three plugins (fixAliasPlugin, fixFolderImportsPlugin, and fixExtensionsPlugin) during the build process.

If you prefer to use the plugins individually, you can import them separately:

import {
  fixAliasPlugin,
  fixFolderImportsPlugin,
  fixExtensionsPlugin,
} from "esbuild-fix-imports-plugin";

export default defineConfig({
  // ... your other configurations
  esbuildPlugins: [
    fixAliasPlugin(),
    fixFolderImportsPlugin(),
    fixExtensionsPlugin(),
  ],
});

Plugins Overview

fixAliasPlugin

Description: Resolves path aliases defined in your tsconfig.json file and replaces them with relative paths in the output files.

Use Case: When using path aliases in TypeScript, the compiled JavaScript files may contain unresolved import paths. This plugin fixes that by converting aliases to relative paths.

Requirements:

  • Ensure your tsconfig.json includes the paths configuration.
  • Provide the path to tsconfig.json in your tsup or ESBuild configuration.

Example tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@utils/*": ["src/utils/*"],
      "@components/*": ["src/components/*"]
    }
    // ... other options
  }
}

fixFolderImportsPlugin

Description: Replaces import paths pointing to directories with explicit paths to the index file.

Use Case: Some module resolvers do not automatically resolve imports to index files within directories. This plugin ensures that imports like import { myFunction } from './utils'; are transformed to import { myFunction } from './utils/index';.

fixExtensionsPlugin

Description: Appends the correct file extensions (.js, .mjs, .cjs) to relative import paths in the output files.

Use Case: In environments that require explicit file extensions in import statements, this plugin ensures that all relative imports have the correct extensions, preventing runtime errors.

Example Configuration

Here's a full example of how to configure tsup with this plugin:

// tsup.config.ts

import { defineConfig } from "tsup";
import { fixImportsPlugin } from "esbuild-fix-imports-plugin";

export default defineConfig([
  {
    entry: ["src/**/*"],
    target: "esnext",
    dts: true,
    external: ["fs", "path"],
    clean: true,
    sourcemap: true,
    bundle: false, // Important: set to false
    tsconfig: "./tsconfig.json",
    format: ["cjs"],
    outDir: "dist/cjs",
    outExtension: () => ({ js: ".cjs" }),
    esbuildPlugins: [fixImportsPlugin()],
  },
  {
    entry: ["src/**/*"],
    target: "esnext",
    dts: true,
    external: ["fs", "path"],
    clean: true,
    sourcemap: true,
    bundle: false, // Important: set to false
    tsconfig: "./tsconfig.json",
    format: ["esm"],
    outDir: "dist/esm",
    outExtension: () => ({ js: ".mjs" }),
    esbuildPlugins: [fixImportsPlugin()],
  },
]);

Explanation:

  • bundle: false: Setting bundle to false tells tsup not to bundle the modules, which can lead to issues with import paths. This plugin helps resolve those issues.
  • esbuildPlugins: [fixImportsPlugin()]: Applies the combined plugin to fix import paths during the build process.

Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue on GitHub.

Steps to Contribute

  1. Fork the Repository: Click the "Fork" button at the top-right corner of the repository page.

  2. Clone Your Fork:

    git clone https://github.com/your-username/esbuild-fix-imports-plugin.git
  3. Create a New Branch:

    git checkout -b feature/my-new-feature
  4. Install Dependencies:

    npm install
  5. Make Your Changes: Implement your feature or fix.

  6. Build the Project:

    npm run build
  7. Test Your Changes: Ensure everything works as expected.

  8. Commit Your Changes:

    git commit -am 'Add my new feature'
  9. Push to Your Fork:

    git push origin feature/my-new-feature
  10. Open a Pull Request: Go to your fork on GitHub and open a pull request to the main repository.

License

This project is licensed under the ISC License.

Author

Aymeric PINEAU


Note: Remember to adjust the plugin configurations according to your project's specific needs and ensure that all paths and options are correctly set.


Acknowledgements

Special thanks to the contributors and the open-source community for their continuous support.


Frequently Asked Questions (FAQ)

Why do I need this plugin?

When using tsup with bundle: false, you might encounter issues with import paths in the output files, such as missing file extensions, unresolved path aliases, or imports pointing to directories without explicit index files. This plugin automates the process of fixing these issues during the build.

Can I use this plugin with plain ESBuild?

Yes, you can use the plugins directly with ESBuild by adding them to the plugins array in your ESBuild configuration.

import esbuild from "esbuild";
import { fixImportsPlugin } from "esbuild-fix-imports-plugin";

esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: false,
  plugins: [fixImportsPlugin()],
  // ... other configurations
});

Do I need all three plugins?

Not necessarily. If you only need to fix specific issues, you can import and apply the individual plugins:

import {
  fixAliasPlugin,
  fixExtensionsPlugin,
} from "esbuild-fix-imports-plugin";

export default defineConfig({
  // ... your other configurations
  esbuildPlugins: [fixAliasPlugin(), fixExtensionsPlugin()],
});

What environments benefit from this plugin?

Environments that require explicit file extensions in imports or do not automatically resolve directory imports to index files will benefit from this plugin. This includes some Node.js configurations and bundlers.


Feel free to open an issue if you have more questions or need assistance.