Snowpack

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use CommonJS `require()` syntax within an ES Module context, which Snowpack typically operates in.
  fix Replace `require()` calls with `import` statements. Ensure your configuration and source files are treated as ES Modules (e.g., by using `.mjs` extension for config, or `"type": "module"` in `package.json`).

• Error: Cannot find module 'snowpack'

  cause Snowpack is not installed or not found in the project's `node_modules`. This can happen if `npm install` was not run, or if it's installed globally but not linked correctly.
  fix Run `npm install snowpack` or `yarn add snowpack` in your project directory. If using global installation for CLI, ensure it's in your PATH or link it locally.

• Port 8080 is already in use

  cause Another process is already using the default development server port (8080) that Snowpack tries to bind to.
  fix Change the `port` option in your `snowpack.config.mjs` (e.g., `devOptions: { port: 3000 }`) or specify it via CLI (`snowpack dev --port 3000`).

Warnings

• breaking Snowpack is no longer actively maintained and is not recommended for new projects. Its development has ceased, and its creators have moved on to other tools like Vite. Expect no further updates, security patches, or community support.
  Fix: Migrate to an actively maintained alternative like Vite (created by Snowpack's original author) or esbuild.
• breaking Snowpack v3 introduced several breaking changes including configuration file renames (e.g., 'homepage' no longer sets 'baseUrl'), changes to relative path resolution in config files, and clearer build file naming conventions.
  Fix: Refer to the Snowpack v3 upgrade guide for specific migration steps. Update configuration properties (e.g., use 'buildOptions.baseUrl' directly) and adjust paths relative to the configuration file.
• gotcha Snowpack is an ESM-first tool. While it can process CommonJS dependencies, custom build scripts and programmatic API usage should adhere to ES Module syntax. Using `require()` for Snowpack's own API will lead to errors in most modern Node.js environments.
  Fix: Always use `import` statements for Snowpack's API and ensure your project's entry points are configured for ESM (e.g., using `.mjs` extension or `"type": "module"` in `package.json`).
• gotcha By default, Snowpack's `build` command generates an unbundled output optimized for modern browsers with native ESM. For traditional bundled and optimized production deployments (e.g., for older browser support or single-file delivery), it explicitly recommends integrating a separate bundler like Webpack or Rollup via plugins.
  Fix: For production, use a Snowpack bundler plugin (e.g., `@snowpack/plugin-webpack` or `@snowpack/plugin-rollup`) or pipe Snowpack's output to your preferred bundler for final optimization and bundling. This adds an extra step to the build process.
• gotcha The Node.js `engines` field specifies `>=10.19.0`. As Snowpack is unmaintained, it may not be compatible with newer Node.js versions, potentially leading to unexpected errors or installation failures with future Node.js releases.
  Fix: Pin your Node.js version to one known to be compatible with Snowpack (e.g., Node.js 16.x or 18.x). Consider migrating to an actively maintained tool for long-term project viability.

Install

• npm install snowpack npm
• yarn add snowpack yarn
• pnpm add snowpack pnpm

Imports

• startServer
  wrong:

  const { startServer } = require('snowpack');

  correct:

  import { startServer } from 'snowpack';

  Programmatic API for starting the development server. Snowpack is primarily ESM-driven.
• build
  wrong:

  const { build } = require('snowpack');

  correct:

  import { build } from 'snowpack';

  Programmatic API for initiating a production build.
• SnowpackConfig

  import type { SnowpackConfig } from 'snowpack';

  TypeScript type for configuration objects, useful when extending Snowpack or writing plugins.

Quickstart

This quickstart demonstrates a basic Snowpack project with TypeScript, including package scripts, a configuration file, an HTML entry point, and a TypeScript source file, ready for development and production builds.

{
  "name": "my-snowpack-app",
  "version": "1.0.0",
  "scripts": {
    "start": "snowpack dev",
    "build": "snowpack build"
  },
  "devDependencies": {
    "snowpack": "^3.8.8",
    "typescript": "^4.0.0"
  }
}

// snowpack.config.mjs
export default {
  mount: {
    'public': '/',
    'src': '/_dist_',
  },
  plugins: ['@snowpack/plugin-typescript'],
  optimize: {
    bundle: true,
    minify: true,
    target: 'es2018',
  },
  devOptions: {
    open: 'none',
  },
  buildOptions: {
    out: 'build',
    clean: true,
  },
};

// public/index.html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Snowpack App</title>
</head>
<body>
  <div id="root"></div>
  <script type="module" src="/_dist_/index.js"></script>
</body>
</html>

// src/index.ts
const app = document.getElementById('root');
if (app) {
  app.innerHTML = `<h1>Hello from Snowpack & TypeScript!</h1>`;
}

console.log('Snowpack development server is running...');