@hypothesis/frontend-build

This package contains functions for building assets and running tests in
Hypothesis frontend projects, typically as part of Gulp tasks.

It assumes that the project is using our standard frontend tech stack and
follows certain conventions about the location and naming of files.

Prerequisites

This project assumes our standard tech stack for frontend projects:

- Gulp for running tasks [1]
- Rollup for building JavaScript bundles
- Tailwind or Sass for authoring styles
- Vitest for running tests

[1] Gulp is not required as the task runner, but is how most of our projects
are currently set up.

Usage

The typical structure of a Hypothesis frontend project looks like:

``sh
gulpfile.mjs # Gulp tasks
vitest.config.js # Vitest config file

src/ # Source files ("$PROJECT_NAME/static/scripts" in Python projects)
tests/
bootstrap.js # JS module that configures test environment

rollup.config.mjs # Rollup config that builds application/library bundles
rollup-tests.config.mjs # Rollup config that builds test bundle from build/scripts/test-inputs.js

build/ # Compiled frontend assets
scripts/ # Generated JS bundles
some-app.bundle.js
some-app.bundle.js.map

styles/ # Generated CSS bundles
some-app.css
some-app.css.map
`

Compiling frontend assets from source files is handled by tasks defined in
gulpfile.mjs.

To use this package, first add it as a dependency to the project:

`js
yarn add --dev @hypothesis/frontend-build
`

Then use the functions within Gulp tasks. For example:

`js
import { buildCSS, buildJS, watchCSS, runTests } from '@hypothesis/frontend-build';

gulp.task('build-js', () => buildJS('rollup.config.mjs'));
gulp.task('watch-js', () => watchJS('rollup.config.mjs'));
gulp.task('build-css', () => buildCSS(
['src/my-app.css', 'src/other-app.css'],
{ tailwind: true }
));
gulp.task('watch-css', () => gulp.watch('src/*/.css', 'build-css'));
gulp.task('watch', gulp.parallel('watch-js', 'watch-css'));
gulp.task('test', () => runTests({
bootstrapFile: 'src/tests/bootstrap.js',
vitestConfig: 'vitest.config.js',
rollupConfig: 'rollup-tests.config.mjs',
testsPattern: '*/-test.js',
});

// Project-specific tasks...
`

Functions can be imported from the main export, or from individual ones if you
don't want to install all optional peer dependencies:

`js
import { buildJS, watchJS } from '@hypothesis/frontend-build/rollup';
import { buildCSS } from '@hypothesis/frontend-build/sass';
import { runTests } from '@hypothesis/frontend-build/tests';

`

API reference

This section provides an overview of the functions in this package. See the
JSDoc comments for individual functions for full details.

$3

buildJS(rollupConfig) - Build one or more JavaScript bundles defined in a
Rollup config file. The Rollup config file must be an ES module.

watchJS(rollupConfig) - Same as buildJS, but watches for updates to input files
after building the bundle and rebuilds if they change.

buildCSS(inputs, options = {}) - Build one or more CSS bundles from CSS or SASS
entry points, with optional support for Tailwind.

- options.tailwind : Enable Tailwind

generateManifest(options) - Generate a JSON asset manifest suitable for use
with the h-assets package used by Python
apps to serve static assets.

$3

runTests(config) - Build a JavaScript bundle of tests from a set of input files
and run them in Vitest.

The test bundle is created by first finding all test files that match the
testsPattern argument and generating an entry point,
build/scripts/test-inputs.js, which imports all of the test files. The
bundle is then built by passing the config specified by rollupConfig to
Rollup. Once the bundle has been generated, Vitest is started using the config
file specified by vitestConfig, which should load the test bundle.

This command supports filtering which tests are run
by using the --grep CLI argument. If the --live CLI flag is
set, the test runner watches for changes and rebuild and re-runs the tests if
the input files change.

$3

log.{info, warn, error}(message...) - Log a message with a timestamp. This
is a re-export of fancy-log's API.

run(command, args)` - Run a CLI command and forward the output to the terminal.

Additional documentation

Release guide. _Note this is in the frontend-shared repository. The process is the same for this one._