builder

builder is a shared webpack configuration, and scripts for running a dev server and building/bundling application code.

It currently resembles the start and build script functionality of the create-react-app package.

Installation and usage

1. Install

yarn add -D @dhi-gras/builder

2. Add & use scripts

Add to project package.json scripts

"build": "builder build",
"start": "builder start"

3. Add hot reload Not required to use the builder. If omitted, hot module replacement will not work and the webpage will be fully refreshed on save.

Install hot reload packages

yarn add -D react-hot-loader

Modify application code (suggested syntax)

// App .tsx
import { hot } from 'react-hot-loader/root' // eslint-disable-line import/no-extraneous-dependencies

// ... App component ...

const isEnvDev = process.env.NODE_ENV === 'development'
export default isEnvDev ? hot(App) : App

4. Run the scripts

Features / functionality

Only functionality that is specific to the builder will be covered here.

.env file integration

Environment variables specified in a .env file in the project root will be accessible to the application.

System environment variables

Only environment variables prefixed with APP_ (preffered) or REACT_APP will be accessible to the application.

Static files dir

Files placed in a directory named static in the project root will be copied to the output directory, named dist by default.

This can be useful for images and files that you don't wish to bundle in output JS files.

The files can be fetched via GET requests or used directly in a src attribute.
Specifying host is not required in most cases (when you're requesting the file from the same host name): /image.png
Otherwise, specify the full URL, and keep in mind that the url must be updated apropriately if the site is located in a subdirectory.

Sentry source map upload and release tagging

Note: This does not work out of the box! See setup below.

Source maps can be uploaded to Sentry projects. This allows sentry to display stack traces relevant to the source code.
This works in conjunction with specifiying releases - so you also see which release/build/commit the error occured.

Setup requirements

• Add release: COMMIT_SHA in the Sentry.init object argument in your app source.
• Ensure the COMMIT_SHA environment variable is accessible to builder. The azure-multi-deploy action does this out of the box.
• Ensure the SENTRY_PROJECT, SENTRY_ORG, SENTRY_AUTH_TOKEN environment variables are accessible to the builder prior to building the app, either as system variables or in a .env file in the project root Alternatively, you can add these settings in a .sentryclirc file, but note the different syntax.

Note: it is recommended to use an organization wide Sentry auth token. To access it, go to Organization Settings > Developer Settings > Internal Integrations. Use the token from the integration.

Motivation

• Minimal and customizable - we can adapt the bundler config to our project and development workflow needs
• Module bundler agnostic - while we currently use only webpack, we can use any module bundler or use multiple
• We decide what features to enable or try out - for example, if there's a new ES version we'd like to try out or support before general adoption
• Valuable skill - understanding how JavaScript is bundled, transpiled, etc. is easier when you can easily see and change the configuration

Drawback

We have to maintain the build utility and keep it up to date ourselves.
This requires developers to be interested in maintaining and learning about the utility and module bundling and similar concepts.