From 257df4b9ac87407281e56ac98e318c6cd5fd2d6c Mon Sep 17 00:00:00 2001 From: Mario Contreras Date: Sun, 20 Aug 2017 16:41:36 -0400 Subject: [PATCH 1/6] Explanation extended and ref.json file added --- src/content/guides/author-libraries.md | 65 +++++++++++++++++++------- 1 file changed, 47 insertions(+), 18 deletions(-) diff --git a/src/content/guides/author-libraries.md b/src/content/guides/author-libraries.md index bb131d7532c6..847240ddb9d2 100644 --- a/src/content/guides/author-libraries.md +++ b/src/content/guides/author-libraries.md @@ -8,12 +8,36 @@ contributors: - 5angel --- -webpack is a tool which can be used to bundle application code and also to bundle library code. If you are the author of a JavaScript library and are looking to streamline your bundle strategy then this document will help you. +webpack is a tool which can be used to bundle application code and also to bundle library code. If you are the author of a JavaScript library and are looking to streamline your bundle strategy then this document will help you with the differents webpack configurations to expose your libraries as you think convenient. -## Author a Library +## Authoring a Library -Let's assume that you are writing a small library `webpack-numbers` allowing to convert numbers 1 to 5 from their numeric to a textual representation and vice-versa. The implementation makes use of ES2015 modules, and might look like this: +Let's assume that you are writing a small library ,`webpack-numbers`, allowing to convert numbers 1 to 5 from their numeric representation to the textual one and vice-versa, e.g.: 2 to 'two'. +The implementation makes use of ES2015 modules, and might look like this: + +__src/ref.json__ +```javascript +[{ + "num": 1, + "word": "One" +}, { + "num": 2, + "word": "Two" +}, { + "num": 3, + "word": "Three" +}, { + "num": 4, + "word": "Four" +}, { + "num": 5, + "word": "Five" +}, { + "num": 0, + "word": "Zero" +}] +``` __src/index.js__ @@ -34,38 +58,43 @@ export function wordToNum(word) { }; ``` -The usage spec for the library will be as follows. +The usage specification for the library use will be as follows: ```javascript -import * as webpackNumbers from 'webpack-numbers'; - +import * as webpackNumbers from 'webpack-numbers';//ES2015 module import +var webpackNumbers = require('webpack-numbers');// CommonJS module require ... -webpackNumbers.wordToNum('Two') // output is 2 +webpackNumbers.wordToNum('Two') //ES2015 and CommonJS module use ... +//AMD module require +require(['webpackNumbers'], function ( webpackNumbers) { + ... + webpackNumbers.wordToNum('Two')//AMD module use + ... +}); -// CommonJS modules - -var webpackNumbers = require('webpack-numbers'); - -... -webpackNumbers.numToWord(3); // output is Three -... ``` - +The consumer also can use the library loading it with the script tag: ```html -// Or as a script tag ... ``` +The configurations also can expose the library in the next ways: +- Property in the global object, for node. +- Property in the this object. + For full library configuration and code please refer to [webpack-library-example](https://github.com/kalcifer/webpack-library-example) From a5f17b033a345b0fce3dc6f43915053a0a1b0733 Mon Sep 17 00:00:00 2001 From: Mario Contreras Date: Sun, 20 Aug 2017 20:44:01 -0400 Subject: [PATCH 2/6] Project Structure added Explanations rewritten to be more understandable. Warning for bug added. --- src/content/guides/author-libraries.md | 80 ++++++++++++++++++++------ 1 file changed, 62 insertions(+), 18 deletions(-) diff --git a/src/content/guides/author-libraries.md b/src/content/guides/author-libraries.md index 847240ddb9d2..3e7a181f821b 100644 --- a/src/content/guides/author-libraries.md +++ b/src/content/guides/author-libraries.md @@ -6,6 +6,7 @@ contributors: - johnstew - simon04 - 5angel + - marioacc --- webpack is a tool which can be used to bundle application code and also to bundle library code. If you are the author of a JavaScript library and are looking to streamline your bundle strategy then this document will help you with the differents webpack configurations to expose your libraries as you think convenient. @@ -14,7 +15,24 @@ webpack is a tool which can be used to bundle application code and also to bundl ## Authoring a Library Let's assume that you are writing a small library ,`webpack-numbers`, allowing to convert numbers 1 to 5 from their numeric representation to the textual one and vice-versa, e.g.: 2 to 'two'. -The implementation makes use of ES2015 modules, and might look like this: +The basic project structure may look like this. + +__project__ + +``` diff ++ |webpack.config.js ++ |- package.json ++ |- /src ++ |- index.js ++ |- ref.json +``` + +Initialize npm, install webpack and lodash +``` bash + +npm init -y +npm install --save-dev webpack lodash +``` __src/ref.json__ ```javascript @@ -101,18 +119,23 @@ For full library configuration and code please refer to [webpack-library-example ## Configure webpack -Now the agenda is to bundle this library +Now the agenda is to bundle this library achieving the next goals: + +- Without bundling `lodash`, but requiring it to be loaded by the consumer using `externals`. +- Setting the library name as `webpack-numbers`. +- Exposing the library as a variable called `webpackNumbers`. +- Being able to access the library inside Node.js.s + +Also, the consumer will be able to access` the library the `next ways: +- ES2015 module. i.e. `import webpackNumbers from 'webpack-numbers'`. +- CommonJS module. i.e. `require('webpack-numbers')`. +- Global variable when included through `script` tag. -- Without bundling `lodash` but requiring it to be loaded by the consumer. -- Name of the library is `webpack-numbers` and the variable is `webpackNumbers`. -- Library can be imported as `import webpackNumbers from 'webpack-numbers'` or `require('webpack-numbers')`. -- Library can be accessed through global variable `webpackNumbers` when included through `script` tag. -- Library can be accessed inside Node.js. ### Add webpack -Add basic webpack configuration. +Add this basic webpack configuration to bundle the library. __webpack.config.js__ @@ -129,7 +152,6 @@ module.exports = { ``` -This adds basic configuration to bundle the library. ### Add `externals` @@ -137,7 +159,7 @@ This adds basic configuration to bundle the library. Now, if you run `webpack`, you will find that a largish bundle file is created. If you inspect the file, you will find that lodash has been bundled along with your code. It would be unnecessary for your library to bundle a library like `lodash`. Hence you would want to give up control of this external library to the consumer of your library. -This can be done using the `externals` configuration as +This can be done using the `externals` configuration as: __webpack.config.js__ @@ -158,7 +180,7 @@ module.exports = { This means that your library expects a dependency named `lodash` to be available in the consumer's environment. -If you only plan on using your library as a dependency in another webpack bundle, you may specify externals as an array. +However, if you only plan on using your library as a dependency in another webpack bundle, you may specify externals as an array. ```javascript module.exports = { @@ -171,7 +193,7 @@ module.exports = { }; ``` -Please note: for bundles that use several files from a package like this +Please note: for bundles that use several files from a package like this: ```javascript import A from 'library/A'; @@ -195,11 +217,27 @@ module.exports = { }; ``` +W>At the moment of webpack 3.5.5, using the next configuration is not working properly as stated in the [issue 4824](https://github.com/webpack/webpack/issues/4824): +```javascript +module.exports = { + ... + output: { + ... + + libraryTarget: { + root:'_' + } + } + ... +}; +``` + + ### Add `libraryTarget` -For widespread use of the library, we would like it to be compatible in different environments, i. e. CommonJS, AMD, Node.js and as a global variable. +For widespread use of the library, we would like it to be compatible in different environments, i.e. CommonJS, AMD, Node.js and as a global variable. -To make your library available for reuse, add `library` property in webpack configuration. +To make your library available for reuse, add `library` property inside `output` in webpack configuration. __webpack.config.js__ @@ -214,7 +252,7 @@ module.exports = { }; ``` -This makes your library bundle to be available as a global variable when imported. To make the library compatible with other environments, add `libraryTarget` property to the config. +This makes your library bundle to be available as a global variable named `webpackNumbers` when imported. To make the library compatible with other environments, add `libraryTarget` property to the config. This will add the differents options about how the library can be exposed. __webpack.config.js__ @@ -224,13 +262,19 @@ module.exports = { output: { ... library: 'webpackNumbers', - libraryTarget: 'umd' + libraryTarget: 'umd', } ... }; ``` - -If `library` is set and `libraryTarget` is not, `libraryTarget` defaults to `var` as specified in the [output configuration documentation](/configuration/output). See [`output.libraryTarget`](/configuration/output#output-librarytarget) there for a detailed list of all available options. +You can expose the library in the next ways: +- Variable: as a global variable. Available in the `script` tag. i.e. `libraryTarget:'var'`. +- This: available trough the this object. i.e. `libraryTarget:'this'`. +- Window: available trough the `window` object, in the browser. i.e. `libraryTarget:'window'`. +- UMD: available after AMD or CommonJS `require`. i.e. `libraryTarget:'umd'` + +If `library` is set and `libraryTarget` is not, `libraryTarget` defaults to `var` as specified in the [output configuration documentation](/configuration/output). +See [`output.libraryTarget`](/configuration/output#output-librarytarget) there for a detailed list of all available options. ### Final Steps From ca58445d10557be3b1778ab6cdaaac04bfe16008 Mon Sep 17 00:00:00 2001 From: Mario Contreras Date: Wed, 23 Aug 2017 16:58:19 -0400 Subject: [PATCH 3/6] CI issues related with markdown fixed. --- src/content/guides/author-libraries.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/src/content/guides/author-libraries.md b/src/content/guides/author-libraries.md index 3e7a181f821b..76f30397090b 100644 --- a/src/content/guides/author-libraries.md +++ b/src/content/guides/author-libraries.md @@ -28,13 +28,14 @@ __project__ ``` Initialize npm, install webpack and lodash -``` bash +``` bash npm init -y npm install --save-dev webpack lodash ``` __src/ref.json__ + ```javascript [{ "num": 1, @@ -92,9 +93,10 @@ require(['webpackNumbers'], function ( webpackNumbers) { }); ``` + The consumer also can use the library loading it with the script tag: -```html +```html ... @@ -109,7 +111,9 @@ The consumer also can use the library loading it with the script tag: ``` + The configurations also can expose the library in the next ways: + - Property in the global object, for node. - Property in the this object. @@ -127,6 +131,7 @@ Now the agenda is to bundle this library achieving the next goals: - Being able to access the library inside Node.js.s Also, the consumer will be able to access` the library the `next ways: + - ES2015 module. i.e. `import webpackNumbers from 'webpack-numbers'`. - CommonJS module. i.e. `require('webpack-numbers')`. - Global variable when included through `script` tag. @@ -218,6 +223,7 @@ module.exports = { ``` W>At the moment of webpack 3.5.5, using the next configuration is not working properly as stated in the [issue 4824](https://github.com/webpack/webpack/issues/4824): + ```javascript module.exports = { ... @@ -232,6 +238,7 @@ module.exports = { }; ``` +W> However, you can set libraryTarget.var='_' to expect the library as a global variable ### Add `libraryTarget` @@ -267,7 +274,9 @@ module.exports = { ... }; ``` + You can expose the library in the next ways: + - Variable: as a global variable. Available in the `script` tag. i.e. `libraryTarget:'var'`. - This: available trough the this object. i.e. `libraryTarget:'this'`. - Window: available trough the `window` object, in the browser. i.e. `libraryTarget:'window'`. From d9d601d2f6daae523102e5003ab521944ab2a935 Mon Sep 17 00:00:00 2001 From: Mario Contreras Date: Thu, 31 Aug 2017 17:13:02 -0500 Subject: [PATCH 4/6] Grammar and spelling enhancements. --- src/content/guides/author-libraries.md | 32 +++++++++++++------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/src/content/guides/author-libraries.md b/src/content/guides/author-libraries.md index 76f30397090b..a7e3439e9f39 100644 --- a/src/content/guides/author-libraries.md +++ b/src/content/guides/author-libraries.md @@ -9,12 +9,12 @@ contributors: - marioacc --- -webpack is a tool which can be used to bundle application code and also to bundle library code. If you are the author of a JavaScript library and are looking to streamline your bundle strategy then this document will help you with the differents webpack configurations to expose your libraries as you think convenient. +Aside from applications, webpack can also be used to bundle JavaScript libraries. The following guide is meant for library authors looking to streamline their bundling strategy.. ## Authoring a Library -Let's assume that you are writing a small library ,`webpack-numbers`, allowing to convert numbers 1 to 5 from their numeric representation to the textual one and vice-versa, e.g.: 2 to 'two'. +Let's assume that you are writing a small library ,`webpack-numbers`, allowing to convert numbers 1 to 5 from their numeric representation to the textual one and vice-versa, e.g.: 2 to 'two'. The basic project structure may look like this. __project__ @@ -80,8 +80,8 @@ export function wordToNum(word) { The usage specification for the library use will be as follows: ```javascript -import * as webpackNumbers from 'webpack-numbers';//ES2015 module import -var webpackNumbers = require('webpack-numbers');// CommonJS module require +import * as webpackNumbers from 'webpack-numbers'; //ES2015 module import +var webpackNumbers = require('webpack-numbers'); //CommonJS module require ... webpackNumbers.wordToNum('Two') //ES2015 and CommonJS module use ... @@ -103,19 +103,19 @@ The consumer also can use the library loading it with the script tag: ``` -The configurations also can expose the library in the next ways: +The configurations also can expose the library in the following ways: - Property in the global object, for node. -- Property in the this object. +- Property in the `this` object. For full library configuration and code please refer to [webpack-library-example](https://github.com/kalcifer/webpack-library-example) @@ -123,14 +123,14 @@ For full library configuration and code please refer to [webpack-library-example ## Configure webpack -Now the agenda is to bundle this library achieving the next goals: +Now the plan is to bundle this library achieving the next goals: - Without bundling `lodash`, but requiring it to be loaded by the consumer using `externals`. - Setting the library name as `webpack-numbers`. - Exposing the library as a variable called `webpackNumbers`. - Being able to access the library inside Node.js.s -Also, the consumer will be able to access` the library the `next ways: +Also, the consumer will be able to access the library the following ways: - ES2015 module. i.e. `import webpackNumbers from 'webpack-numbers'`. - CommonJS module. i.e. `require('webpack-numbers')`. @@ -222,14 +222,14 @@ module.exports = { }; ``` -W>At the moment of webpack 3.5.5, using the next configuration is not working properly as stated in the [issue 4824](https://github.com/webpack/webpack/issues/4824): +W> With webpack 3.5.5, using the following configuration doesn't work properly as stated in [issue 4824](https://github.com/webpack/webpack/issues/4824): ```javascript module.exports = { ... output: { ... - + libraryTarget: { root:'_' } @@ -244,7 +244,7 @@ W> However, you can set libraryTarget.var='_' to expect the library as a global For widespread use of the library, we would like it to be compatible in different environments, i.e. CommonJS, AMD, Node.js and as a global variable. -To make your library available for reuse, add `library` property inside `output` in webpack configuration. +To make your library available for reuse, add the `library` property inside `output` in the webpack configuration. __webpack.config.js__ @@ -259,7 +259,7 @@ module.exports = { }; ``` -This makes your library bundle to be available as a global variable named `webpackNumbers` when imported. To make the library compatible with other environments, add `libraryTarget` property to the config. This will add the differents options about how the library can be exposed. +This makes your library bundle available as a global variable named `webpackNumbers` when imported. To make the library compatible with other environments, add `libraryTarget` property to the config. This will add the different options about how the library can be exposed. __webpack.config.js__ @@ -275,14 +275,14 @@ module.exports = { }; ``` -You can expose the library in the next ways: +You can expose the library in the following ways: - Variable: as a global variable. Available in the `script` tag. i.e. `libraryTarget:'var'`. - This: available trough the this object. i.e. `libraryTarget:'this'`. - Window: available trough the `window` object, in the browser. i.e. `libraryTarget:'window'`. - UMD: available after AMD or CommonJS `require`. i.e. `libraryTarget:'umd'` -If `library` is set and `libraryTarget` is not, `libraryTarget` defaults to `var` as specified in the [output configuration documentation](/configuration/output). +If `library` is set and `libraryTarget` is not, `libraryTarget` defaults to `var` as specified in the [output configuration documentation](/configuration/output). See [`output.libraryTarget`](/configuration/output#output-librarytarget) there for a detailed list of all available options. From a23f4c1b5ec105993348a866a5233d329a28eba3 Mon Sep 17 00:00:00 2001 From: Mario Contreras Date: Thu, 31 Aug 2017 17:15:35 -0500 Subject: [PATCH 5/6] Comments format normalized. --- src/content/guides/author-libraries.md | 28 ++++++++++++++++---------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/src/content/guides/author-libraries.md b/src/content/guides/author-libraries.md index a7e3439e9f39..b393e1f946f1 100644 --- a/src/content/guides/author-libraries.md +++ b/src/content/guides/author-libraries.md @@ -9,7 +9,7 @@ contributors: - marioacc --- -Aside from applications, webpack can also be used to bundle JavaScript libraries. The following guide is meant for library authors looking to streamline their bundling strategy.. +Aside from applications, webpack can also be used to bundle JavaScript libraries. The following guide is meant for library authors looking to streamline their bundling strategy. ## Authoring a Library @@ -80,15 +80,19 @@ export function wordToNum(word) { The usage specification for the library use will be as follows: ```javascript -import * as webpackNumbers from 'webpack-numbers'; //ES2015 module import -var webpackNumbers = require('webpack-numbers'); //CommonJS module require +// ES2015 module import +import * as webpackNumbers from 'webpack-numbers'; +// CommonJS module require +var webpackNumbers = require('webpack-numbers'); ... -webpackNumbers.wordToNum('Two') //ES2015 and CommonJS module use +// ES2015 and CommonJS module use +webpackNumbers.wordToNum('Two'); ... -//AMD module require +// AMD module require require(['webpackNumbers'], function ( webpackNumbers) { ... - webpackNumbers.wordToNum('Two')//AMD module use + // AMD module use + webpackNumbers.wordToNum('Two'); ... }); @@ -102,11 +106,11 @@ The consumer also can use the library loading it with the script tag: @@ -216,7 +220,8 @@ module.exports = { externals: [ 'library/A', 'library/B', - /^library\/.+$/ // everything that starts with "library/" + // everything that starts with "library/" + /^library\/.+$/ ] ... }; @@ -297,7 +302,8 @@ __package.json__ ```javascript { "main": "dist/webpack-numbers.js", - "module": "src/index.js", // To add as standard module as per https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md#typical-usage + // To add as standard module as per https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md#typical-usage + "module": "src/index.js", } ``` From 297ea3bf668b84d65bc5f6f67309389485a2094d Mon Sep 17 00:00:00 2001 From: Greg Venech Date: Sun, 3 Sep 2017 16:41:52 -0400 Subject: [PATCH 6/6] docs(guides): pre-merge clean up of author-libraries Minor fixes... - Code formatting - Full diffs for most instances - Some grammar fixes --- src/content/guides/author-libraries.md | 300 ++++++++++++------------- 1 file changed, 148 insertions(+), 152 deletions(-) diff --git a/src/content/guides/author-libraries.md b/src/content/guides/author-libraries.md index b393e1f946f1..c0c8e159fcb5 100644 --- a/src/content/guides/author-libraries.md +++ b/src/content/guides/author-libraries.md @@ -14,20 +14,21 @@ Aside from applications, webpack can also be used to bundle JavaScript libraries ## Authoring a Library -Let's assume that you are writing a small library ,`webpack-numbers`, allowing to convert numbers 1 to 5 from their numeric representation to the textual one and vice-versa, e.g.: 2 to 'two'. -The basic project structure may look like this. +Let's assume that you are writing a small library ,`webpack-numbers`, that allows users to convert the numbers 1 through 5 from their numeric representation to a textual one and vice-versa, e.g. 2 to 'two'. + +The basic project structure may look like this: __project__ ``` diff -+ |webpack.config.js ++ |- webpack.config.js + |- package.json + |- /src + |- index.js + |- ref.json ``` -Initialize npm, install webpack and lodash +Initialize npm, install webpack and lodash: ``` bash npm init -y @@ -38,23 +39,23 @@ __src/ref.json__ ```javascript [{ - "num": 1, - "word": "One" + "num": 1, + "word": "One" }, { - "num": 2, - "word": "Two" + "num": 2, + "word": "Two" }, { - "num": 3, - "word": "Three" + "num": 3, + "word": "Three" }, { - "num": 4, - "word": "Four" + "num": 4, + "word": "Four" }, { - "num": 5, - "word": "Five" + "num": 5, + "word": "Five" }, { - "num": 0, - "word": "Zero" + "num": 0, + "word": "Zero" }] ``` @@ -65,15 +66,15 @@ import _ from 'lodash'; import numRef from './ref.json'; export function numToWord(num) { - return _.reduce(numRef, (accum, ref) => { - return ref.num === num ? ref.word : accum; - }, ''); + return _.reduce(numRef, (accum, ref) => { + return ref.num === num ? ref.word : accum; + }, ''); }; export function wordToNum(word) { - return _.reduce(numRef, (accum, ref) => { - return ref.word === word && word.toLowerCase() ? ref.num : accum; - }, -1); + return _.reduce(numRef, (accum, ref) => { + return ref.word === word && word.toLowerCase() ? ref.num : accum; + }, -1); }; ``` @@ -84,67 +85,60 @@ The usage specification for the library use will be as follows: import * as webpackNumbers from 'webpack-numbers'; // CommonJS module require var webpackNumbers = require('webpack-numbers'); -... +// ... // ES2015 and CommonJS module use webpackNumbers.wordToNum('Two'); -... +// ... // AMD module require require(['webpackNumbers'], function ( webpackNumbers) { - ... - // AMD module use - webpackNumbers.wordToNum('Two'); - ... + // ... + // AMD module use + webpackNumbers.wordToNum('Two'); + // ... }); - ``` -The consumer also can use the library loading it with the script tag: +The consumer also can use the library by loading it via a script tag: -```html +``` html ... ``` -The configurations also can expose the library in the following ways: +Note that we can also configure it to expose the library in the following ways: - Property in the global object, for node. - Property in the `this` object. - -For full library configuration and code please refer to [webpack-library-example](https://github.com/kalcifer/webpack-library-example) +For full library configuration and code please refer to [webpack-library-example](https://github.com/kalcifer/webpack-library-example). -## Configure webpack +## Base Configuration -Now the plan is to bundle this library achieving the next goals: +Now let's bundle this library in a way that will achieve the following goals: - Without bundling `lodash`, but requiring it to be loaded by the consumer using `externals`. - Setting the library name as `webpack-numbers`. - Exposing the library as a variable called `webpackNumbers`. -- Being able to access the library inside Node.js.s +- Being able to access the library inside Node.js. -Also, the consumer will be able to access the library the following ways: +Also, the consumer should be able to access the library the following ways: - ES2015 module. i.e. `import webpackNumbers from 'webpack-numbers'`. - CommonJS module. i.e. `require('webpack-numbers')`. - Global variable when included through `script` tag. - - -### Add webpack - -Add this basic webpack configuration to bundle the library. +We can start with this basic webpack configuration: __webpack.config.js__ @@ -152,158 +146,160 @@ __webpack.config.js__ var path = require('path'); module.exports = { - entry: './src/index.js', - output: { - path: path.resolve(__dirname, 'dist'), - filename: 'webpack-numbers.js' - } + entry: './src/index.js', + output: { + path: path.resolve(__dirname, 'dist'), + filename: 'webpack-numbers.js' + } }; - ``` +## Externalize Lodash -### Add `externals` - -Now, if you run `webpack`, you will find that a largish bundle file is created. If you inspect the file, you will find that lodash has been bundled along with your code. -It would be unnecessary for your library to bundle a library like `lodash`. Hence you would want to give up control of this external library to the consumer of your library. +Now, if you run `webpack`, you will find that a largish bundle is created. If you inspect the file, you'll see that lodash has been bundled along with your code. In this case, we'd prefer to treat `lodash` as a `peerDependency`. Meaning that the consumer should already have `lodash` installed. Hence you would want to give up control of this external library to the consumer of your library. -This can be done using the `externals` configuration as: +This can be done using the `externals` configuration: __webpack.config.js__ -```javascript -module.exports = { - ... - externals: { - "lodash": { - commonjs: "lodash", - commonjs2: "lodash", - amd: "lodash", - root: "_" - } - } - ... -}; +``` diff + var path = require('path'); + + module.exports = { + entry: './src/index.js', + output: { + path: path.resolve(__dirname, 'dist'), + filename: 'webpack-numbers.js' +- } ++ }, ++ externals: { ++ lodash: { ++ commonjs: 'lodash', ++ commonjs2: 'lodash', ++ amd: 'lodash', ++ root: '_' ++ } ++ } + }; ``` This means that your library expects a dependency named `lodash` to be available in the consumer's environment. -However, if you only plan on using your library as a dependency in another webpack bundle, you may specify externals as an array. - -```javascript -module.exports = { - ... - externals: [ - 'react', - 'react-dom' - ] - ... -}; -``` +T> Note that if you only plan on using your library as a dependency in another webpack bundle, you may specify `externals` as an array. -Please note: for bundles that use several files from a package like this: -```javascript -import A from 'library/A'; -import B from 'library/B'; -... -``` +## External Limitations -you wont be able to exclude them from bundle by specifying `library` in the externals. +For libraries that use several files from a dependency: -You'll either need to exclude them one by one or by using a regular expression. +``` js +import A from 'dependency/one'; +import B from 'dependency/two'; -```javascript -module.exports = { - ... - externals: [ - 'library/A', - 'library/B', - // everything that starts with "library/" - /^library\/.+$/ - ] - ... -}; +// ... ``` -W> With webpack 3.5.5, using the following configuration doesn't work properly as stated in [issue 4824](https://github.com/webpack/webpack/issues/4824): - -```javascript -module.exports = { - ... - output: { - ... +You won't be able to exclude them from bundle by specifying `library` in the externals. You'll either need to exclude them one by one or by using a regular expression. - libraryTarget: { - root:'_' - } - } - ... -}; +``` js +externals: [ + 'library/one', + 'library/two', + // Everything that starts with "library/" + /^library\/.+$/ +] ``` -W> However, you can set libraryTarget.var='_' to expect the library as a global variable -### Add `libraryTarget` +## Expose the Library -For widespread use of the library, we would like it to be compatible in different environments, i.e. CommonJS, AMD, Node.js and as a global variable. - -To make your library available for reuse, add the `library` property inside `output` in the webpack configuration. +For widespread use of the library, we would like it to be compatible in different environments, i.e. CommonJS, AMD, Node.js and as a global variable. To make your library available for consumption, add the `library` property inside `output`: __webpack.config.js__ -```javascript -module.exports = { - ... +``` diff + var path = require('path'); + + module.exports = { + entry: './src/index.js', output: { - ... - library: 'webpackNumbers' + path: path.resolve(__dirname, 'dist'), +- filename: 'webpack-numbers.js' ++ filename: 'webpack-numbers.js', ++ library: 'webpackNumbers' + }, + externals: { + lodash: { + commonjs: 'lodash', + commonjs2: 'lodash', + amd: 'lodash', + root: '_' + } } - ... -}; + }; ``` -This makes your library bundle available as a global variable named `webpackNumbers` when imported. To make the library compatible with other environments, add `libraryTarget` property to the config. This will add the different options about how the library can be exposed. +This exposes your library bundle available as a global variable named `webpackNumbers` when imported. To make the library compatible with other environments, add `libraryTarget` property to the config. This will add the different options about how the library can be exposed. __webpack.config.js__ -```javascript -module.exports = { - ... +``` diff + var path = require('path'); + + module.exports = { + entry: './src/index.js', output: { - ... - library: 'webpackNumbers', - libraryTarget: 'umd', + path: path.resolve(__dirname, 'dist'), + filename: 'webpack-numbers.js', +- library: 'webpackNumbers' ++ library: 'webpackNumbers', ++ libraryTarget: 'umd' + }, + externals: { + lodash: { + commonjs: 'lodash', + commonjs2: 'lodash', + amd: 'lodash', + root: '_' + } } - ... -}; + }; ``` You can expose the library in the following ways: -- Variable: as a global variable. Available in the `script` tag. i.e. `libraryTarget:'var'`. -- This: available trough the this object. i.e. `libraryTarget:'this'`. -- Window: available trough the `window` object, in the browser. i.e. `libraryTarget:'window'`. -- UMD: available after AMD or CommonJS `require`. i.e. `libraryTarget:'umd'` +- Variable: as a global variable made available by a `script` tag (`libraryTarget:'var'`). +- This: available through the `this` object (`libraryTarget:'this'`). +- Window: available trough the `window` object, in the browser (`libraryTarget:'window'`). +- UMD: available after AMD or CommonJS `require` (`libraryTarget:'umd'`). -If `library` is set and `libraryTarget` is not, `libraryTarget` defaults to `var` as specified in the [output configuration documentation](/configuration/output). -See [`output.libraryTarget`](/configuration/output#output-librarytarget) there for a detailed list of all available options. +If `library` is set and `libraryTarget` is not, `libraryTarget` defaults to `var` as specified in the [output configuration documentation](/configuration/output). See [`output.libraryTarget`](/configuration/output#output-librarytarget) there for a detailed list of all available options. +W> With webpack 3.5.5, using `libraryTarget: { root:'_' }` doesn't work properly (as stated in [issue 4824](https://github.com/webpack/webpack/issues/4824)). However, you can set `libraryTarget: { var: '_' }` to expect the library as a global variable. -### Final Steps -[Tweak your production build using webpack](/guides/production). +### Final Steps -Add the path to your generated bundle as the package's main file in `package.json` +Optimize your output for production by following the steps in the [production guide](/guides/production). Let's also add the path to your generated bundle as the package's `main` field in with our `package.json` __package.json__ -```javascript +``` json +{ + ... + "main": "dist/webpack-numbers.js", + ... +} +``` + +Or, to add as standard module as per [this guide](https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md#typical-usage): + +``` json { - "main": "dist/webpack-numbers.js", - // To add as standard module as per https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md#typical-usage - "module": "src/index.js", + ... + "module": "src/index.js", + ... } ```