https://github.com/hypothesis/frontend-build
Utilities for building Hypothesis frontend projects
https://github.com/hypothesis/frontend-build
Last synced: 5 months ago
JSON representation
Utilities for building Hypothesis frontend projects
- Host: GitHub
- URL: https://github.com/hypothesis/frontend-build
- Owner: hypothesis
- Created: 2021-10-19T07:44:13.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-08-12T13:19:37.000Z (11 months ago)
- Last Synced: 2025-08-12T15:23:38.409Z (11 months ago)
- Language: JavaScript
- Size: 3.49 MB
- Stars: 0
- Watchers: 5
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# @hypothesis/frontend-build
This package contains functions for building assets and running tests in
Hypothesis frontend projects, typically as part of [Gulp](https://gulpjs.com) 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](https://gulpjs.com) for running tasks [1]
- [Rollup](https://rollupjs.org/guide/en/) for building JavaScript bundles
- [Tailwind](https://tailwindcss.com) or [Sass](https://sass-lang.com) for authoring styles
- [Vitest](https://vitest.dev/) 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.
### Building asset bundles
`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](https://tailwindcss.com)
`generateManifest(options)` - Generate a JSON asset manifest suitable for use
with the [h-assets](https://pypi.org/project/h-assets/) package used by Python
apps to serve static assets.
### Running tests
`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.
### Utilities
`log.{info, warn, error}(message...)` - Log a message with a timestamp. This
is a re-export of [fancy-log](https://www.npmjs.com/package/fancy-log)'s API.
`run(command, args)` - Run a CLI command and forward the output to the terminal.
## Additional documentation
[Release guide](https://github.com/hypothesis/frontend-shared/blob/main/docs/releases.md). _Note this is in the frontend-shared repository. The process is the same for this one._