Skip to content

Latest commit

 

History

History
146 lines (120 loc) · 7.71 KB

05-configuration.md

File metadata and controls

146 lines (120 loc) · 7.71 KB
Raw

Configuration

Snowpack's behavior can be configured by CLI flags, a custom Snowpack config file, or both. See the table below for the full list of supported options.

Config Files

Snowpack supports configuration files in multiple formats, sorted by priority order:

  1. --config [path]: If provided.
  2. package.json: A namespaced config object ("snowpack": {...}).
  3. snowpack.config.js: (module.exports = {...}).
  4. snowpack.config.json: ({...}).

CLI Flags

# Show helpful info
$ snowpack --help

# {installOptions: {dest: 'CUSTOM_DIR/'}}
$ snowpack install --dest CUSTOM_DIR/

# {devOptions: {bundle: true}}
$ snowpack dev --bundle

# {devOptions: {bundle: false}}
$ snowpack dev --no-bundle

CLI flags will be merged with (and take priority over) your config file values. Every config value outlined below can also be passed as a CLI flag. Additionally, Snowpack also supports the following flags:

  • --config [path] Set the path to your project config file.
  • --help Show this help.
  • --version Show the current version.
  • --reload Clear the local cache. Useful for troubleshooting installer issues.

All Config Options

{
  "install": [
    "htm",
    "preact",
    "preact/hooks", // A package within a package
    "unistore/full/preact.es.js", // An ESM file within a package (supports globs)
    "bulma/css/bulma.css" // A non-JS static asset (supports globs)
  ],
  "homepage": "/your-project",
  "scripts": { /* ... */ },
  "installOptions": { /* ... */ },
  "devOptions": { /* ... */ },
  "proxy": { /* ... */ },
}

Top-Level Options

  • extends | 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.
  • exclude | string[]
    • Exclude any files from scanning, building, etc. Defaults to exclude common test file locations: ['**/node_modules/**/*', '**/__tests__/*', '**/*.@(spec|test).@(js|mjs)']
    • Useful for excluding tests and other unnecessary files from the final build. Supports glob pattern matching.
  • install | string[]
    • Known dependencies to install with Snowpack. Useful for installing packages manually and any dependencies that couldn't be detected by our automatic import scanner (ex: package CSS files).
  • homepage | string
    • By default, Snowpack's builds your app assuming it will be hosted at the server root.
    • You can set the "homepage" whenever your project is deployed anywhere other than the domain's root URL.
    • Note: Snowpack will also read this value from your package.json manifest.
  • scripts
    • Set build scripts to transform your source files. See the section below for more info.
  • installOptions.*
    • Configure how npm packages are installed. See the section below for all options.
  • devOptions.*
    • Configure your dev server and build workflows. See the section below for all options.
  • proxy.*
    • Configure the dev server to proxy requests. See the section below for all options.

Install Options

  • dest | string
    • Default:"web_modules"
    • Configure the install directory.
  • sourceMap | boolean
    • Emit source maps for installed packages.
  • env | {[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.
  • treeshake | boolean
    • Default:false, or true when run with snowpack build
    • Treeshake your dependencies to optimize your installed files. Snowpack will scan your application to detect which exact imports are used from each package, and then will remove any unused imports from the final install via dead-code elimination (aka tree shaking).
  • installTypes | boolean
    • Install TypeScript type declarations with your packages. Requires changes to your tsconfig.json to pick up these types.
  • alias | {[mapFromPackageName: string]: string}
    • Alias an installed package name. This applies to imports within your application and within your installed dependency graph.
    • Example: "alias": {"react": "preact/compat", "react-dom": "preact/compat"}
  • namedExports | string[]
    • Legacy Common.js (CJS) packages should only be imported by the default import (Example: import reactTable from 'react-table')
    • But, some packages use named exports in their documentation, which can cause confusion for users. (Example: import {useTable} from 'react-table')
    • You can enable "fake/synthetic" named exports for Common.js package by adding the package name under this configuration.
    • Example: "namedExports": ["react-table"]
  • rollup
    • Snowpack uses Rollup internally to install your packages. This rollup config option gives you deeper control over the internal rollup configuration that we use.
    • rollup.plugins - Specify Custom Rollup plugins if you are dealing with non-standard files.
    • rollup.dedupe - 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.

Dev Options

  • port | number | Default: 8080
    • The port number to run the dev server on.
  • out | string | Default: "build"
    • The local directory that we output your final build to.
  • bundle | boolean
    • Create an optimized, bundled build for production.
    • You must have Parcel as a dev dependency in your project.
    • If undefined, this option will be enabled if the parcel package is found.
  • fallback | string | Default: "index.html"
    • When using the Single-Page Application (SPA) pattern, this is the HTML "shell" file that gets served for every (non-resource) user route. Make sure that you configure your production servers to serve this as well.
  • open | string | Default: "default"
    • Opens the dev server in a new browser tab. If Chrome is available on macOS, an attempt will be made to reuse an existing browser tab. Any installed browser may also be specified. E.g., "chrome", "firefox", "brave". Set "none" to disable.
  • hmr | boolean | Default: true
    • Toggles whether or not Snowpack dev server should have HMR enabled.

Proxy Options

// snowpack.config.json
{
  "proxy": {
    // Short form:
    "/api/01": "https://pokeapi.co/api/v2/",
    // Long form:
    "/api/02": { 
      on: { proxyReq: (p, req, res) => /* Custom event handlers (JS only) */ },
      /* Custom http-proxy options */
    }
  }
}

If desired, "proxy" is where you configure the proxy behavior of your dev server. Define different paths that should be proxied, and where they should be proxied to.

The short form of a full URL string is enough for general use. For advanced configuration, you can use the object format to set all options supported by http-proxy.

on is a special property for setting event handler functions on proxy server events. See the section on "Listening for Proxy Events" for a list of all supported events. You must be using a snowpack.config.js JavaScript configuration file to set this.

This configuration has no effect on the final build.