{"id":21263,"library":"esbuild-plugin-path-alias","title":"esbuild-plugin-path-alias","description":"A esbuild plugin to support path aliases similar to webpack's resolve.alias. Current version 1.0.7, limited release history. It allows developers to define custom path mappings (e.g., '@' -> './app/component') so that import paths in source code can be shortened. The plugin requires esbuild as a peer dependency and expects absolute paths in alias definitions. Compared to alternatives like `esbuild-alias`, this plugin is minimal and focused, but lacks advanced features like tsconfig path resolution. It uses the `onResolve` hook and Node.js path module for resolution, and works with both ESM and CJS builds.","status":"active","version":"1.0.7","language":"javascript","source_language":"en","source_url":"https://github.com/indooorsman/esbuild-plugin-path-alias","tags":["javascript","alias","path","esbuild","plugin","webpack","tsconfig"],"install":[{"cmd":"npm install esbuild-plugin-path-alias","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-path-alias","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-path-alias","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required to function as a plugin","package":"esbuild","optional":false}],"imports":[{"note":"Default export; CJS require works in Node but TypeScript may need esModuleInterop.","wrong":"const esbuildPluginPathAlias = require('esbuild-plugin-path-alias')","symbol":"esbuildPluginPathAlias","correct":"import esbuildPluginPathAlias from 'esbuild-plugin-path-alias'"},{"note":"There is no named export; only default export. Using destructuring yields undefined.","wrong":"const { aliasPlugin } = require('esbuild-plugin-path-alias')","symbol":"default","correct":"import aliasPlugin from 'esbuild-plugin-path-alias'"},{"note":"Namespace import works only for default export.","wrong":"import { alias } from 'esbuild-plugin-path-alias'","symbol":"esbuildPluginPathAlias","correct":"import * as alias from 'esbuild-plugin-path-alias'\nalias.default({ '@': __dirname + '/src' })"}],"quickstart":{"code":"import esbuild from 'esbuild';\nimport aliasPlugin from 'esbuild-plugin-path-alias';\nimport path from 'path';\n\nawait esbuild.build({\n  entryPoints: [path.resolve(__dirname, 'src/index.js')],\n  bundle: true,\n  outdir: 'dist',\n  plugins: [\n    aliasPlugin({\n      '@': path.resolve(__dirname, 'src/components'),\n      '#': path.resolve(__dirname, 'src/utils'),\n    }),\n  ],\n});\n// In src/index.js: import MyComponent from '@/MyComponent'","lang":"typescript","description":"Shows how to set up esbuild-plugin-path-alias with two aliases, then import using the alias."},"warnings":[{"fix":"Use path.resolve() to convert relative paths to absolute.","message":"Alias values must be absolute paths; relative paths will not be resolved correctly.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Consider using esbuild-plugin-tsconfig-paths if you need tsconfig-based aliases.","message":"The plugin does not respect tsconfig 'paths' auto-resolution; you must manually define each alias.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure your esbuild setup supports CJS plugins, or use an alternative that provides ESM exports.","message":"The package is rarely updated; the README warns that it uses `require()` internally which may affect ESM builds.","severity":"deprecated","affected_versions":"<=1.0.7"},{"fix":"Verify alias definitions and import statements match exactly, including path separators (use forward slashes).","message":"Import paths with aliases must match exactly; trailing slashes or case sensitivity may cause resolution to fail.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Use path.resolve() to make the alias value absolute, e.g., path.resolve(__dirname, 'src/components').","cause":"Alias value provided as relative path (e.g., './src/components').","error":"Error: esbuild-plugin-path-alias: alias path must be absolute."},{"fix":"Use import aliasPlugin from 'esbuild-plugin-path-alias' instead of destructuring.","cause":"Attempted to import named export { aliasPlugin } instead of default export.","error":"TypeError: aliasPlugin is not a function"},{"fix":"Define alias for '@components' or ensure the import path matches exactly: import from '@/Header'.","cause":"Alias '@' is defined but the import path uses '@components' with an extra prefix.","error":"Cannot find module '@components/Header'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}