unplugin-svelte-components

On-demand components auto importing for Svelte.

Sveltekit Demo Svelte Vite Demo

Features

• ⚡️ Supports Vite, Webpack, Rollup, esbuild and more, powered by unplugin.
• 🏝 Tree-shakable, only registers the components you use.
• 🪐 Folder names as namespaces.
• 🦾 Full TypeScript support.
• 😃 Works perfectly with unplugin-auto-import.

Installation

pnpm add -D unplugin-svelte-components

// vite.config.ts
import Components from 'unplugin-svelte-components/vite'

export default defineConfig({
  plugins: [
    Components({ /* options */ }),
  ],
})

// rollup.config.js
import Components from 'unplugin-svelte-components/rollup'

export default {
  plugins: [
    Components({ /* options */ }),
  ],
}

// webpack.config.js
module.exports = {
  /* ... */
  plugins: [
    require('unplugin-svelte-components/webpack')({ /* options */ }),
  ],
}

// esbuild.config.js
import { build } from 'esbuild'

build({
  /* ... */
  plugins: [
    require('unplugin-svelte-components/esbuild')({
      /* options */
    }),
  ],
})

// vite.config.ts
import Components from 'unplugin-svelte-components/vite'

export default defineConfig({
  plugins: [
    Components({ /* options */ }), // before sveltekit plugin
    sveltekit(),
  ],
})

Usage

Use components as you would usually do, it will import components on demand, and there is no import required anymore!

It will automatically turn this

<HelloWorld msg="Hello Svelte" />

into this

<HelloWorld msg="Hello Svelte" />

<script>
import HelloWorld from './src/components/HelloWorld.svelte'
</script>

TypeScript

To get TypeScript support for auto-imported components, you can change the config as following to get the support.

Components({
  dts: true, // enabled by default if `typescript` is installed
})

Once the setup is done, a components.d.ts will be generated and updates automatically with the type definitions. Feel free to commit it into git or not as you want.

Make sure you also add components.d.ts to your tsconfig.json under includes.

Registered third party components

It's cool to have your own components have been import it, but sometime you want to import third party components.

Thus unplugin-svelte-components provided a way to import these components.

Components({
  dts: true,
  external: [
    {
      from: "agnostic-svelte", // import from third party
      names: [ // import these components
        "Alert",
        "Button as AButton", // import as `AButton`
      ],
      defaultImport: false, // telling `unplugin-svelte-components` to import any component as non-default export
    },
  ],
})

So the Alert and AButton will be available to use.

Disabling

In some cases, you may want to disable the auto-import in your page, unplugin-svelte-components provides a way to do that by just adding <!-- unplugin-svelte-components disabled --> in your .svelte file

<!-- unplugin-svelte-components disabled -->
<HelloWorld msg="Hello Svelte" />

Configuration

The following show the default values of the configuration

Components({
  // relative paths to the directory to search for components.
  dirs: ['src/components'],

  // valid file extensions for components.
  extensions: ['svelte'],

// search for subdirectories
  deep: true,

  // generate `components.d.ts` global declarations,
  // also accepts a path for custom filename
  // default: `true` if package typescript is installed
  dts: false,

  // Allow subdirectories as namespace prefix for components.
  directoryAsNamespace: false,
  // Subdirectory paths for ignoring namespace prefixes
  // works when `directoryAsNamespace: true`
  globalNamespaces: [],

  // Transform path before resolving
  importPathTransform: v => v,

  // Allow for components to override other components with the same name
  allowOverrides: false,

  // Accept a svelte pre-processor (e.g. svelte-preprocess)
  preprocess:  null,

  // filters for transforming targets
  include: [/\.svelte$/, /\.svelte\?svelte/],
  exclude: [/[\\/]node_modules[\\/]/, /[\\/]\.git[\\/]/, /[\\/]\.svelte-kit[\\/]/,],

  // Generate corresponding .eslintrc-components.json file.
  // eslint globals Docs - https://eslint.org/docs/user-guide/configuring/language-options#specifying-globals
  eslintrc:{
    enabled: true, // Default `true`
    filepath: './.eslintrc-components.json', // Default `./.eslintrc-components.json`
    globalsPropValue: true, // Default `true`, (true | false | 'readonly' | 'readable' | 'writable' | 'writeable')
  }

})

Thanks

Thanks to Anthony Fu, this project is heavily inspired by unplugin-vue-components.

License

MIT License © 2022-PRESENT Mohamed Nesredin