@xh/hoist 76.0.0-SNAPSHOT.1755187001333 → 76.0.0-SNAPSHOT.1755394070476

package/docs/build-and-deploy.md

@@ -9,16 +9,17 @@ at the build process.
 
 **_At a high level, the build process:_**
 
--   Builds the Grails back-end via Gradle, producing a WAR file.
--   Builds the JS front-end via Webpack, producing a set of production ready client assets.
--   Copies both outputs into a pair of Docker containers and publishes those containers as the
-    end-product of the build.
--   Deploys the new images, immediately or in a later step.
+- Builds the Grails back-end via Gradle, producing a WAR file.
+- Builds the JS front-end via Webpack, producing a set of production ready client assets.
+- Copies both outputs into a pair of Docker containers and publishes those containers as the
+  end-product of the build.
+- Deploys the new images, immediately or in a later step.
 
 Hoist does not mandate the use of any particular CI system, although we recommend and use
 [Jetbrains Teamcity](https://www.jetbrains.com/teamcity/) across multiple project deployments. The
 examples in this section do reference some Teamcity terms (although these concepts are very general
-and applicable to any common CI system).
+and applicable to any common CI system). In addition to TC, Hoist applications are currently built
+and deployed using GitHub Actions and Gitlab pipelines.
 
 Hoist also does not require the use of Docker or containerization in general, nor does it rely on
 any particular container orchestration technology (e.g. Kubernetes). That said, the move towards
@@ -29,20 +30,21 @@ to bundle up and somewhat abstract away the two-part nature of full-stack Hoist
 assigned to your application. This is a short, camelCased variant of the longer `appName` and is set
 within the application source code via both the Gradle and Webpack configs.
 
-### 1\) Setup/Prep
+## Setup/Prep
 
-#### 1.1) Refresh and Lint JS Client
+### Refresh and Lint JS Client
 
 We do this first to fail fast if the client code doesn't pass the linter checks, which is relatively
 common. This step could also run any preflight unit tests, etc. should you be diligent enough to
-have them.
+have them. The below assumes `yarn` is used for the project's package manager, sub with `npm` if
+using that instead.
 
 ```bash
 yarn
 yarn lint
 ```
 
-#### 1.2) Set Gradle project name (optional)
+### Set Gradle project name (optional)
 
 It’s best to be explicit with Gradle about the name of the project. By default it uses the name of
 the containing directory, which in a CI build is probably a random hash.
