Particle utilizes a multi-level inheritance model for it's various configurations. This allows the configuration to be extensible across multiple applications as well as multiple design systems. Configuration objects are merged together from generic to most specific.
Root webpack config: The root
.browserslistrc file to autoprefix CSS attributes as well as minify CSS in production. This is the base configuration that all other configurations extend from.
Design system config: Each design system has it's own configuration object which is merged onto the root webpack config. This config generally sets three items which are used throughout the implementation of the specific design system. The first config item is the ability to generate JSON from the design system's Sass variables as well as the includePaths for Sass to import other components. This config also initializes the SVGSpritemapPlugin with the path to SVGs and some basic options. This plugin creates Sass mixins to include SVG icons as well as a spritesheet of SVG assets. For a detailed list of how Particle handles SVGs, check out the Atoms > Svgicon page in Pattern Lab. Finally, this config imports the namespaces of the project and adds them to Webpack's alias resolver. This enables shorter imports such as
import thing from 'atoms/thing';.
App specific config: Each application contains it's own webpack configuration to specify settings needed to run it. This may include dev server settings, overrides to previously established file loaders, as well as the entry and output points for the app. Each app config has a webpack object for
prod. If there are no specific settings for one of these environments the variable is an empty object. Each app configuration exports a call to the particle function from
particle.js to create the webpack configuration object for that application.
The particle function exported from
particle.js also accepts a
cssMode key on the options object. The cssMode can be set to
fetch protocol is a relatively recent addition and does not exist on certain versions of IE. In order for the code to function properly a polyfill must be used to bridge that functionality. Babel's polyfill reads from the
.browserslistrc file to only polyfill the features that are needed for the targeted browsers.
The default Particle install will emit Webpack warnings when running the
build:pl script. These warnings are:
WARNING in asset size limit, and
WARNING in entrypoint size limit. The asset size limit is a result of the Font Awesome SVG map. This raw asset is tree-shaken during the build process to only utilize the icons used and referenced in the code base. The entrypoint size limit is a result of the decision to bundle everything into one entrypoint for initial install and ease of use. This can be optimized through creating multiple entry points, or code-splitting the bundle as described in the section below. Additionally, if you don't need libraries such as Vue for your application, the bundle size can be reduced by removing Vue examples from the dependency chain. These examples are located at
Analyzing your bundle output from Webpack allows you to utilize data visualization and inspect what comprises the bundle. This is useful for identifying potential performance bottlenecks, packages which are not tree shaking properly, as well as discovering potential areas for code splitting.
To analyze the bundle of an app, we'll generate a stats profile and then analyze it. Let's use the Pattern Lab app as an example.
npm run build:pl
Then, we're going to generate a profile stats file:
NODE_ENV=production npx webpack --config apps/pl/webpack.config.js --profile --json > dist/app-pl/assets/stats.json
Finally, let's fire up an interactive view of our bundle:
npx webpack-bundle-analyzer dist/app-pl/assets/stats.json
You'll be greeted with an open browser tab featuring a visualization at http://localhost:8888: