{"id":21057019,"url":"https://github.com/aymericzip/esbuild-fix-imports-plugin","last_synced_at":"2025-10-13T08:33:20.397Z","repository":{"id":259374469,"uuid":"877770213","full_name":"aymericzip/esbuild-fix-imports-plugin","owner":"aymericzip","description":"An ESBuild plugin that fixes import paths. It ensures correct file extensions, resolves path aliases, and fixes directory imports in your build output when using 'tsup' with 'bundle: false'.","archived":false,"fork":false,"pushed_at":"2025-08-23T19:18:16.000Z","size":74,"stargazers_count":22,"open_issues_count":4,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-28T06:56:46.192Z","etag":null,"topics":["alias","bundle","esbuild","extention","fix","import","path","plugin","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aymericzip.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-10-24T08:02:51.000Z","updated_at":"2025-08-29T15:15:03.000Z","dependencies_parsed_at":"2024-10-24T23:36:04.315Z","dependency_job_id":"8ff97bc5-1825-4193-a6a2-42680d1feb4e","html_url":"https://github.com/aymericzip/esbuild-fix-imports-plugin","commit_stats":null,"previous_names":["aymericzip/esbuild-fix-imports-plugin"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aymericzip/esbuild-fix-imports-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aymericzip%2Fesbuild-fix-imports-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aymericzip%2Fesbuild-fix-imports-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aymericzip%2Fesbuild-fix-imports-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aymericzip%2Fesbuild-fix-imports-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aymericzip","download_url":"https://codeload.github.com/aymericzip/esbuild-fix-imports-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aymericzip%2Fesbuild-fix-imports-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279014315,"owners_count":26085492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alias","bundle","esbuild","extention","fix","import","path","plugin","typescript"],"created_at":"2024-11-19T16:55:52.806Z","updated_at":"2025-10-13T08:33:20.377Z","avatar_url":"https://github.com/aymericzip.png","language":"TypeScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# esbuild-fix-imports-plugin\n\nAn ESBuild plugin that fixes import paths by applying the following plugins:\n\n- **`fixAliasPlugin`**: Resolves path aliases defined in `tsconfig.json`.\n- **`fixFolderImportsPlugin`**: Replaces imports pointing to directories with explicit paths to the `index` file.\n- **`fixExtensionsPlugin`**: Appends the correct file extensions to relative import paths.\n\nThis plugin ensures correct file extensions, resolves path aliases, and fixes directory imports in your build output when using [`tsup`](https://github.com/egoist/tsup) with `bundle: false`.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Plugins Overview](#plugins-overview)\n  - [fixAliasPlugin](#fixaliasplugin)\n  - [fixFolderImportsPlugin](#fixfolderimportsplugin)\n  - [fixExtensionsPlugin](#fixextensionsplugin)\n- [Example Configuration](#example-configuration)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\nInstall the package via npm:\n\n```bash\nnpm install esbuild-fix-imports-plugin\n```\n\nOr using pnpm:\n\n```bash\npnpm add esbuild-fix-imports-plugin\n```\n\nOr using Yarn:\n\n```bash\nyarn add esbuild-fix-imports-plugin\n```\n\n## Usage\n\nIn your `tsup.config.ts` or ESBuild configuration file, import the plugin and add it to your `esbuildPlugins` array:\n\n```typescript\n// tsup.config.ts\n\nimport { defineConfig } from \"tsup\";\nimport { fixImportsPlugin } from \"esbuild-fix-imports-plugin\";\n\nexport default defineConfig({\n  // ... your other configurations\n  esbuildPlugins: [fixImportsPlugin()],\n});\n```\n\nThis will apply all three plugins (`fixAliasPlugin`, `fixFolderImportsPlugin`, and `fixExtensionsPlugin`) during the build process.\n\nIf you prefer to use the plugins individually, you can import them separately:\n\n```typescript\nimport {\n  fixAliasPlugin,\n  fixFolderImportsPlugin,\n  fixExtensionsPlugin,\n} from \"esbuild-fix-imports-plugin\";\n\nexport default defineConfig({\n  // ... your other configurations\n  esbuildPlugins: [\n    fixAliasPlugin(),\n    fixFolderImportsPlugin(),\n    fixExtensionsPlugin(),\n  ],\n});\n```\n\n## Plugins Overview\n\n### fixAliasPlugin\n\n**Description**: Resolves path aliases defined in your `tsconfig.json` file and replaces them with relative paths in the output files.\n\n**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.\n\n**Requirements**:\n\n- Ensure your `tsconfig.json` includes the `paths` configuration.\n- Provide the path to `tsconfig.json` in your `tsup` or ESBuild configuration.\n\n**Example `tsconfig.json`**:\n\n```json5\n{\n  compilerOptions: {\n    baseUrl: \".\",\n    paths: {\n      \"@utils/*\": [\"src/utils/*\"],\n      \"@components/*\": [\"src/components/*\"],\n    },\n    // ... other options\n  },\n}\n```\n\n### fixFolderImportsPlugin\n\n**Description**: Replaces import paths pointing to directories with explicit paths to the `index` file.\n\n**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';`.\n\n### fixExtensionsPlugin\n\n**Description**: Appends the correct file extensions (`.js`, `.mjs`, `.cjs`) to relative import paths in the output files.\n\n**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.\n\n## Example Configuration\n\nHere's a full example of how to configure `tsup` with this plugin:\n\n```typescript\n// tsup.config.ts\n\nimport { defineConfig } from \"tsup\";\nimport { fixImportsPlugin } from \"esbuild-fix-imports-plugin\";\n\nexport default defineConfig([\n  {\n    entry: [\"src/**/*\"],\n    target: \"esnext\",\n    dts: true,\n    external: [\"fs\", \"path\"],\n    clean: true,\n    sourcemap: true,\n    bundle: false, // Important: set to false\n    tsconfig: \"./tsconfig.json\",\n    format: [\"cjs\"],\n    outDir: \"dist/cjs\",\n    outExtension: () =\u003e ({ js: \".cjs\" }),\n    esbuildPlugins: [fixImportsPlugin()],\n  },\n  {\n    entry: [\"src/**/*\"],\n    target: \"esnext\",\n    dts: true,\n    external: [\"fs\", \"path\"],\n    clean: true,\n    sourcemap: true,\n    bundle: false, // Important: set to false\n    tsconfig: \"./tsconfig.json\",\n    format: [\"esm\"],\n    outDir: \"dist/esm\",\n    outExtension: () =\u003e ({ js: \".mjs\" }),\n    esbuildPlugins: [fixImportsPlugin()],\n  },\n]);\n```\n\n**Explanation**:\n\n- **`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.\n- **`esbuildPlugins: [fixImportsPlugin()]`**: Applies the combined plugin to fix import paths during the build process.\n\n## Contributing\n\nContributions are welcome! If you find a bug or have a feature request, please open an issue on [GitHub](https://github.com/aymericzip/esbuild-fix-imports-plugin/issues).\n\n### Steps to Contribute\n\n1. **Fork the Repository**: Click the \"Fork\" button at the top-right corner of the repository page.\n\n2. **Clone Your Fork**:\n\n   ```bash\n   git clone https://github.com/aymericzip/esbuild-fix-imports-plugin.git\n   ```\n\n3. **Create a New Branch**:\n\n   ```bash\n   git checkout -b feature/my-new-feature\n   ```\n\n4. **Install Dependencies**:\n\n   ```bash\n   npm install\n   ```\n\n5. **Make Your Changes**: Implement your feature or fix.\n\n6. **Build the Project**:\n\n   ```bash\n   npm run build\n   ```\n\n7. **Test Your Changes**:\n\n   ```bash\n   npm run test\n   ```\n\n8. **Commit Your Changes**:\n\n   ```bash\n   git commit -am 'Add my new feature'\n   ```\n\n9. **Push to Your Fork**:\n\n   ```bash\n   git push origin feature/my-new-feature\n   ```\n\n10. **Open a Pull Request**: Go to your fork on GitHub and open a pull request to the main repository.\n\n## License\n\nThis project is licensed under the ISC License.\n\n## Author\n\n**Aymeric PINEAU**\n\n- **GitHub**: [aymericzip](https://github.com/aymericzip)\n\n---\n\n**Note**: Remember to adjust the plugin configurations according to your project's specific needs and ensure that all paths and options are correctly set.\n\n---\n\n## Acknowledgements\n\nSpecial thanks to the contributors and the open-source community for their continuous support.\n\n---\n\n## Frequently Asked Questions (FAQ)\n\n### Why do I need this plugin?\n\nWhen 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.\n\n### Can I use this plugin with plain ESBuild?\n\nYes, you can use the plugins directly with ESBuild by adding them to the `plugins` array in your ESBuild configuration.\n\n```typescript\nimport esbuild from \"esbuild\";\nimport { fixImportsPlugin } from \"esbuild-fix-imports-plugin\";\n\nesbuild.build({\n  entryPoints: [\"src/index.ts\"],\n  bundle: false,\n  plugins: [fixImportsPlugin()],\n  // ... other configurations\n});\n```\n\n### Do I need all three plugins?\n\nNot necessarily. If you only need to fix specific issues, you can import and apply the individual plugins:\n\n```typescript\nimport {\n  fixAliasPlugin,\n  fixExtensionsPlugin,\n} from \"esbuild-fix-imports-plugin\";\n\nexport default defineConfig({\n  // ... your other configurations\n  esbuildPlugins: [fixAliasPlugin(), fixExtensionsPlugin()],\n});\n```\n\n### What environments benefit from this plugin?\n\nEnvironments 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.\n\n---\n\nFeel free to open an issue if you have more questions or need assistance.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faymericzip%2Fesbuild-fix-imports-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faymericzip%2Fesbuild-fix-imports-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faymericzip%2Fesbuild-fix-imports-plugin/lists"}