{"_id":"578fe61e29f79c19000892c1","category":{"_id":"57e48a4000c8680e00fae6e7","version":"55a6e72f8cc73e0d00096638","__v":0,"project":"55a6e72e8cc73e0d00096635","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-09-23T01:49:52.242Z","from_sync":false,"order":3,"slug":"advanced-installation-options","title":"Advanced Installation Options"},"parentDoc":null,"user":"55a6caa022cfa321008e01d6","version":{"_id":"55a6e72f8cc73e0d00096638","project":"55a6e72e8cc73e0d00096635","hasReference":false,"__v":29,"hasDoc":true,"createdAt":"2015-07-15T23:05:19.125Z","releaseDate":"2015-07-15T23:05:19.125Z","categories":["55a6e7308cc73e0d00096639","55b7ed07aea7c8190058badb","5604567c0c78b00d0039b191","5605e6f23a93940d002b3e4a","5605f2bba4574a0d00811365","5605f309a4574a0d00811366","5608e3b98aedf50d0004cf8f","5608e4318aedf50d0004cf90","5608e6b5a7cc2f0d00d9754d","5608e6d331beb60d001b6560","5608f879a7cc2f0d00d97580","560b097887b71d0d000d3bd9","560b13cbafa0990d00979545","560b5cbec341310d00de2a01","560b5cd0c341310d00de2a02","566a35b81e08750d00a0c49b","566a3e8503b4b20d00d02a4a","567889d307bf6a0d0083edc8","569c8b7c15bb390d00db6f9d","56b254dc65ddf50d0076ba8f","57a8ebc4cdeea20e001d2a63","57e48a4000c8680e00fae6e7","5808216773557d0f00a1e428","58105ad54a8aa50f00aa4cba","58105bf298aea40f00afa3ba","58105f548a4aed0f00d67536","581061b898aea40f00afa3be","584b3de7e5f3a42300df6ef7","596839a75965d400155bb750"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":1,"project":"55a6e72e8cc73e0d00096635","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-07-20T20:59:10.499Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Optional Workflow\",\n  \"body\": \"The steps below are required _only_ if you plan to modify or override the default Webpack-based workflow that installs with Stencil's default Cornerstone theme. (Webpack is also incorporated into current versions of most other Marketplace themes.) If you do not require these advanced configuration options, you can safely skip this page.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"This entry covers:\\n\\n<ul>\\n <li><a href=\\\"#jsomething\\\">Webpack, jspm, or Other JavaScript Managers</a></li>\\n <li><a href=\\\"#wpOptions\\\">Webpack-Specific Configuration</a></li>\\n  <ul> <!-- inner -->\\n \\t\\t<li><a href=\\\"#wpVerbose\\\">More-Verbose JavaScript Diagnostics</a>\\n    </li> <p></p>\\n  </ul> <!-- inner -->\\n <li><a href=\\\"#build_config\\\">Build-System Configuration File</a></li>\\n <li><a href=\\\"#watchOptions\\\">Watched Folders: watchOptions Object</a></li>\\n <li><a href=\\\"#development\\\">JavaScript Rebundling: development Function</a></li>\\n <li><a href=\\\"#production\\\">Theme Packaging: production Function</a></li>\\n <li><a href=\\\"#Next\\\">Next Steps</a></li>\\n</ul>\"\n}\n[/block]\n## <span id=\"jsomething\">Webpack, jspm, or Other JavaScript Managers</span>\n\nStencil themes are Node.js applications, and therefore contain dependencies on other JavaScript libraries. For Stencil's default Cornerstone theme, we provide the [Webpack](https://webpack.github.io/docs/) build manager to handle these dependencies. \n\nAs you develop a theme based on Cornerstone, you have options to reconfigure Webpack's watched folders, and to even substitute a different build system. These options are explained below.\n\nAll themes currently in the BigCommerce Theme Marketplace use Webpack. However, older versions of certain themes used the <a href=\"http://jspm.io/\">jspm</a> JavaScript dependency manager instead of Webpack. Please see [this page](/docs/downloading-and-customizing-marketplace-themes) to determine (by version number) whether you are developing based on one of these earlier versions, and to find the required jspm setup procedures.<p></p>\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"BigCommerce does not offer technical assistance on substitutions for the default dependencies listed in this documentation.\",\n  \"title\": \"Limited Support\"\n}\n[/block]\n## <span id=\"wpOptions\"> Webpack-Specific Configuration</span>\n\nThe following Webpack configuration options can aid in troubleshooting.\n\n### <span id=\"wpVerbose\"> More-Verbose JavaScript Diagnostics </span>\n\nIf JavaScript errors in your browser's developer tools are not reporting filenames and line numbers, try changing your `webpack.conf.js` file's [sourcemap](http://webpack.github.io/docs/build-performance.html) entry from:\n\n```\ndevtool: 'eval-cheap-module-source-map'\n```\nto:\n\n```\ndevtool: 'eval-source-map'\n```\n\nThe `eval-cheap-module-source-map` option performs faster rebuilds, but omits line numbers. The `eval-source-map` option is slower, but more verbose. <p></p>\n[block:html]\n{\n  \"html\": \"<!-- ### <span id=\\\"wpError\\\"> Module Not Found Errors </span>\\n\\nIf you see errors of this type:\\n \\n```\\n[ModuleNotFoundError: Module not found: Error: Cannot resolve module 'fs' in...]\\n```\\n\\nThen we recommend enabling Webpack's `--display-error-details` option to see richer diagnostics. -->\"\n}\n[/block]\n## <span id=\"build_config\">Build-System Configuration File</span>\n\nTo take advantage of automatic JavaScript bundling and browser refresh, Stencil themes require the [`stencil.conf.js`](https://github.com/bigcommerce/cornerstone/blob/master/stencil.conf.js) file. To enable a custom build system, you would need to edit this file.\n\nWithin `stencil.conf.js`, Stencil CLI looks for the exported `watchOptions` object, and `development` and `production` callbacks, shown below. For smooth theme development, all three must be defined – whether you are using Webpack or a custom build system:\n\n```\nmodule.exports = {\n    watchOptions: watchOptions,\n    development: development,\n    production: production,\n};\n```\nLet's take a closer look at each of these three references.\n\n\n## <span id=\"watchOptions\">Watched Folders: watchOptions Object</span>\n\nThe `watchOptions` object defines directories for the [Browsersync](https://browsersync.io/docs) preview engine to watch or ignore, in two respective lists. You are free to edit these lists:\n\n```\n/**\n * Watch options for the core watcher\n * :::at:::type {{files: string[], ignored: string[]}}\n */\nvar watchOptions = {\n    // If files in these directories change, reload the page.\n    files: [\n        '/templates',\n        '/lang'\n    ],\n\n    //Do not watch files in these directories\n    ignored: [\n        '/assets/scss',\n        '/assets/less',\n        '/assets/css',\n    ]\n};\n```\n\n## <span id=\"development\">JavaScript Rebundling: development Function</span>\n\nUpon the command-line instruction [`stencil start`](/docs/running-stencil-locally), Stencil CLI will look for and call the `development` function. This function passes an instance of Browsersync as its first argument. \n\nIn the base Cornerstone theme, we have created a Webpack watcher to trigger a browser reload whenever theme edits cause JavaScript to be rebundled to the theme's `bundle.js` file. This watcher uses options configured in the [webpack.conf.js file](https://github.com/bigcommerce/cornerstone/blob/master/webpack.conf.js) passed by `webpackConfig`. So a JavaScript rebuild will refresh the browser:\n\n```\nfunction development(Bs) {\n    var compiler = webpack(webpackConfig);\n\n    // Rebuild the bundle once at bootup\n    compiler.watch({}, function(err, stats) {\n        if (err) {\n            console.error(err)\n        }\n\n        Bs.reload();\n    });\n}\n```\n\n## <span id=\"production\">Theme Packaging: production Function</span>\n\nWhen you issue the command-line instruction [`stencil bundle`](/docs/bundling-submitting#ship-zip-small), to process and package a completed theme for upload to a store, Stencil CLI will look for and call the `production` function. This function passes a callback as its first argument, to support asynchronous builds. \n\nThe callback must be invoked somewhere inside the `production` function, to notify Stencil CLI that the theme-specific build has completed and is ready to package:\n\n```\nfunction production(done) {\n    var compiler;\n\n    webpackConfig.devtool = false;\n    webpackConfig.plugins.push(new webpack.optimize.DedupePlugin());\n    webpackConfig.plugins.push(new webpack.optimize.UglifyJsPlugin({\n        comments: false\n    }));\n\n    compiler = webpack(webpackConfig);\n\n    compiler.run(function(err, stats) {\n        if (err) {\n            throw err;\n        }\n\n        done();\n    });\n}\n```\n[block:html]\n{\n  \"html\": \"<H2> <A NAME=\\\"Next\\\"></a> Next Steps </h2>\\n\\nPlease proceed to <a href=\\\"/docs/launching-stencil\\\">Launching Stencil</a>.\\n\\n<!-- We invite you to proceed to:\\n\\n<ul>\\n<li> <a href=\\\"/docs/configjson-reference\\\">Configuration</a> reference.\\n  </li>\\n<li> <a href=\\\"/docs/using-yaml-front-matter\\\">Front-matter</a> overview of YAML conventions.\\n  </li>\\n<li> Front-matter <a href=\\\"/docs/front-matter-variables\\\">attributes</a> reference.\\n  </li>\\n<li> <a href=\\\"/docs/developing-with-handlebars\\\">Handlebars</a> development overview.\\n  </li>\\n<li> <a href=\\\"/docs/stencil-object-model\\\">Objects</a> reference.\\n  </li>\\n</ul> -->\"\n}\n[/block]","excerpt":"","slug":"webpack-and-build-options","type":"basic","title":"Configuring Webpack or a Custom Build System"}

Configuring Webpack or a Custom Build System


[block:callout] { "type": "info", "title": "Optional Workflow", "body": "The steps below are required _only_ if you plan to modify or override the default Webpack-based workflow that installs with Stencil's default Cornerstone theme. (Webpack is also incorporated into current versions of most other Marketplace themes.) If you do not require these advanced configuration options, you can safely skip this page." } [/block] [block:html] { "html": "This entry covers:\n\n<ul>\n <li><a href=\"#jsomething\">Webpack, jspm, or Other JavaScript Managers</a></li>\n <li><a href=\"#wpOptions\">Webpack-Specific Configuration</a></li>\n <ul> <!-- inner -->\n \t\t<li><a href=\"#wpVerbose\">More-Verbose JavaScript Diagnostics</a>\n </li> <p></p>\n </ul> <!-- inner -->\n <li><a href=\"#build_config\">Build-System Configuration File</a></li>\n <li><a href=\"#watchOptions\">Watched Folders: watchOptions Object</a></li>\n <li><a href=\"#development\">JavaScript Rebundling: development Function</a></li>\n <li><a href=\"#production\">Theme Packaging: production Function</a></li>\n <li><a href=\"#Next\">Next Steps</a></li>\n</ul>" } [/block] ## <span id="jsomething">Webpack, jspm, or Other JavaScript Managers</span> Stencil themes are Node.js applications, and therefore contain dependencies on other JavaScript libraries. For Stencil's default Cornerstone theme, we provide the [Webpack](https://webpack.github.io/docs/) build manager to handle these dependencies. As you develop a theme based on Cornerstone, you have options to reconfigure Webpack's watched folders, and to even substitute a different build system. These options are explained below. All themes currently in the BigCommerce Theme Marketplace use Webpack. However, older versions of certain themes used the <a href="http://jspm.io/">jspm</a> JavaScript dependency manager instead of Webpack. Please see [this page](/docs/downloading-and-customizing-marketplace-themes) to determine (by version number) whether you are developing based on one of these earlier versions, and to find the required jspm setup procedures.<p></p> [block:callout] { "type": "warning", "body": "BigCommerce does not offer technical assistance on substitutions for the default dependencies listed in this documentation.", "title": "Limited Support" } [/block] ## <span id="wpOptions"> Webpack-Specific Configuration</span> The following Webpack configuration options can aid in troubleshooting. ### <span id="wpVerbose"> More-Verbose JavaScript Diagnostics </span> If JavaScript errors in your browser's developer tools are not reporting filenames and line numbers, try changing your `webpack.conf.js` file's [sourcemap](http://webpack.github.io/docs/build-performance.html) entry from: ``` devtool: 'eval-cheap-module-source-map' ``` to: ``` devtool: 'eval-source-map' ``` The `eval-cheap-module-source-map` option performs faster rebuilds, but omits line numbers. The `eval-source-map` option is slower, but more verbose. <p></p> [block:html] { "html": "<!-- ### <span id=\"wpError\"> Module Not Found Errors </span>\n\nIf you see errors of this type:\n \n```\n[ModuleNotFoundError: Module not found: Error: Cannot resolve module 'fs' in...]\n```\n\nThen we recommend enabling Webpack's `--display-error-details` option to see richer diagnostics. -->" } [/block] ## <span id="build_config">Build-System Configuration File</span> To take advantage of automatic JavaScript bundling and browser refresh, Stencil themes require the [`stencil.conf.js`](https://github.com/bigcommerce/cornerstone/blob/master/stencil.conf.js) file. To enable a custom build system, you would need to edit this file. Within `stencil.conf.js`, Stencil CLI looks for the exported `watchOptions` object, and `development` and `production` callbacks, shown below. For smooth theme development, all three must be defined – whether you are using Webpack or a custom build system: ``` module.exports = { watchOptions: watchOptions, development: development, production: production, }; ``` Let's take a closer look at each of these three references. ## <span id="watchOptions">Watched Folders: watchOptions Object</span> The `watchOptions` object defines directories for the [Browsersync](https://browsersync.io/docs) preview engine to watch or ignore, in two respective lists. You are free to edit these lists: ``` /** * Watch options for the core watcher * @type {{files: string[], ignored: string[]}} */ var watchOptions = { // If files in these directories change, reload the page. files: [ '/templates', '/lang' ], //Do not watch files in these directories ignored: [ '/assets/scss', '/assets/less', '/assets/css', ] }; ``` ## <span id="development">JavaScript Rebundling: development Function</span> Upon the command-line instruction [`stencil start`](/docs/running-stencil-locally), Stencil CLI will look for and call the `development` function. This function passes an instance of Browsersync as its first argument. In the base Cornerstone theme, we have created a Webpack watcher to trigger a browser reload whenever theme edits cause JavaScript to be rebundled to the theme's `bundle.js` file. This watcher uses options configured in the [webpack.conf.js file](https://github.com/bigcommerce/cornerstone/blob/master/webpack.conf.js) passed by `webpackConfig`. So a JavaScript rebuild will refresh the browser: ``` function development(Bs) { var compiler = webpack(webpackConfig); // Rebuild the bundle once at bootup compiler.watch({}, function(err, stats) { if (err) { console.error(err) } Bs.reload(); }); } ``` ## <span id="production">Theme Packaging: production Function</span> When you issue the command-line instruction [`stencil bundle`](/docs/bundling-submitting#ship-zip-small), to process and package a completed theme for upload to a store, Stencil CLI will look for and call the `production` function. This function passes a callback as its first argument, to support asynchronous builds. The callback must be invoked somewhere inside the `production` function, to notify Stencil CLI that the theme-specific build has completed and is ready to package: ``` function production(done) { var compiler; webpackConfig.devtool = false; webpackConfig.plugins.push(new webpack.optimize.DedupePlugin()); webpackConfig.plugins.push(new webpack.optimize.UglifyJsPlugin({ comments: false })); compiler = webpack(webpackConfig); compiler.run(function(err, stats) { if (err) { throw err; } done(); }); } ``` [block:html] { "html": "<H2> <A NAME=\"Next\"></a> Next Steps </h2>\n\nPlease proceed to <a href=\"/docs/launching-stencil\">Launching Stencil</a>.\n\n<!-- We invite you to proceed to:\n\n<ul>\n<li> <a href=\"/docs/configjson-reference\">Configuration</a> reference.\n </li>\n<li> <a href=\"/docs/using-yaml-front-matter\">Front-matter</a> overview of YAML conventions.\n </li>\n<li> Front-matter <a href=\"/docs/front-matter-variables\">attributes</a> reference.\n </li>\n<li> <a href=\"/docs/developing-with-handlebars\">Handlebars</a> development overview.\n </li>\n<li> <a href=\"/docs/stencil-object-model\">Objects</a> reference.\n </li>\n</ul> -->" } [/block]