carbon-preprocess-svelte

Svelte preprocessors for the Carbon Design System

Installation

Install carbon-preprocess-svelte as a development dependency.

# Yarn
yarn add -D carbon-preprocess-svelte

# npm
npm i -D carbon-preprocess-svelte

# pnpm
pnpm i -D carbon-preprocess-svelte

Usage

• optimizeImports: Svelte preprocessor that rewrites Carbon Svelte imports to their source path in the script block, making development compile times dramatically faster.
• optimizeCss: Vite/Rollup plugin that removes unused Carbon styles, resulting in smaller CSS bundles.

optimizeImports

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 production 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

- 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. As of today, @sveltejs/vite-plugin-svelte enables prebundleSvelteLibraries, which pre-bundles Svelte libraries to improve cold start times for Vite-based set-ups. However, this preprocessor is still useful for non-Vite bundlers, like Rollup and Webpack.

SvelteKit

See examples/sveltekit.

// 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.

// 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.

// 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.

// webpack.config.js
const { optimizeImports } = require("carbon-preprocess-svelte");

module.exports = {
  module: {
    rules: [
      {
        test: /\.svelte$/,
        use: {
          loader: "svelte-loader",
          options: {
            hotReload: !PROD,
            preprocess: [optimizeImports()],
            compilerOptions: { dev: !PROD },
          },
        },
      },
    ],
  },
};

optimizeCss

optimizeCss is a Vite plugin that removes unused Carbon styles at build time. The plugin is compatible with Rollup (Vite extends the Rollup plugin API).

[email protected] or greater is required.

$ vite build

Optimized 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 vite.plugins. For Vite set-ups, this plugin is only run when building the app. For Rollup and Webpack, you should conditionally apply the plugin to only execute when building for production.

SvelteKit

See examples/sveltekit.

// 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.

// 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.

// 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(),
  ],
};

Webpack

Webpack users should use the OptimizeCssPlugin. The plugin API is identical to the Vite plugin.

This code is abridged; see examples/webpack for a full set-up.

// webpack.config.js
const { OptimizeCssPlugin } = require("carbon-preprocess-svelte");

const PROD = process.env.NODE_ENV === "production";

module.exports = {
  plugins: [
    // Only apply the plugin when building for production.
    PROD && new OptimizeCssPlugin(),
  ],
};

optimizeCss API

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: false,
});

Examples

Refer to examples for common set-ups.

Contributing

Refer to the contributing guidelines.

License

Apache 2.0