A zero-dependency library providing Svelte preprocessors and build plugins for the Carbon Design System
npm install carbon-preprocess-svelte[![NPM][npm]][npm-url]
!GitHub
!npm downloads to date
> A zero-dependency library providing Svelte preprocessors and build plugins for the Carbon Design System.
Install carbon-preprocess-svelte as a development dependency.
``shnpm
npm i -D carbon-preprocess-svelte
Usage
- optimizeImports: Svelte preprocessor that rewrites Carbon Svelte imports to their source path in the
block, making development compile times dramatically faster.
- optimizeCss: Vite/Rollup plugin that removes unused Carbon styles, resulting in smaller CSS bundles.
- OptimizeCssPlugin: The corresponding optimizeCss plugin for Webpack that removes unused Carbon styles.$3
optimizeImports is a Svelte preprocessor that rewrites barrel imports from Carbon components/icons/pictograms packages to their source Svelte code paths. This can significantly speed up development and build compile times while preserving typeahead and autocompletion offered by integrated development environments (IDE) like VS Code.The preprocessor optimizes imports from the following packages:
- carbon-components-svelte
- carbon-icons-svelte
- carbon-pictograms-svelte
`diff
- import { Button } from "carbon-components-svelte";
+ import Button from "carbon-components-svelte/src/Button/Button.svelte";- import { Add } from "carbon-icons-svelte";
+ import Add from "carbon-icons-svelte/lib/Add.svelte";
- import { Airplane } from "carbon-pictograms-svelte";
+ import Airplane from "carbon-pictograms-svelte/lib/Airplane.svelte";
`> [!NOTE]
> When this preprocessor was first created, there was no workaround to optimize slow cold start times with Vite in development.
> Today, @sveltejs/vite-plugin-svelte enables
by default.
> However, this preprocessor is still useful for non-Vite bundlers, like Rollup and Webpack. Also, it can further improve cold start development times even with prebundleSvelteLibraries: true.#### SvelteKit
See examples/sveltekit.
`js
// svelte.config.js
import adapter from "@sveltejs/adapter-static";
import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
import { optimizeImports } from "carbon-preprocess-svelte";/* @type {import('@sveltejs/kit').Config} /
const config = {
preprocess: [
// Preprocessors are run in sequence.
// If using TypeScript, the code must be transpiled first.
vitePreprocess(),
optimizeImports(),
],
kit: {
adapter: adapter(),
},
};
export default config;
`#### Vite
See examples/vite.
js
// vite.config.js
import { svelte } from "@sveltejs/vite-plugin-svelte";
import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
import { optimizeImports } from "carbon-preprocess-svelte";/* @type {import('vite').UserConfig} /
export default {
plugins: [
svelte({
preprocess: [
// Preprocessors are run in sequence.
// If using TypeScript, the code must be transpiled first.
vitePreprocess(),
optimizeImports(),
],
}),
],
};
`#### Rollup
This code is abridged; see examples/rollup for a full set-up.
js
// rollup.config.js
import svelte from "rollup-plugin-svelte";
import { optimizeImports } from "carbon-preprocess-svelte";export default {
plugins: [
svelte({
preprocess: [optimizeImports()],
}),
],
};
`#### Webpack
This code is abridged; see examples/webpack for a full set-up.
js
// webpack.config.mjs
import { optimizeImports } from "carbon-preprocess-svelte";export default {
module: {
rules: [
{
test: /\.svelte$/,
use: {
loader: "svelte-loader",
options: {
hotReload: !PROD,
preprocess: [optimizeImports()],
compilerOptions: { dev: !PROD },
},
},
},
],
},
};
`$3
is a Vite plugin that removes unused Carbon styles at build time. The plugin is compatible with Rollup (Vite extends the Rollup plugin API).`diff
$ vite buildOptimized index-CU4gbKFa.css
- Before: 606.26 kB
+ After: 53.22 kB (-91.22%)
dist/index.html 0.34 kB │ gzip: 0.24 kB
dist/assets/index-CU4gbKFa.css 53.22 kB │ gzip: 6.91 kB
dist/assets/index-Ceijs3eO.js 53.65 kB │ gzip: 15.88 kB
`> [!NOTE]
> This is a plugin and not a Svelte preprocessor. It should be added to the list of
. For Vite set-ups, this plugin _is not run_ during development and is only executed when building the app (i.e., vite build). For Rollup and Webpack, you should conditionally apply the plugin to only execute when building for production.#### SvelteKit
See examples/sveltekit.
`js
// vite.config.js
import { sveltekit } from "@sveltejs/kit/vite";
import { optimizeCss } from "carbon-preprocess-svelte";
import { defineConfig } from "vite";export default defineConfig({
plugins: [sveltekit(), optimizeCss()],
});
`#### Vite
See examples/vite.
js
// vite.config.js
import { svelte } from "@sveltejs/vite-plugin-svelte";
import { optimizeCss } from "carbon-preprocess-svelte";/* @type {import('vite').UserConfig} /
export default {
plugins: [svelte(), optimizeCss()],
};
`#### Rollup
This code is abridged; see examples/rollup for a full set-up.
js
// rollup.config.js
import svelte from "rollup-plugin-svelte";
import { optimizeCss } from "carbon-preprocess-svelte";const production = !process.env.ROLLUP_WATCH;
export default {
plugins: [
svelte({
preprocess: [optimizeImports()],
}),
// Only apply the plugin when building for production.
production && optimizeCss(),
],
};
`####
API`ts
optimizeCss({
/**
* By default, the plugin will print the size
* difference between the original and optimized CSS.
*
* Set to false to disable verbose logging.
* @default true
*/
verbose: false, /**
* By default, pre-compiled Carbon StyleSheets ship
@font-face rules
* for all available IBM Plex fonts, many of which are not actually
* used in Carbon Svelte components.
*
* The default behavior is to preserve the following IBM Plex fonts:
* - IBM Plex Sans (300/400/600-weight and normal-font-style rules)
* - IBM Plex Mono (400-weight and normal-font-style rules)
*
* Set to true to disable this behavior and
retain all* IBM Plex @font-face rules.
* @default false
*/
preserveAllIBMFonts: true,
});
`$3
For Webpack users,
is a drop-in replacement for optimizeCss. The plugin API is identical to that of optimizeCss. Similarly, the plugin only runs in production mode.This code is abridged; see examples/webpack or examples/webpack@svelte-5 for a full set-up.
`js
// webpack.config.mjs
import { OptimizeCssPlugin } from "carbon-preprocess-svelte";export default {
plugins: [new OptimizeCssPlugin()],
};
``Refer to examples for common set-ups.
Refer to the contributing guidelines.
[npm]: https://img.shields.io/npm/v/carbon-preprocess-svelte.svg?color=262626&style=for-the-badge
[npm-url]: https://npmjs.com/package/carbon-preprocess-svelte