esbuild-svelte-paths

0.1.4 verified Fri May 01 auth: no javascript

ESBuild plugin that resolves shortcuted paths for Svelte components, allowing imports without '.svelte' extension and folder/file name matching. Current stable version is 0.1.4, released in May 2022. It respects path aliases from tsconfig/jsconfig. Differentiators: specifically for esbuild (not webpack/vite), requires capital-letter last path segment to trigger resolution, and supports custom extensions for other frameworks like Malina.

Common errors

error Plugin must be placed before other plugins in esbuild ↓

cause Plugin order is not correct: sveltePaths() is not first or missing.

fix

Move sveltePaths() before any Svelte compiler plugin in the plugins array.

error Cannot find module './component' (unexpected) ↓

cause Import path does not start with capital letter, so shortcut is not applied and esbuild tries to resolve the file without .svelte extension.

fix

Ensure the last segment of the import path starts with a capital letter, e.g., './Component'.

error The plugin does not work with bundled esbuild ↓

cause Esbuild is used programmatically with bundle option but plugin is not installed or configured.

fix

Install esbuild-svelte-paths and add it to the plugins array before the Svelte plugin.

Warnings

gotcha Plugin must be placed before any Svelte compiler plugin in the plugins array, otherwise resolution may fail. ↓

fix Ensure the order: sveltePaths() first, then sveltePlugin().

gotcha Shortcut only applies when the last path segment starts with a capital letter. Lowercase imports are ignored and treated normally. ↓

fix Use capital letter for the component name in the import path, e.g., import Button from './Button'.

gotcha IDE features like ctrl+click and autocomplete are lost for shortcuted imports; the import path is virtual and not resolved by the IDE. ↓

fix Use explicit full paths if you need IDE navigation support.

Install

npm install esbuild-svelte-paths

yarn add esbuild-svelte-paths

pnpm add esbuild-svelte-paths

Imports

sveltePaths

wrong

import sveltePaths from 'esbuild-svelte-paths'

correct

import { sveltePaths } from 'esbuild-svelte-paths'

Named export, not default.

sveltePaths (require)

wrong

const sveltePaths = require('esbuild-svelte-paths')

correct

const { sveltePaths } = require('esbuild-svelte-paths')

CommonJS require must destructure the named export.

Plugin (as ESBuild plugin object)

wrong

import sveltePaths from 'esbuild-svelte-paths'; plugins: [sveltePaths]

correct

const { sveltePaths } = require('esbuild-svelte-paths'); plugins: [sveltePaths()]

sveltePaths is a function that must be called to create the plugin instance.

Quickstart

Shows how to install and configure the plugin in an esbuild script, placing it before the Svelte compiler plugin.

const { sveltePaths } = require('esbuild-svelte-paths');
const sveltePlugin = require('esbuild-svelte');

require('esbuild').build({
  entryPoints: ['src/main.js'],
  bundle: true,
  outfile: 'public/bundle.js',
  plugins: [
    sveltePaths(),
    sveltePlugin()
  ]
}).catch(() => process.exit(1));