From abcd7c465e6a4f070fb39da8a9efef0902eeaf92 Mon Sep 17 00:00:00 2001 From: Nicolas Coden Date: Thu, 20 Sep 2018 23:07:09 +0200 Subject: [PATCH] docs: add description of bundle formats in the Javascript doc --- docs/pages/javascript.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/pages/javascript.md b/docs/pages/javascript.md index 26e57aec2..dc0af0a5b 100644 --- a/docs/pages/javascript.md +++ b/docs/pages/javascript.md @@ -39,7 +39,7 @@ Know that they all require `foundation.core.js` to be loaded *first*. Some plugi ### Import in JavaScript -Foundation is exported as [UMD modules](http://bob.yexley.net/umd-javascript-that-runs-anywhere/). This means that Foundation and its plugins can be imported in any JavaScript environnement. +By default, Foundation is exported as [UMD modules](http://bob.yexley.net/umd-javascript-that-runs-anywhere/). This means that Foundation and its plugins can be imported and used in any JavaScript environnement. For example with [ES6](https://github.com/lukehoban/es6features#readme) (the ESM format): ```js @@ -63,6 +63,22 @@ var Foundation = require('foundation-sites'); var $dropdown = new Dropdown('#mydropdown'); ``` +#### All Javascript bundles + +Foundation is proposed in bundles of various module formats so you can pick the one that match the best your needs. If you don't know these terms yet, take a look at this [10-minute introduction to module formats in JavaScript](https://www.jvandemo.com/a-10-minute-primer-to-javascript-modules-module-formats-module-loaders-and-module-bundlers/). You will find in the `dist/js` folder the following bundles: + +* `foundation.js` UMD Default
+ Compatible with most environments and tools (AMD, CJS, ESM...). It works almost everywhere by checking the module format of your environments and then using it, which make the bundle a little heavier. + +* `foundation.cjs.js` CommonJS
+ Dedicated to Node.js and older bundlers like Browserify or Webpack v1. + +* `foundation.esm.js` ES6 Modules
+ Everything is transpiled to ES5 but the modules. Dedicated to modern bundlers, like Webpack 2+ or Rollup. They will automatically use this bundle and parse the ES6 modules to remove the unused code (see [tree shaking](#tree-shaking) below). + +* `foundation.es6.js` ES6
+ Unlike the others bundles, this bundle is not transpiled. It contains all the Foundation sources in ES6 in a single file. Use it if you want to manually transpile it for your own targets. + #### Tree Shaking Many bundlers like Webpack, Rollup or Parcel support tree shaking. It consists of the removing the unused code parts from your codebase or your dependencies. Take a look at these articles to know how it works and how to enable it: [How To Clean Up Your JavaScript Build With Tree Shaking](https://www.engineyard.com/blog/tree-shaking), [Why Webpack 2's Tree Shaking is not as effective as you think](https://advancedweb.hu/2017/02/07/treeshaking/) and [Reduce JavaScript Payloads with Tree Shaking](https://developers.google.com/web/fundamentals/performance/optimizing-javascript/tree-shaking/). -- 2.47.2