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.
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.
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.
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
โจ 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.
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.
โ๏ธ [email protected] | https://xh.io
Copyright ยฉ 2024 Extremely Heavy Industries Inc.