diff options
Diffstat (limited to 'examples/snowpack/src/pages/concepts')
4 files changed, 158 insertions, 0 deletions
diff --git a/examples/snowpack/src/pages/concepts/build-pipeline.md b/examples/snowpack/src/pages/concepts/build-pipeline.md new file mode 100644 index 000000000..b996273a4 --- /dev/null +++ b/examples/snowpack/src/pages/concepts/build-pipeline.md @@ -0,0 +1,40 @@ +--- +layout: ../../layouts/content.astro +title: The Build Pipeline +description: Snowpack Build creates a production-ready website with or without a bundler +--- + + + +`snowpack build` - When you're ready to deploy your application, run the build command to generate a static production build of your site. Building is tightly integrated with your dev setup so that you are guaranteed to get a near-exact copy of the same code that you saw during development. + +### Bundle for Production + +**You should be able to use a bundler because you want to, and not because you need to.** That was the original concept that Snowpack was designed to address. Snowpack treats bundling as an optional production optimization, which means you're free to skip over the extra complexity of bundling until you need it. + +By default, `snowpack build` will build your site using the same unbundled approach as the `dev` command. This is fine for most projects, but you also may still want to bundle for production. Legacy browser support, code minification, code-splitting, tree-shaking, dead code elimination, and other performance optimizations can all be handled in Snowpack via bundling. + +Bundlers normally require dozens or even hundreds of lines of configuration, but with Snowpack it's just a one-line plugin with no config required. This is possible because Snowpack builds your application _before_ sending it to the bundler, so the bundler never sees your custom source code (JSX, TS, Svelte, Vue, etc.) and instead needs to worry only about building common HTML, CSS, and JS. + +```js +// Bundlers plugins are pre-configured to work with Snowpack apps. +// No config required! +{ + "plugins": [["@snowpack/plugin-webpack"]] +} +``` + +See [our bundling guides](/guides/optimize-and-bundle) for more information about connecting bundled (or unbundled) optimization plugins for your production builds. + +## Legacy Browser Support + +You can customize the set of browsers you'd like to support via the `package.json` "browserslist" property, going all the way back to IE11. This will be picked up when you run `snowpack build` to build for production. + +```js +/* package.json */ +"browserslist": ">0.75%, not ie 11, not UCAndroid >0, not OperaMini all", +``` + +If you're worried about legacy browsers, you should also add a bundler to your production build. Check out our [section on bundling for deployment](/guides/optimize-and-bundle) for more info. + +Note: During development (`snowpack dev`) we perform no transpilation for older browsers. Make sure that you're using a modern browser during development. diff --git a/examples/snowpack/src/pages/concepts/dev-server.md b/examples/snowpack/src/pages/concepts/dev-server.md new file mode 100644 index 000000000..b15bde96b --- /dev/null +++ b/examples/snowpack/src/pages/concepts/dev-server.md @@ -0,0 +1,11 @@ +--- +layout: ../../layouts/content.astro +title: The Dev Server +description: Snowpack's dev server is fast because it only rebuilds the files you change. Powered by ESM (ES modules). +--- + + + +`snowpack dev` - Snowpack's dev server is an instant dev environment for [unbundled development.](/concepts/how-snowpack-works) The dev server will build a file only when it's requested by the browser. That means that Snowpack can start up instantly (usually in **\<50ms**) and scale to infinitely large projects without slowing down. In contrast, it's common to see 30+ second dev startup times when building large apps with a traditional bundler. + +Snowpack supports JSX & TypeScript source code by default. You can extend your build even further with [custom plugins](/plugins) that connect Snowpack with your favorite build tools: TypeScript, Babel, Vue, Svelte, PostCSS, Sass... go wild! diff --git a/examples/snowpack/src/pages/concepts/hot-module-replacement.md b/examples/snowpack/src/pages/concepts/hot-module-replacement.md new file mode 100644 index 000000000..868bbd9a7 --- /dev/null +++ b/examples/snowpack/src/pages/concepts/hot-module-replacement.md @@ -0,0 +1,45 @@ +--- +layout: ../../layouts/content.astro +title: HMR + Fast Refresh +description: Snowpack's ESM-powered unbundled development means near-instant single file builds that only take 10-25ms to load and update in the browser. +--- + +Hot Module Replacement (HMR) is the ability to push file updates to the browser without triggering a full page refresh. Imagine changing some CSS, hitting save, and then instantly seeing your change reflected on the page without a refresh. That's HMR. + +HMR is not unique to Snowpack. However, Snowpack's ability to leverage ESM for unbundled development introduces near-instant single file builds that only take 10-25ms to load and update in the browser. + +Snowpack ships with ready, out-of-the-box HMR support for the following file types: + +- CSS +- CSS Modules +- JSON + +JavaScript HMR is also supported out-of-the-box, but often requires a few additional lines of code to properly integrate with your frontend framework's "render" function. See "Enabling HMR + Fast Refresh" below. + +## Fast Refresh + +In addition to normal HMR, Snowpack also supports **Fast Refresh** for most popular frameworks like React, Preact and Svelte. Fast Refresh is a framework-specific enhancement to HMR, which applies single file updates in a way that preserves component state across updates. Changes to a `<Timer />` component, for example, would be applied without resetting the component's internal state. + +Fast Refresh makes development even faster, especially when working on popups and other secondary view states that normally would require a click to re-open or re-visit after every change. + +## Enabling HMR + Fast Refresh + +Snowpack supports HMR for all popular frontend frameworks. **[Create Snowpack App (CSA)](https://github.com/snowpackjs/snowpack/blob/main/create-snowpack-app) ships with HMR enabled by default.** You can setup HMR yourself with just a few lines of code, and Fast Refresh can be enabled automatically via plugin: + +- Preact: [@prefresh/snowpack](https://www.npmjs.com/package/@prefresh/snowpack) +- React: [@snowpack/plugin-react-refresh](https://www.npmjs.com/package/@snowpack/plugin-react-refresh) +- Svelte: [@snowpack/plugin-svelte](https://www.npmjs.com/package/@snowpack/plugin-svelte) +- Vue (HMR only): [A few lines of code](https://github.com/snowpackjs/snowpack/blob/main/create-snowpack-app/app-template-vue/src/index.js#L7-L14) + +For more advanced HMR integrations, Snowpack created the [esm-hmr spec](https://github.com/snowpackjs/esm-hmr), a standard HMR API for any ESM-based dev environment: + +```js +// HMR Code Snippet Example +if (import.meta.hot) { + import.meta.hot.accept(({ module }) => { + // Accept the module, apply it into your application. + }); +} +``` + +Check out the full [ESM-HMR API reference](https://github.com/snowpackjs/esm-hmr) on GitHub. diff --git a/examples/snowpack/src/pages/concepts/how-snowpack-works.md b/examples/snowpack/src/pages/concepts/how-snowpack-works.md new file mode 100644 index 000000000..7b89c4dbd --- /dev/null +++ b/examples/snowpack/src/pages/concepts/how-snowpack-works.md @@ -0,0 +1,62 @@ +--- +layout: ../../layouts/content.astro +title: How Snowpack Works +description: Snowpack serves your application unbundled during development. Each file is built only once and is cached until it changes. +--- + +### Summary + +**Snowpack is a modern, lightweight build tool for faster web development.** Traditional JavaScript build tools like webpack and Parcel need to rebuild & rebundle entire chunks of your application every time you save a single file. This rebundling step introduces lag between hitting save on your changes and seeing them reflected in the browser. + +Snowpack serves your application **unbundled during development.** Each file needs to be built only once and then is cached forever. When a file changes, Snowpack rebuilds that single file. There's no time wasted re-bundling every change, just instant updates in the browser (made even faster via [Hot-Module Replacement (HMR)](/concepts/hot-module-replacement)). You can read more about this approach in our [Snowpack 2.0 Release Post.](/posts/2020-05-26-snowpack-2-0-release/) + +Snowpack's **unbundled development** still supports the same **bundled builds** that you're used to for production. When you go to build your application for production, you can plug in your favorite bundler via an official Snowpack plugin for Webpack or Rollup (coming soon). With Snowpack already handling your build, there's no complex bundler config required. + +**Snowpack gets you the best of both worlds:** fast, unbundled development with optimized performance in your bundled production builds. + + + +### Unbundled Development + +**Unbundled development** is the idea of shipping individual files to the browser during development. Files can still be built with your favorite tools (like Babel, TypeScript, Sass) and then loaded individually in the browser with dependencies thanks to ESM `import` and `export` syntax. Any time you change a file, Snowpack rebuilds only that file. + +The alternative is **bundled development.** Almost every popular JavaScript build tool today focuses on bundled development. Running your entire application through a bundler introduces additional work and complexity to your dev workflow that is unnecessary now that ESM is widely supported. Every change -- on every save -- must be rebundled with the rest of your application before your changes can be reflected in your browser. + +Unbundled development has several advantages over the traditional bundled development approach: + +- Single-file builds are fast. +- Single-file builds are deterministic. +- Single-file builds are easier to debug. +- Project size doesn’t affect dev speed. +- Individual files cache better. + +That last point is key: **Every file is built individually and cached indefinitely.** Your dev environment will never build a file more than once and your browser will never download a file twice (until it changes). This is the real power of unbundled development. + +### Using NPM Dependencies + +NPM packages are mainly published using a module syntax (Common.js, or CJS) that can't run on the web without some build processing. Even if you write your application using browser-native ESM `import` and `export` statements that would all run directly in the browser, trying to import any one npm package will force you back into bundled development. + +**Snowpack takes a different approach:** Instead of bundling your entire application for this one requirement, Snowpack processes your dependencies separately. Here's how it works: + +``` +node_modules/react/**/* -> http://localhost:3000/web_modules/react.js +node_modules/react-dom/**/* -> http://localhost:3000/web_modules/react-dom.js +``` + +1. Snowpack scans your website/application for all used npm packages. +2. Snowpack reads these installed dependencies from your `node_modules` directory. +3. Snowpack bundles all of your dependencies separately into single JavaScript files. For example: `react` and `react-dom` are converted to `react.js` and `react-dom.js`, respectively. +4. Each resulting file can be run directly in the browser, and imported via ESM `import` statements. +5. Because your dependencies rarely change, Snowpack rarely needs to rebuild them. + +After Snowpack builds your dependencies, any package can be imported and run directly in the browser with zero additional bundling or tooling required. This ability to import npm packages natively in the browser (without a bundler) is the foundation that all unbundled development and the rest of Snowpack is built on top of. + +```html +<!-- This runs directly in the browser with `snowpack dev` --> +<body> + <script type="module"> + import React from 'react'; + console.log(React); + </script> +</body> +``` |