// Example: snowpack.config.mjs
// The added "@type" comment will enable TypeScript type information via VSCode, etc.

/** @type {import("snowpack").SnowpackUserConfig } */
export default {
  plugins: [
    /* ... */

To generate a basic configuration file scaffold in your Snowpack project run snowpack init.


Type: "test" | "development" | "production"Default: "development" for snowpack dev, "production" for snowpack build.

Specifies the “mode” that Snowpack should run in. The main impact of this is the value of __SNOWPACK_ENV__.MODE at runtime, although there are some other key differences between modes:

  • "test": testOptions.files are not excluded, and will be scanned & built as normal source files. Useful when running tests on top of Snowpack.


Type: stringDefault: /

Specify the root of a project using Snowpack. (Previously: config.cwd)


Type: string

Specify the root of your workspace or monorepo, if you are using one. When configured, Snowpack will treat any sibling packages in your workspace like source files, and pass them through your unbundled Snowpack build pipeline during development. This allows for fast refresh, HMR support, file change watching, and other dev improvements when working in monorepos.

When you build your site for production, symlinked packages will be treated like any other package, bundled and tree-shaken into single files for faster loading.


Deprecated! Moved to packageOptions.knownEntrypoints


Type: string

Inherit from a separate “base” config.

Can be a relative file path, an npm package, or a file within an npm package. Your configuration will be merged on top of the extended base config.


Type: string[]Default: ['**/node_modules/**/*']

Exclude any files from the Snowpack pipeline.

Supports glob pattern matching.


mount: {
  [path: string]: string | {url: string, resolve: boolean, static: boolean, dot: boolean}

Mount local directories to custom URLs in your built application.

  • mount.url | string | required : The URL to mount to, matching the string in the simple form above.
  • mount.static | boolean | optional | Default: false : If true, don’t build files in this directory. Copy and serve them directly from disk to the browser.
  • mount.resolve | boolean | optional | Default: true: If false, don’t resolve JS & CSS imports in your JS, CSS, and HTML files. Instead send every import to the browser, as written.
  • | boolean | optional | Default: false: If true, include dotfiles (ex: .htaccess) in the final build.


// snowpack.config.mjs
// Example: Basic "mount" usage
export default {
  mount: {
    src: '/dist',
    public: '/',

You can further customize this the build behavior for any mounted directory by using the expanded object notation:

// snowpack.config.mjs
// Example: expanded object notation "mount" usage
export default {
  mount: {
    // Same behavior as the "src" example above:
    src: {url: '/dist'},
    // Mount "public" to the root URL path ("/*") and serve files with zero transformations:
    public: {url: '/', static: true, resolve: false},


Type: Record<string, string|boolean|undefined>

Declare any environment variables that should be exposed on __SNOWPACK_ENV__ at runtime. See Environment Variables for more information.

// snowpack.config.mjs
export default {
  env: {
    API_URL: '',


Type: object (package: package or path)

Configure import aliases for directories and packages.

Note: In an older version of Snowpack, all mounted directories were also available as aliases by Default. As of Snowpack 2.7, this is no longer the case and no aliases are defined by Default.

// snowpack.config.mjs
// Example: alias types
export default {
  alias: {
    // Type 1: Package Import Alias
    lodash: 'lodash-es',
    react: 'preact/compat',
    // Type 2: Local Directory Import Alias (relative to cwd)
    components: './src/components',
    '@app': './src',


Type: array containing pluginName string or an array [pluginName, pluginOptions

Enable Snowpack plugins and their options.

Also see our Plugin guide

// snowpack.config.mjs
// Example: enable plugins both simple and expanded
export default {
  plugins: [
    // Simple format: no options needed
    // Expanded format: allows you to pass options to the plugin
    ['plugin-2', {'plugin-option': false}],


Type: object (option name: value)

Configure the Snowpack dev server.

Type: boolean or objectDefault: false

Toggles whether Snowpack dev server should use HTTPS with HTTP2 enabled. See the SSL Certificates Guide for more information.

If the value is true, Snowpack will look for a snowpack.crt and snowpack.key file in your root directory. If the value is an object, you may pass your custom cert and key files directly to it.

// snowpack.config.mjs
import fs from 'fs';

const cert = await fs.promises.readFile('/path/to/server.crt');
const key = await fs.promises.readFile('/path/to/server.key');

export default {
  devOptions: {
    secure: {cert, key},


Type: stringDefault: localhost

The hostname that the dev server is running on. Snowpack uses this information to configure the HMR websocket and properly open your browser on startup (see:


Type: numberDefault: 8080

The port the dev server runs on.


Type: string

Optional path to append to dev server url. May also include querystring parameters, example: test/foo.html?bar=123.

Type: stringDefault: "**Default**"

Configures how the dev server opens in the browser when it starts.

Any installed browser, e.g., “chrome”, “firefox”, “brave”, or the path to a browser. Set “none” to disable.


Type: "stream" | "dashboard"Default: "dashboard"

Set the output mode of the dev console:

  • "dashboard" delivers an organized layout of console output and the logs of any connected tools. This is recommended for most users and results in the best logging experience.
  • "stream" is useful when Snowpack is run in parallel with other commands, where clearing the shell would clear important output of other commands running in the same shell.


Type: booleanDefault: true

Toggles HMR on the Snowpack dev server.


Type: number (milliseconds) Default: 0

Milliseconds to delay HMR-triggered browser update.


Type: numberDefault: devOptions.port

The port where Snowpack’s HMR Websocket runs.


Type: booleanDefault: true

Toggles a browser overlay that displays JavaScript runtime errors when running HMR.


Type: stringDefault: "build"

NOTE: Deprecated, see buildOptions.out.


Type: string

If using Tailwind, specify the path to your config file. e.g.: tailwindConfig: './tailwind.config.js'


Type: object

NOTE: Deprecated, see packageOptions.


Type: object

Configure how npm packages are installed and used.


Type: string[]Example: "external": ["fs"]

Mark some imports as external. Snowpack will ignore these imports and leave them as-is in your final build.

This is an advanced feature: Bare imports are not supported in any major browser, so an ignored import will usually fail when sent directly to the browser. This will most likely fail unless you have a specific use-case that requires it.


Type: "local" | "remote"Default: "local"Example: "source": "local"

Your JavaScript npm packages can be consumed in two different ways: local and remote. Each mode supports a different set of package options. You can choose between these two different modes by setting the packageOptions.source property.


Load your dependencies from your local node_modules/ directory. Install and manage your dependencies using npm (or any other npm-ready package manager) and a project package.json file.

This is traditional Snowpack behavior matching Snowpack v2. This mode is recommended for anyone already using npm to manage their frontend dependencies.


Type: string[]

Known dependencies to install with Snowpack. Used for installing packages any dependencies that cannot be detected by our automatic import scanner (ex: package CSS files).


Type: booleanDefault: false

This will automatically polyfill any Node.js dependencies as much as possible for the browser

Converts packages that depend on Node.js built-in modules ("fs", "path", "url", etc.). You can see the full list of supported polyfills at the rollup-plugin-node-polyfills documentation

If you’d like to customize this polyfill behavior, you can provide your own Rollup plugin for the installer:

// snowpack.config.mjs
// Example: If `--polyfill-node` doesn't support your use-case, you can provide your own custom Node.js polyfill behavior
import rollupPluginNodePolyfills from 'rollup-plugin-node-polyfills';

export default {
  packageOptions: {
    polyfillNode: false,
    rollup: {
      plugins: [rollupPluginNodePolyfills({crypto: true, ...})],

When source="remote", Node.js polyfills are always provided. Configuring this option is only supported in source="local" mode.


Type: {[ENV_NAME: string]: (string true)}

Sets a process.env. environment variable inside the installed dependencies.

If set to true (ex: {NODE_ENV: true} or --env NODE_ENV) this will inherit from your current shell environment variable. Otherwise, set to a string (ex: {NODE_ENV: 'production'} or --env NODE_ENV=production) to set the exact value manually.

This option is only supported in source="local" mode. source="remote" does not support this feature yet.


Type: string[]Example: "packageLookupFields": ["svelte"]

Set custom lookup fields for dependency package.json file entrypoints, in addition to the defaults like “module”, “main”, etc.

This option is only supported in source="local" mode. source="remote" does not support this feature yet.


Type: string[]Example: "packageExportLookupFields": ["svelte"]

Set custom lookup fields for dependency package.json“exports” mappings.

This option is only supported in source="local" mode. source="remote" does not support this feature yet.


Type: Object

Allows customization of Snowpack’s internal Rollup configuration.

Snowpack uses Rollup internally to install your packages. This rollup config option gives you deeper control over the internal Rollup configuration that we use.

  • packageOptions.rollup.plugins | RollupPlugin[] - Provide an array of custom Rollup plugins that will run on every installed package. Useful for dealing with non-standard file types in your npm packages.
  • packageOptions.rollup.dedupe | string[] - If needed, deduplicate multiple versions/copies of a packages to a single one. This helps prevent issues with some packages when multiple versions are installed from your node_modules tree. See rollup-plugin-node-resolve for more documentation.
  • packageOptions.rollup.context | string - Specify top-level this value. Useful to silence install errors caused by legacy common.js packages that reference a top-level this variable, which does not exist in a pure ESM environment. Note that the 'THIS_IS_UNDEFINED' warning (“‘this’ keyword is equivalent to ‘undefined’ … and has been rewritten”) is silenced by default, unless --verbose is used.

This option is only supported in source="local" mode. source="remote" does not support custom Rollup install options.


Enable streaming package imports. Load dependencies from our remote CDN. Manage your dependencies using snowpack and a project snowpack.deps.json file.

Learn more about Streaming Remote Imports.


Type: stringDefault:

The remote origin to import packages from. When you import a new package, Snowpack will fetch those resources from this URL.

Currently, the origin must implement a specific response format that Snowpack can parse for ESM. In future versions of Snowpack we plan to add support for custom CDNs and import origins.


Type: stringDefault: .snowpack

The location of your project cache folder, relative to the project root. Snowpack will save cached data to this folder. For example, if packageOptions.types is set to true, Snowpack will save TypeScript types to a types directory within this folder.


Type: booleanDefault: false

If true, Snowpack will download TypeScript types for every package.


Type: object (option name: value)

Configure your final build.


Type: stringDefault: "build"

The local directory that we output your final build to.


Type: stringDefault: /

In your HTML, replace all instances of %PUBLIC_URL% with this

Inspired by the same Create React App concept. This is useful if your app will be deployed to a subdirectory.


Type: booleanDefault: true

Set to false to prevent Snowpack from deleting the build output folder (buildOptions.out) between builds.


Type: string
Default: ./node_modules/.cache/snowpack

Specify the cache directory in which bundled Node modules will be cached.


NOTE: Deprecated, see buildOptions.metaUrlPath.


NOTE: Deprecated, see buildOptions.metaUrlPath.


Type: stringDefault: _snowpack

Rename the default directory for Snowpack metadata. In every build, Snowpack creates meta files for loading things like HMR, Environment Variables, and your built npm packages.

When you build your project, this will be a path on disk relative to the buildOptions.out directory.


Type: booleanDefault: false

Generates source maps.

Experimental: Still in progress, you may encounter some issues when using source maps until this support is finalized.

Type: booleanDefault: false

Run Snowpack’s build pipeline through a file watcher. This option works best for local development when you have a custom frontend server (ex: Rails, PHP, etc.) and the Snowpack dev server cannot be used.


Type: booleanDefault: false

Toggles whether HTML fragments are transformed like full HTML pages.

HTML fragments are HTML files not starting with <!doctype html>.


Type: stringDefault: React.createElement (or h if Preact import is detected)

Set the name of the function used to create JSX elements.


Type: stringDefault: React.Fragment (or Fragment if Preact import is detected)

Set the name of the function used to create JSX fragments.


Type: stringDefault: undefined

If set, this string can be used to automatically inject JSX imports for every JSX/TSX file. React users might use import React from 'react' whereas Preact users might use import { h, Fragment } from 'preact'.


Configure your tests.


Type: string[]Default: ["__tests__/**/*", "**/*.@(spec|test).*"]

Specifies your test files. If NODE_ENV is set to “test”, Snowpack includes these files in your site build and scan them for installable dependencies. Otherwise, Snowpack excludes these files.


Type: object (option name: value)

This section is currently empty! In the future, this section may be used for experimental and not yet finalized.