@@ -73,9 +75,9 @@ As a workaround, we can have the build system take the app name (we use a projec
 echo "rootProject.name = \"%appCode%\"" > settings.gradle
 ```
 
-### 2\) Server and Client Builds
+## Server and Client Builds
 
-#### 2.1) Build Grails server WAR with Gradle
+### Build Grails server WAR with Gradle
 
 This step calls into a `build.gradle` script checked in with each project to build the Grails
 server-side into a WAR.
@@ -83,11 +85,11 @@ server-side into a WAR.
 This step takes an application version as well as an optional build tag, both of which are baked
 into the build:
 
--   `xhAppVersion` - an x.y.z version for releases, or `x.y-SNAPSHOT` for transient builds.
--   `xhAppBuild` - this is an optional arg that gets baked into the server and client and exposed as a
-    variable for display in the built-in Hoist admin client. We use it to pass a git commit hash,
-    which then provides another way to cross-reference exactly what snapshot of the codebase was used
-    to build any given running application.
+- `xhAppVersion` - an x.y.z version for releases, or `x.y-SNAPSHOT` for transient builds.
+- `xhAppBuild` - this is an optional arg that gets baked into the server and client and exposed as a
+  variable for display in the built-in Hoist admin client. We use it to pass a git commit hash,
+  which then provides another way to cross-reference exactly what snapshot of the codebase was used
+  to build any given running application.
 
 Both version and build can be left unspecified, in which case the version will default to the
 version specified within the app’s `gradle.properties` file (the build tag is nullable). Our
@@ -108,18 +110,21 @@ project and used according to Gradle best practices.
 
 In both cases, the output is a `appCode-appVersion.war` file within `/build/libs`.
 
-#### 2.2) Build JS Client with Webpack
+### Build TS Client with Webpack
 
-This step builds all the client-side assets (JS/CSS/static resources) with Webpack, taking the
+This step builds all the client-side assets (TS/CSS/static resources) with Webpack, taking the
 source and dependencies and producing concatenated, minified, and hashed files suitable for serving
-to browsers. We use `yarn` as our package manager / runner tool.
+to browsers.
+
+In the example below, we use `yarn` as our package manager / runner tool.
 
 This step takes several arguments that are passed via a script in `package.json` to Webpack. Each
 project has a `webpack.config.js` file checked into the root of its `client-app` directory that
 accepts any args and runs them through a script provided by
 [hoist-dev-utils](https://github.com/xh/hoist-dev-utils/blob/master/configureWebpack.js) to produce
-a fully-based Webpack configuration object. The appVersion and appBuild params, detailed above, are
-the most common options passed in at build-time.
+a fully-based Webpack configuration object. See that project for additional details.
+
+The appVersion and appBuild params, detailed above, are the most common options set at build-time.
 
 An example Teamcity command line runner. ⚠️ Note this must run with `client-app` as its working
 directory:
@@ -136,9 +141,9 @@ yarn build --env.appVersion=$appVersion --env.appBuild=$appBuild
 
 The output is a set of files within `/client-app/build/` .
 
-### 3\) Docker images
+## Docker Container images
 
-🐳 The primary outputs of the overall build process are a pair of Docker containers, one for the
+The primary outputs of the overall build process are a pair of Docker containers, one for the
 Grails server and one for the client JS assets. These include the build assets and are tagged with
 the desired version, making them (as a pair) a complete and deployable instance of the application.
 
@@ -148,30 +153,32 @@ both the server and client containers. Both can be based on
 [those](https://github.com/xh/xh-tomcat) [images](https://github.com/xh/xh-nginx) will show that
 they are very thin layers on top of the official Tomcat and nginx images on Docker Hub.
 
-#### 3.1) Build and Publish Tomcat Docker image
+### Build and Publish Tomcat Docker image
 
 The Grails server component is deployed within a Tomcat container. The app should have a minimal
 `/docker/tomcat/Dockerfile` (checked into source control) such as:
 
 ```dockerfile
-FROM xhio/xh-tomcat:latest
+# Update the tag below to a fixed version for stability, or next to get a regularly updated build
+FROM xhio/xh-tomcat:next-jdk17
 COPY setenv.sh bin/
 COPY *.war webapps/ROOT.war
 ```
 
-The `setenv.sh` referenced here can also be checked in with the app project and used to set
-environment variables / Java Opts required by Tomcat. This typically contains a reasonable `Xmx`
-(max JVM heap) value for the app and a pointer to an “instance config” file used by Hoist apps to
-bootstrap themselves with DB credentials and other low-level configuration required at startup. By
-convention we place this file within a Docker volume that’s mounted to `/appCode` within each
-container
+------
 
-All this means that a `/docker/tomcat/setenv.sh` typically looks like:
+#### Optional `setenv.sh`
+
+The optional `setenv.sh` referenced here can be checked in with the app project and used to set
+environment variables / Java Opts required by Tomcat. This typically contains a reasonable `Xmx`
+(max JVM heap) value for the app, either hard-coded or referencing a CI param or env variable:
 
 ```bash
-export JAVA_OPTS="$JAVA_OPTS -Xmx2G -Dio.xh.hoist.instanceConfigFile=/appCode/conf.yml"
+export JAVA_OPTS="$JAVA_OPTS -Xmx2G"
 ```
 
+------
+
 That leaves the build with the job of generating a suitable tag for the container, running the
 Docker build, and then pushing to an appropriate (likely internal) Docker registry. The container
 tag should include the appCode + `-tomcat` to indicate that this is the Grails-side container.
@@ -203,28 +210,33 @@ rm *.war
 exit $ret
 ```
 
-#### 3.2) Build and Publish nginx Docker image
+### Build and Publish nginx Docker image
 
 The static JS resources are deployed within an nginx container. The app should have a minimal
 `/docker/nginx/Dockerfile/ ` (checked into source control) such as:
 
 ```dockerfile
-FROM xhio/xh-nginx:latest
-COPY app.conf $/XH_NGINX_CONFIG_PATH/
-COPY build/ $/XH_NGINX_CONTENT_PATH/
+# Update the tag below to a fixed version for stability, or next to get a regularly updated build
+FROM xhio/xh-nginx:next
+COPY app.conf $XH_NGINX_CONFIG_PATH/
+COPY build/ $XH_NGINX_CONTENT_PATH/
 ```
 
-Note that the `$XH` environment variables are set for convenience within the `xh-nginx` base image
+Note that the `$XH_` environment variables are set for convenience within the `xh-nginx` base image
 Dockerfile.
 
-The `app.conf` referenced here is an app-specific nginx configuration that should be checked in
+------
+
+#### About the `app.conf` nginx configuration file
+
+The `app.conf` referenced above is an app-specific nginx configuration that should be checked in
 alongside the Dockerfile. It should setup the available routes to serve each bundled client app,
-configure SSL certificates if needed, do any required redirects, and (importantly) include a _proxy
-configuration_ to pass traffic through from the nginx container to the Tomcat container. Hoist
-deploys typically bind only the nginx ports to the host machine, then link the nginx and Tomcat
-containers together via Docker so there’s a single point of entry (nginx) for incoming requests.
-This means that no CORS or further, external proxy configuration is required to have the
-nginx-dosted client communicate with its Tomcat back-end.
+handle any required redirects, and (importantly) include a _proxy configuration_ to pass traffic
+through from the nginx container to the Tomcat container. Hoist deploys typically bind only the
+nginx ports to the host machine, then link the nginx and Tomcat containers together via Docker/k8s
+so there’s a single point of entry (nginx) for incoming requests. This means that no CORS or
+further, external proxy configuration is required to have the nginx-hosted client communicate with
+its Tomcat back-end.
 
 While the exact content of the `app.conf` file will vary depending on the app, a representative
 example is below:
@@ -232,20 +244,19 @@ example is below:
 ```
 server {
     server_name  localhost;
-    include includes/xh-secure-redirect.conf;
-}
-
-server {
-    server_name  localhost;
-    listen 443 ssl;
+    listen 80;
     root   /usr/share/nginx/html;
 
-    ssl_certificate     /appCode/ssl/appCode.crt;
-    ssl_certificate_key /appCode/ssl/appCode.pem;
+    # NOT included here - CSP and other security-related headers. See Toolbox for recommendations,
+    # ensuring you tailor to your particular deployment environment and requirements.
 
-    # Redirect root to /app/
+    # Redirect root to platform-appropriate default client app - either app or mobile.
     location = / {
-        return 301 $scheme://$host/app/;
+        if ($is_mobile) {
+            return 302 https://$host/mobile/;
+        }
+
+        return 302 https://$host/app/;
     }
 
     # Static JS/CSS/etc assets not matching a more specific selector below
@@ -253,60 +264,60 @@ server {
         expires $expires;
     }
 
-    # App entry points - ensure trailing slash, match or fallback to index for sub-routes
-    location = /admin {
-        return 301 $uri/;
-    }
-
-    location /admin/ {
-        try_files $uri /admin/index.html;
+    # Entry points for all of this project's SPWA clients
+    location ~ ^/(admin|app|mobile)/?$ {
+        # Add trailing slash if not present. Use explicit redirect w/leading https as nginx is
+        # behind a load balancer and will first redirect to http otherwise, resulting in an excess
+        # redirect with the load balancer sending the browser back to https.
+        if ($request_uri ~ ^/(admin|app|mobile)$) {
+            return 301 https://$host$uri/;
+        }
+
+        # When at the correct path, check if the requested path exists as a file - if so, serve it.
+        # If not, serve index.html - this allows app routing to work - e.g. /admin/general/config
+        # will load /admin/index.html and allow the client app code to interpret the rest.
+        try_files $uri /$1/index.html;
         expires $expires;
     }
 
-    location = /app {
-        return 301 $uri/;
-    }
-
-    location /app/ {
-        try_files $uri /app/index.html;
-        expires $expires;
-    }
-
-    # Proxy to Grails back-end - appCode-tomcat is defined by Docker (e.g. via link)
+    # Proxy to Grails back-end, accessible to nginx on localhost as per container deployment.
     location /api/ {
-        proxy_pass http://appCode-tomcat:8080/;
+        proxy_pass http://localhost:8080/;
         include includes/xh-proxy.conf;
+        include includes/xh-hardeners.conf;
     }
 }
 ```
 
 **_Note that this example configuration:_**
 
--   Uses `appCode` as a placeholder - use the same code as configured in the app’s server and client
-    builds!
--   Calls several optional nginx config includes, sourced from the base `xh-nginx` image. The base
-    image also copies in [an overall config](https://github.com/xh/xh-nginx/blob/master/xh.conf) that
-    enables gzip compression and sets the `$expires` variable referenced above.
--   Redirects insecure requests to HTTPS on port 443 and terminates SSL itself, using certificates
-    sourced from `/appCode/ssl` - the conventional location for Hoist apps to store certs and keys
-    within an attached Docker volume.
--   Sets up locations for each client-app entry point / bundle - here we are shipping two JS apps with
-    this container: `app` - the business-user facing app itself - and `admin` - the built-in Hoist
-    Admin console. Apps might have other entry points, such as `mobile` or other more specific
-    bundles.
--   Uses the `try_files` directive to attempt to service requests at sub-paths by handing back asset
-    files if they exist, but otherwise falling back to `index.html` within that path. This allows for
-    the use of HTML5 “pushState” routing, where in-app routes are written to the URL without the use
-    of a traditional `#` symbol (e.g. <http://host/app/details/123>).
--   Creates a proxy endpoint at `/api/` to pass traffic through to the Tomcat back-end. This path is
-    expected by the JS client, which will automatically prepend it to the path of any local/relative
-    Ajax requests. This can be customized if needed on the client by adjusting the `baserUrl` param
-    passed to `configureWebpack()`.
+- Uses nginx config includes sourced from the base `xh-nginx` image. The base image also copies
+  in [an overall config](https://github.com/xh/xh-nginx/blob/master/xh.conf) that enables gzip
+  compression and sets the `$expires` variable referenced above.
+- Assumes a load balancer / ingress is handling SSL termination and that the nginx container is not
+  directly exposed to the internet. While uncommon for Hoist apps, nginx can handle SSL if needed.
+- Sets up locations for three client-app entry points / bundles: `app`, `admin`, and `mobile`, with
+  `mobile` being a dedicated app for mobile clients. Not all apps will have these three - some might
+  lack a mobile client entirely, or ship other dedicated client apps.
+- Uses the `try_files` directive to attempt to service requests at sub-paths by handing back asset
+  files if they exist, but otherwise falling back to `index.html` within that path. This allows for
+  the use of HTML5 “pushState” routing, where in-app routes are written to the URL without the use
+  of a traditional `#` symbol (e.g. <http://host/app/details/123>).
+- Creates a proxy endpoint at `/api/` to pass traffic through to the Tomcat back-end, which here is
+  expected to be reachable from nginx via `localhost`.
+    - The `/api/ `path is expected by the JS client, which will automatically prepend it to the path
+      of any local/relative fetch requests. This can be customized if needed on the client by
+      adjusting the `baserUrl` param passed to `configureWebpack()`.
+    - The use of `localhost` is enabled via a deployment configuration that runs the two containers
+      on the same pod / task / workload. This will vary based on the deployment environment.
+
+------
 
 The build system now simply needs to copy the built client-side resources into the Docker context
 and build the image. The sample below is simplified, but could also include the return code checks
-in the Tomcat example above. Note the `-nginx` suffix on the container tag. ⚠️ This example must
-also run with `docker/nginx` as its working directory:
+in the Tomcat example above. Note the `-nginx` suffix on the container tag.
+
+⚠️ This example must run with `docker/nginx` as its working directory:
 
 ```bash
 cp -R ../../client-app/build/ .
@@ -316,43 +327,40 @@ sudo docker build --pull -t "$containerTag" .
 sudo docker push "$containerTag"
 ```
 
-#### 3.3) Docker cleanup
+### Docker cleanup
 
 ✨ At this point the build is complete and new versioned or snapshot images containing all the
 runtime code have been pushed to a Docker registry and are ready for deployment.
 
 It might be beneficial to add one more step to clean up local Docker images on the build agent, to
 avoid them continuing to grow and take up disk space indefinitely. Note this forces Docker to pull
-the base images anew each time, which takes a small amount of time/bandwidth. It could probably be
-made more targeted if desired:
+the base images anew each time, which takes a small amount of time/bandwidth. It could be made more
+targeted if desired:
 
 ```bash
 sudo docker system prune -af
 ```
 
-### 4\) Docker deployment
+## Docker deployment
 
-🚢 We typically setup distinct targets for build vs. deploy, and configure deployment targets to
+🚢 XH typically creates distinct targets for build vs. deploy, and configure deployment targets to
 prompt for the version number and/or Docker hostname. This process will differ significantly
 depending on the use (or not) of orchestration technology such as Kubernetes or AWS Elastic
 Container Service (ECS).
 
 Regardless of the specific implementation, the following points should apply:
 
--   Both `appCode-tomcat` and `appCode-nginx` containers should be deployed as a service / pair, and
-    be kept at the same version.
--   The Tomcat container does not need to have any ports exposed/mapped onto the host (although it
-    could if direct access is desired).
--   The nginx container typically exposes ports 80 and 443, although if a load balancer or similar is
-    also in play that might vary (and would require appropriate adjustments to the `app.conf` nginx
-    file outlined above).
--   The nginx container must be able to reach the Tomcat container at the same name included in its
-    `app.conf` file - by convention, it expects to use `appCode-tomcat`. With straight Docker, this
-    can be accomplished via the `--link` option (see below).
--   A shared volume can be used to host the instance config .yml file for the Grails server, SSL certs
-    as required for nginx, and logs if so configured. This volume must be created in advance on the
-    host and populated with any required bootstrap files. How that’s done again will depend on the
-    particular Docker environment in play.
+- Both `appCode-tomcat` and `appCode-nginx` containers should be deployed as a service / pair, and
+  be kept at the same version.
+- The Tomcat container does not need to have any ports exposed/mapped onto the host (although it
+  could if direct access is desired).
+- The nginx container typically exposes ports 80 and 443, although if a load balancer or similar is
+  also in play that might vary (and would require appropriate adjustments to the `app.conf` nginx
+  file outlined above).
+- The nginx container must be able to reach the Tomcat container at the same name included in its
+  `app.conf` file, typically `localhost` (as in the example above).
+- A persistent volume can be used to store logs if so configured. How that’s done again will depend
+  on the particular deployment environment and is beyond the scope of this doc.
 
 A sample Teamcity SSH-exec runner using Docker directly:
 
@@ -384,8 +392,8 @@ sudo docker container rm $nginxName
 # Pull nginx image at specified version
 sudo docker image pull $nginxImage
 
-# Run nginx image - link to Tomcat for proxying, expose ports, and mount local docker volume for SSL certificate access
-sudo docker run -d --name $nginxName --link $tomcatName:$tomcatName -p 80:80 -p 443:443 --mount type=volume,src=$appCode,dst=/$appCode --restart always $nginxImage
+# Run nginx image - link to Tomcat for proxying, expose ports, and mount local docker volume for log storage
+sudo docker run -d --name $nginxName --link $tomcatName:$tomcatName -p 80:80 --mount type=volume,src=$appCode,dst=/$appCode --restart always $nginxImage
 echo "Deploying $nginxImage complete"
 
 # Prune Docker, cleaning up dangling images and avoiding disk space bloat
@@ -394,5 +402,6 @@ sudo docker system prune -af
 
 ------------------------------------------
 
-📫☎️🌎 info@xh.io | https://xh.io/contact
-Copyright © 2025 Extremely Heavy Industries Inc. - all rights reserved
+☎️ info@xh.io | <https://xh.io>
+
+Copyright © 2025 Extremely Heavy Industries Inc.

package/docs/development-environment.md

@@ -4,9 +4,18 @@ The information below applies to Hoist development generally and covers the setu
 development environment for both a [Hoist Core](https://github.com/xh/toolbox) server and a Hoist
 React client application.
 
-[Toolbox](https://github.com/xh/toolbox) is our reference app for Hoist development. Please also
-refer to [that project's README](https://github.com/xh/toolbox/blob/develop/README.md) for
-additional, Toolbox-specific setup info.
+[Toolbox](https://github.com/xh/toolbox) is our reference app for Hoist development and can be a
+useful project to check out and run locally to explore Hoist development. Please refer
+to [that project's README](https://github.com/xh/toolbox/blob/develop/README.md) for additional,
+Toolbox-specific setup info.
+
+## tldr;
+
+Development of Hoist applications requires:
+
+* Git
+* JDK 17
+* Node (LTS or other recent) + `npm` (bundled with Node) or `yarn` (installable via `npm`)
 
 ## Git
 
@@ -16,27 +25,34 @@ via [Homebrew](https://brew.sh/).
 
 ## Server-side prerequisites
 
-### Java 8 JDK
+Hoist Core is the server-side plugin powering Hoist React applications.
+See [that project's README](https://github.com/xh/hoist-core/blob/develop/README.md) for more
+detailed information about the configuration and use of Hoist's Grails server.
 
-The one common pre-requisite for running the server-side of a Hoist project is a Java 8 JDK. Either
-an Oracle or any common OpenJDK distribution should be fine.
+### Java 17 JDK
+
+The one common pre-requisite for running the server-side of a Hoist project is a Java 17 JDK. Any
+common OpenJDK distribution should work. XH typically uses the JetBrains distro, which has
+improved support for hot reloading, helpful for Hoist projects with a significant amount of server-
+side development.
 
 If using IntelliJ (see below), consider having the IDE download and update a JDK for you:
 
--   From the "File > New Projects Settings" menu, open "Structure for New Projects..." If you have an
-    existing project open, you can also select "File > Project Structure" to modify that project.
--   Select the "SDKs" option in the navigation tree.
--   Click the + button and select "Download JDK..."
--   Select version 8/1.8 - a known-good option to choose is the "Azul" open source SDK.
+- From the "File > New Projects Settings" menu, open "Structure for New Projects..." If you have an
+  existing project open, you can also select "File > Project Structure" to modify that project.
+- Select the "SDKs" option in the navigation tree.
+- Click the + button and select "Download JDK..."
+- Select version 17 and a distro of your choice (JetBrains Runtime is a good default).
 
-### Other server-side requirements
+### Server-side instance configuration
 
-Specific projects can have their own additional requirements for running their server-side
-application, typically around database access or connection configuration. Before starting the
-server-side of a project for the first time, ensure you have the required instance configuration
-YAML file in place to tell your app where and how to connect to its database.
+Before starting the server-side of a project for the first time, ensure you have copied the
+project's `template.env` to `.env` and filled in any missing instance configuration values required
+to provide environment-specific database connection and service account details.
 
-For Toolbox development, see that project's README for TB-specific database info.
+Note that some older projects might use a YAML config file in place of `.env` - if you don't see a
+`.env.template` file in the root of your project repo, this is likely the case. Consult another
+developer on the project or ask XH for assistance.
 
 ## Client-side prerequisites
 
@@ -45,28 +61,26 @@ For Toolbox development, see that project's README for TB-specific database info
 A recent version of Node.js is required to build and run the client-side component of the
 application (via Webpack and webpack-dev-server).
 
--   The latest (or any recent) LTS build is recommended - you can download directly from
-    https://nodejs.dev/ or use a tool (recommended) such as Homebrew or NVM (node-version-manager) to
-    install and update your local node versions.
--   Ensure that node is on your path via `node --version`.
+- The latest (or any recent) LTS build is recommended - you can download directly from
+  https://nodejs.dev/ or use a tool (recommended) such as Homebrew or NVM (node-version-manager) to
+  install and update your local node versions.
+- Ensure that node is on your path via `node --version`.
 
 ### Yarn
 
-XH uses Yarn for JS package management. To reduce variability across workstations, we typically
-include an updated, portable version of yarn bundled within each project, but a local yarn install
-is still required to detect and run the portable copy.
-
--   The easiest way to install yarn is with npm (🤯): `npm i -g yarn`
--   Once installed, verify it can be run globally with `yarn --version`
--   Within the `client-app` directory of a Hoist app such as Toolbox, run `yarn` to download, install,
-    and build all client-side dependencies. (Note that `yarn` is a shortcut for `yarn install` - they
-    do the same thing.)
+XH uses both `yarn` (v1) and `npm` (recent/lts) for JS package management - Hoist has no requirement
+for one over the other, although `npm` has been found to work better in some corporate environments
+with intensive workstation and/or network-level antimalware and other file scanning. The important
+thing is to decide on one or the other for your project and ensure all developers use the same tool.
 
-### Other client-side requirements
+When using `yarn`, we typically include an updated, portable version of yarn bundled within each
+project, but a local yarn install is still required to detect and run the portable copy:
 
-Some Hoist React dependencies can require a post-install build step, which looks for and can require
-some supporting build tools (such as Python) on your local workstation. Most of the time this works
-seamlessly, but contact the XH team if you receive any post-install errors from these dependencies.
+- The easiest way to install yarn is with npm (🤯): `npm i -g yarn`
+- Once installed, verify it can be run globally with `yarn --version`
+- Within the `client-app` directory of a Hoist app such as Toolbox, run `yarn` to download, install,
+  and build all client-side dependencies. (Note that `yarn` is a shortcut for `yarn install` - they
+  do the same thing.)
 
 ## JetBrains IntelliJ
 
@@ -98,27 +112,27 @@ beyond the scope of this doc. There are a few recommended settings to highlight,
 
 From within the IDE's general preferences / settings dialog:
 
--   Navigate to _Languages & Frameworks > Javascript_:
-    -   Ensure "ECMAScript 6+" selected in the top-level of this section.
-    -   Expand _Webpack_ - if doing local Toolbox + Hoist React development, you can choose to configure
-        "Manually" and point IntelliJ at a stub `webpack.config.intellij.js` checked-in at the root of
-        your local hoist-react project. This will cause IntelliJ to resolve any auto-suggestions or
-        context clues to the local versions of the Hoist classes and utils.
-    -   Expand _Code Quality Tools > Eslint_ - select "Automatic" configuration to enable eslint to run
-        and monitor your code as you update it. Note that you will need to have run `yarn` to install
-        your local client-side dependencies first.
--   Navigate to _Languages & Frameworks > Node.js and NPM_:
-    -   Ensure the IDE has detected the version of Node you wish to use.
-    -   You can also specify yarn as your package manager, if you wish to use the IDEs built-in yarn
-        integration.
--   Navigate to _Languages & Frameworks > Stylesheets > Stylelint_:
-    -   Enable with "Automatic configuration" to turn on local support for Stylelint, if using in your
-        project.
--   Navigate to _Version Control > Git_ - verify the IDE has detected your local git and select
-    "Update method: Rebase" to avoid introducing unnecessary merge commits when updating your local
-    repo.
-    -   The GitToolBox plugin is a useful add-on to IntelliJ, with several useful enhancements to
-        version control support.
+- Navigate to `Languages & Frameworks > Javascript`:
+    - Ensure "ECMAScript 6+" selected in the top-level of this section.
+    - Expand `Webpack` - *if doing local Toolbox + Hoist React development*, you can choose to
+      configure "Manually" and point IntelliJ at a stub `webpack.config.intellij.js` checked-in at
+      the root of your local hoist-react project. This will cause IntelliJ to resolve any
+      auto-suggestions or context clues to the local versions of the Hoist classes and utils.
+    - Expand `Code Quality Tools > Eslint` - select "Automatic" configuration to enable eslint to
+      run and monitor your code as you update it. Note that you will need to have run `yarn` to
+      install your local client-side dependencies first.
+    - If using Prettier in your project, enable that as well in the dedicated `Prettier` section.
+- Navigate to `Languages & Frameworks > Node.js and NPM`:
+    - Ensure the IDE has detected the version of Node you wish to use.
+    - You can also specify yarn as your package manager, if you wish to use the IDEs built-in yarn
+      integration.
+- Navigate to `Languages & Frameworks > Stylesheets > Stylelint`:
+    - Enable with "Automatic configuration" to turn on local support for Stylelint, if using in your
+      project.
+- Navigate to `Version Control > Git` - verify the IDE has detected your local git and select
+  "Update method: Rebase" to avoid unnecessary merge commits when updating your local repo.
+    - The GitToolBox plugin is a useful add-on to IntelliJ, with several useful enhancements to
+      version control support.
 
 ------------------------------------------
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "76.0.0-SNAPSHOT.1755187001333",
+  "version": "76.0.0-SNAPSHOT.1755394070476",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",