background by
@geographyofrobots
Snowpack 2.7 is here! Read the launch post →

Snowpack

THE PLUGIN GUIDE

Take me back to the main docs

Who is this page for?

Looking for help using Snowpack in your project? 👉 Check out our main docs.

Plugin Overview

A Snowpack Plugin is an object interface that lets you customize Snowpack’s behavior. Snowpack provides different hooks for your plugin to connect to. For example, you can add a plugin to handle Svelte files, optimize CSS, convert SVGs to React components, run TypeScript during development, and much more.

Snowpack’s plugin interface is inspired by Rollup. If you’ve ever written a Rollup plugin before, then hopefully these concepts and terms feel familiar.

Build Plugins

Snowpack uses an internal Build Pipeline to build files in your application for development and production. Every source file passes through the build pipeline, which means that Snowpack can build more than just JavaScript. Images, CSS, SVGs and more can all be built by Snowpack.

Snowpack runs each file through the build pipeline in two separate steps:

  1. Load: Snowpack finds the first plugin that claims to resolve the given file. It then calls that plugin’s load() method to load the file into your application. This is where compiled languages (TypeScript, Sass, JSX, etc.) are loaded and compiled to something that can run on the web (JS, CSS, etc).
  2. Transform: Once loaded, every file passes through the build pipeline again to run through matching transform() methods of all plugins that offer the method. Plugins can transform a file to modify or augment its contents before finishing the file build.

Dev Tooling Plugins

Snowpack plugins support a run() method which lets you run any CLI tool and connect its output into Snowpack. You can use this to run your favorite dev tools (linters, TypeScript, etc.) with Snowpack and automatically report their output back through the Snowpack developer console. If the command fails, you can optionally fail your production build.

Bundler Plugins

Snowpack builds you a runnable, unbundled website by default, but you can optimize this final build with your favorite bundler (webpack, Rollup, Parcel, etc.) through the plugin bundle() method. When a bundler plugin is used, Snowpack will run the bundler on your build automatically to optimize it.

Snowpack’s bundler plugin API is the one part of the API that is still marked as experimental and may change in a future release. See our official bundler plugins for an example of using the current interface:

How to Write a Plugin

Getting Started

To create a Snowpack plugin, you can start with the following file template:

// my-snowpack-plugin.js
module.exports = function (snowpackConfig, pluginOptions) {
  return {
    name: 'my-snowpack-plugin',
    // ...
  };
};
// snowpack.config.json
{
  "plugins": [["./my-snowpack-plugin.js", {"optionA": "foo", "optionB": "bar"}]]
}

A Snowpack plugin should be distributed as a function that can be called with plugin-specific options to return a plugin object. Snowpack will automatically call this function to load your plugin. That function accepts 2 parameters, in this order:

  1. the Snowpack configuration object (snowpackConfig)
  2. (optional) user-provided config options (pluginOptions)

Develop and Test

To develop and test a Snowpack plugin, the strategy is the same as with other npm packages:

  1. Create your new plugin project (either with npm init or yarn init) with, for example, npm name: my-snowpack-plugin and paste in it the above-mentioned code snipped
  2. Run npm link in your plugin’s project folder to expose the plugin globally (in regard to your development machine).
  3. Create a new, example Snowpack project in a different location for testing
  4. In your example Snowpack project, run npm install && npm link my-snowpack-plugin (use the name from your plugin’s package.json).
    • Be aware that npm install will remove your linked plugin, so on any install, you will need to redo the npm link my-snowpack-plugin.
    • (The alternative would be to use npm install --save-dev <folder_to_your_plugin_project>, which would create the "symlink-like" entry in your example Snowpack project’s package.json)
  5. In your example Snowpack project, add your plugin to the snowpack.config.json along with any plugin options you’d like to test: 
          
{
  "plugins": [
    ["my-snowpack-plugin", { "option-1": "testing", "another-option": false }]
  "
}

Transform a File

For our first example, we’ll look at transforming a file.

module.exports = function (snowpackConfig, pluginOptions) {
  return {
    name: 'my-commenter-plugin',
    async transform({fileExt, filePath, contents, isDev}) {
      if (fileExt === '.js') {
        return `/* I’m a comment! */ ${contents}`;
      }
    },
  };
};

The object returned by this function is a Snowpack Plugin. A plugin consists of a name property and some hooks into the Snowpack lifecycle to customizes your build pipeline or dev environment. In the example above we have:

This covers the basics of single-file transformations. In our next example, we’ll show how to compile a source file and change the file extension in the process.

Build From Source

When you build files from source, you also have the ability to transform the file type from source code to web code. In this example, we’ll use Babel to load several types of files as input and output JavaScript in the final build:

const babel = require('@babel/core');

module.exports = function (snowpackConfig, pluginOptions) {
  return {
    name: 'my-babel-plugin',
    resolve: {
      input: ['.js', '.jsx', '.ts', '.tsx', '.mjs'],
      output: ['.js'],
    },
    async load({filePath}) {
      const result = await babel.transformFileAsync(filePath);
      return result.code;
    },
  };
};

This is a simplified version of the official Snowpack Babel plugin, which builds all JavaScript, TypeScript, and JSX files in your application with the load() method.

The load() method is responsible for loading and build files from disk while the resolve property tells Snowpack which files the plugin can load and what to expect as output. In this case, the plugin claims responsibility for files matching any of the file extensions found in resolve.input, and outputs .js JavaScript (declared via resolve.output).

See it in action: Let’s say that we have a source file at src/components/App.jsx. Because the .jsx file extension matches an extension in our plugin’s resolve.input array, Snowpack lets this plugin claim responsibility for loading this file. load() executes, Babel builds the JSX input file from disk, and JavaScript is returned to the final build.

Multi-File Building

For a more complicated example, we’ll take one input file (.svelte) and use it to generate 2 output files (.js and .css).

const fs = require("fs").promises;
const svelte = require("svelte/compiler");

module.exports = function(snowpackConfig, pluginOptions) {
  return {
    name: 'my-svelte-plugin',
    resolve: {
      input: ['.svelte'],
      output: ['.js', '.css'],
    }
    async load({ filePath }) {
      const fileContents = await fs.readFile(filePath, 'utf-8');
      const { js, css } = svelte.compile(codeToCompile, { filename: filePath });
      return {
        '.js': js && js.code,
        '.css': css && css.code,
      };
    }
  };
};

This is a simplified version of the official Snowpack Svelte plugin. Don’t worry if you’re not familiar with Svelte, just know that building a Svelte file (.svelte) generates both JS & CSS for our final build.

In that case, the resolve property only takes a single input file type (['.svelte']) but two output file types (['.js', '.css']). This matches the result of Svelte’s build process and the returned entries of our load() method.

See it in action: Let’s say that we have a source file at src/components/App.svelte. Because the .svelte file extension matches an extension in our plugin’s resolve.input array, Snowpack lets this plugin claim responsibility for loading this file. load() executes, Svelte builds the file from disk, and both JavaScript & CSS are returned to the final build.

Notice that .svelte is missing from resolve.output and isn’t returned by load(). Only the files returned by the load() method are included in the final build. If you wanted your plugin to keep the original source file in your final build, you could add { '.svelte': contents } to the return object.

Optimizing & Bundling

Snowpack supports pluggable bundlers and other build optimizations via the optimize() hook. This method runs after the build and gives plugins a chance to optimize the final build directory. Webpack, Rollup, and other build-only optimizations should use this hook.

module.exports = function(snowpackConfig, pluginOptions) {
  return {
    name: 'my-custom-webpack-plugin',
    async optimize({ buildDirectory }) {
      await webpack.run({...});
    }
  };
};

This is an (obviously) simplified version of the @snowpack/plugin-webpack plugin. When the build command has finished building your application, this plugin hook is called with the buildDirectory path as an argument. It’s up to the plugin to read build files from this directory and write any changes back to the directory. Changes should be made in place, so only write files at the end and be sure to clean up after yourself (if a file is no longer needed after optimizing/bundling, it is safe to remove).

Tips / Gotchas

Plugin API

Check out our “SnowpackPlugin” TypeScript definition for a fully documented and up-to-date summary of the Plugin API and all supported options.

knownEntrypoints

// Example: Svelte plugin needs to make sure this dependency can be loaded.
knownEntrypoints: ["svelte/internal"]

An list of any npm dependencies that are added as a part of load() or transform() that Snowpack will need to know about. Snowpack analyzes most dependency imports automatically when it scans the source code of a project, but some imports are added as a part of a load() or transform() step, which means that Snowpack would never see them. If your plugin does this, add them here.

resolve

// Example: Sass plugin compiles Sass files to CSS.
resolve: {input: [".sass"], output: [".css"]}

// Example: Svelte plugin compiles Svelte files to JS & CSS.
resolve: {input: [".svelte"], output: [".js",[".css"]}

If your plugin defines a load() method, Snowpack will need to know what files your plugin is responsible to load and what its output will look like. resolve is only needed if you also define a load() method.

load()

Load a file from disk and build it for your application. This is most useful for taking a file type that can’t run in the browser (TypeScript, Sass, Vue, Svelte) and returning JS and/or CSS. It can even be used to load JS/CSS files directly from disk with a build step like Babel or PostCSS.

transform()

Transform a file’s contents. Useful for making changes to all types of output (JS, CSS, etc.) regardless of how they were loaded from disk.

run()

Run a CLI command, and connect it’s output into the Snowpack console. Useful for connecting tools like TypeScript.

optimize()

Snowpack’s bundler plugin API is still experimental and may change in a future release. See our official bundler plugins for an example of using the current interface:

Publishing a Plugin

To share a plugin with the world, you can publish it to npm. For example, take a look at snowpack-plugin-starter-template which can get you up-and-running quickly. You can either copy this outright or simply take what you need.

In general, make sure to mind the following checklist:

Back to Main Docs

👉 Back to the main docs.