Using json-path to transform webpack configuration

[KutnerUri]

This discussion showcases how to use JsonPath to select fragments from the Webpack config and mutate them as needed.

Motivation

Bit uses Webpack to generate component previews (docs and compositions). Rather than letting the user setup all these configuration, we provide and maintain "sane defaults" that does all sorts of things - provide metadata, enable hot module reloading, load assets, etc.
Bit still allows developers to override these configuration, with the useWebpack(config => confg) method.

However, accessing the specific part of the configuration is hard - it is complex, deep, and might change.
You will need a robust, specific, flexible way to do so - and json-path does just that.

Usage

json-path is a json query language that resembles xpath or css selector. Try it out here - https://jsonpath.com/.

Let's say I'd like to change the "modules" property of a our css loaders. I could use this complicated selector to select them specifically:

const optionsSlector = "$.module.rules..[?(@ && @.loader && @.loader.includes('css-loader'))].options.modules";

function enableCssModulesTransformer(config: Webpack.Configuration) {
  // ideally we would clone the config file..

  const options = JSONPath({ json: config, path: optionsSelector});
  options.auto = true; // naive implementation

  return config;
}

Why jsonpath-plus?

• It is popular and well maintained implementation of json-path (v6.0.0, over 1m downloads)
• It skips object prototype properties (which might have side-effects or have circularity)
• It goes only into matching paths (ie. '$..modules.loader' will not even look at config.plugins.loader)
• It's ok with both objects ({}) and arrays ([]) and gives a seamless experience.

Pitfalls

Be careful with jsonpath! ⚠️
Jsonpath is built to support primitive json objects.

Executing it on complex objects like a Webpack configuration could have unexpected consequences, like a stack overflow or a busy-wait-loop in case of circular nesting.

I don't know all the edge cases, and we will figure them out as we go along.
I good workaround is to make a more specific query - i.e. use

// use:
"$.module.rules..[?(@ && @.loader && @.loader.includes('css-loader'))].options.modules"
// instead of
"$..modules"

[KutnerUri]

Specifically for tailwind post-css plugin

We gave an example showing a programmatic way to insert the tailwind plugin into the postcss options. This was overly specific and might break. In that case, you could get this error:

postcss loader not found. this probably means the webpack config of bit itself has changed

You can fix it by using this query and avoiding errors all together:

"$.module.rules..[?(@ && @.loader && @.loader.includes('postcss-loader'))]..postcssOptions",

See a fully fledged example here:
https://bit.dev/bit-foundations/styling/tailwind/webpack-transformer/~code/tailwind.transformer.ts