HACKING.md

Bootstrapping the development environment

You will need to npm install in a few places for it to work (look at travis.yml for an up-to-date source of truth).

A monstrous invocation like this should do it:

npm install &&
for dir in {packages/@happypack,upstream}/*
do
  ( cd $dir && npm install ) || exit $?
done

Where:

• upstream/* contains different webpack versions (targets) that happypack is tested against
• packages/@happypack/example-utils contains a few helper functions / constants needed to define the examples (again, because they're run against multiple targets)
• packages/@happypack/test-utils contains (unit) testing utilities
• packages/@happypack/webpack-config-composer is used by tests to generate a configuration for the current webpack version being targeted

Look at the test:webpack* scripts in package.json to learn how the unit tests are run.

Maintaining the integration tests

Directories under examples/ contain sample scripts for configuring webpack with happypack against a certain loader or plugin. The purpose is to provide working examples for users and some means of regression testing for a maintainer.

The master build script invokes these scripts using different versions of webpack (installed in upstream/) to ensure the integration does not regress with later Webpack releases. However, the process is somewhat convoluted mainly because it's not straightforward to run Node against different package trees.

Conventions expected by the runner:

• build.sh exists to invoke webpack and run any assertions on the output

  • The script may utilize the helpers defined in examples/build.sh like git-diff

  • The script has access in PATH to the webpack binary of the current target

  • The script has the following environment variables available for use:

    • EXAMPLE: String name of the example
    • EXAMPLE_DIR: Path base directory of the example
    • EXAMPLE_VERSION: Number the webpack version being targeted
    • EXAMPLE_OUT_DIR: Path where the webpack output will be assuming the scripts use the example helpers to define that path (see packages/@happypack/example-utils/index.js#.outputDir)
    • EXAMPLE_PKG_DIR: Path the base directory of the current version configuration scripts (e.g. where package.json will be found)

  • See the existing build.sh scripts under examples/ for guidance.

• Configuration scripts for each version are placed in:

  examples/[name]/versions/[webpack-version]/vanilla/webpack.config.js
  examples/[name]/versions/[webpack-version]/happy/webpack.config.js
  

• Build dependencies are tracked in separate package.json manifests, one for each version:

  examples/[name]/versions/[webpack-version]/package.json
  

Running the integration tests

Either do npm run test:examples or use examples/build.sh directly. It is possible to selectively run examples; see the header comment of that file for usage. For example, to run only the babel-loader examples:

# run the babel-loader example against all supported targets
./examples/build.sh -o babel-loader

# run babel-loader against webpack 2 only
./examples/build.sh -o babel-loader:2

# run everything except "extract-text-webpack-plugin"
./examples/build.sh -s extract-text-webpack-plugin