@xh/hoist-dev-utils

🛠️ Hoist Dev Utils

Tooling for building and deploying web applications built on the Hoist React platform. This repository is made available as the @xh/hoist-dev-utils package on npm for import and use by applications.

Shared development dependencies

The package.json file in this repository specifies a set of development dependencies required for building Hoist React applications. Those applications can specify @xh/hoist-dev-utils as a dev dependency and transitively bring in libs for Webpack and all associated plugins used in app builds, including Webpack Dev Server, Babel, and other essential loaders.

In most cases this package could be the only dev dependency required by Hoist React apps, although apps might wish to configure additional tooling such as stylelint (for linting SASS files) or lint-staged and husky (for running linters as a pre-commit git hook). See the Toolbox package.json for examples of these libraries in action.

Webpack configuration

The configureWebpack.js module exports a single configureWebpack() method that can be used to output a complete Webpack configuration. This includes support for transpiling and bundling multiple client application entry points with preconfigured loaders for JS code (Babel), styles (CSS/SASS/PostCSS) and HTML index file generation. See the docs within that file for supported arguments and additional details.

The generated Webpack configuration also sets the value of several XH globals within the built JS code, via the Webpack DefinePlugin. These include XH.appCode and XH.appName (both required), XH.appVersion (typically set as part of the build) and similar.

The intention is to reduce application webpack config files to a minimal and manageable subset of options. An example of such a file would be:

const configureWebpack = require('@xh/hoist-dev-utils/configureWebpack');

module.exports = (env = {}) => {
    return configureWebpack({
        appCode: 'myApp',
        appName: 'My Application',
        appVersion: env.appVersion || '1.0-SNAPSHOT',
        favicon: './public/favicon.svg',
        devServerOpenPage: 'app/',
        ...env
    });
};

Note that additional env variables can be provided at build time, so the application file can specify initial defaults (such as appVersion above, checked in as a SNAPSHOT) that are then overridden for particular builds (e.g. via webpack --env prodBuild --env appVersion=1.2.3 to cut a versioned 1.2.3 release).

See the Hoist React docs for step-by-step details on the build process.

Favicons

To include a favicon with your app, provide the favicon option to configureWebpack(). This can be either a png or an svg file:

return configureWebpack({
    ...,
    favicon: './public/favicon.svg',
    ...
});

If your app is intended to be used on mobile devices, you may want to also include a wider variety of favicons. The following files will be automatically bundled in your app's manifest.json if they are found in your project's /client-app/public folder:

• favicon-192.png (192px x 192px)
• favicon-512.png (512px x 512px)
• apple-touch-icon.png (180px x 180px)

You can use the svg-favicon.sh script to automatically create these favicons from a square SVG. Note that this script requires inkscape to be installed. Download the latest version from https://inkscape.org/ or install on Mac via Homebrew with brew install inkscape.

Inkscape includes a command-line interface which is leveraged by the script. In order for the script to be able to use it, you must first symlink Inkscape to /usr/local/bin. (Note this step is not required if you have installed via Homebrew.)

ln -s /Applications/Inkscape.app/Contents/MacOS/inkscape \
/usr/local/bin/inkscape

Then run the script, passing a path to the SVG file as the argument. The command below assumes that you have hoist-dev-utils checked out as a sibling of your top-level project directory, and that you are running the command from within $projectDir/client-app/public:

../../../hoist-dev-utils/svg-favicon.sh favicon.svg

ESLint Configuration

✨ This package includes a development dependency on the @xh/eslint-config package. That package exports an eslint configuration object with ExHI's coding conventions and best practices for Hoist React based development.

Applications that already have @xh/hoist-dev-utils as a dependency can use these rules for their own ESLint config by specifying their .eslintrc file as simply:

{
  "extends": ["@xh/eslint-config"]
}

If required, rules and other settings extended from this base configuration can be overridden at the app level.

Hoist Dev Utils Development

To develop improvements to this library, clone its repo into your workspace alongside a project that uses Hoist-React, like Toolbox. Then follow the instructions for yarn link to symlink to this repo.

---

☎️ [e-mail] | https://xh.io

Copyright © 2024 Extremely Heavy Industries Inc.