Frontend node modernization / Beige Screen fix

.github/workflows/frontend.yml

@@ -39,23 +39,24 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 14
+          node-version-file: frontend/.nvmrc
           cache: npm
           cache-dependency-path: frontend/package-lock.json
       - uses: browser-actions/setup-chrome@v2
         id: setup-chrome
-      - run: npm install -g npm@6.14.18
-      - run: npm install
+      - run: npm ci
         working-directory: ./frontend
       - run: npm run test
         working-directory: ./frontend
         env:
           CHROME_BIN: ${{ steps.setup-chrome.outputs.chrome-path }}
 
   node-next-test:
+    # Guards the `engines: node >= 18` range in frontend/package.json. The
+    # version in frontend/.nvmrc is covered by test-app above.
     strategy:
       matrix:
-        node_version: ['16', '18', '20']
+        node_version: ['18', '20', '24']
     needs: changes
     if: ${{ needs.changes.outputs.frontend == 'true' }}
     runs-on: ubuntu-latest
@@ -65,9 +66,11 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node_version }}
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
       - uses: browser-actions/setup-chrome@v2
         id: setup-chrome
-      - run: npm install
+      - run: npm ci
         working-directory: ./frontend
       - run: npm run test
         working-directory: ./frontend

.tool-versions

@@ -1,4 +1,4 @@
-nodejs 12.22.6
+nodejs 22.23.2
 ruby 3.2.3
 postgres 12.8
 mongodb 4.4.9

CLAUDE.md

@@ -66,5 +66,6 @@ Heroku, via `rake` tasks in the root `Rakefile`. Frontend and backend are separa
 
 ## Gotchas
 
-- Node is pinned to **12.22.6** for the Ember frontend (`.tool-versions`); the native app uses a modern toolchain independently. Don't assume one Node version across the repo.
-- Env files: `cp backend/env-example backend/.env` and `cp backend/env-example frontend/.env`. A `FACEBOOK_APP_ID` is needed in `frontend/.env` or the app renders a blank beige screen on first load (see README "Common Problems" for the workaround).
+- The Ember frontend requires **Node >= 18** (`engines` in `frontend/package.json`, enforced by `engine-strict=true` in `frontend/.npmrc`). `frontend/.nvmrc` pins the version CI builds against; `nvm install` or `asdf install` in `frontend/` picks it up. The build does not work on Node 16 or older, so switch versions rather than bypassing the engine check.
+- `frontend/npm install` needs no `sudo`, `--unsafe-perm` or `--allow-root`, as root or otherwise. If you are tempted to add one, something else is wrong.
+- Env files: `cp backend/env-example backend/.env` and `cp frontend/env-example frontend/.env`. They are read independently — Rails reads `backend/.env`, and `frontend/config/environment.js` loads `frontend/.env` itself (at the top of the file, deliberately: ember-cli evaluates that file before addon config hooks run, so loading `.env` via an addon silently drops the values on a cold build). `FACEBOOK_APP_ID` is only needed for Facebook login.

README.md

@@ -14,7 +14,7 @@ Help would be appreciated! Please join us in [slack #flaredown](https://join.sla
 * MongoDB 4.4.9
 * Redis 6.2.3
 * Ruby 3.2.3
-* Node 12.22.6
+* Node 22 (the frontend supports Node 18 and newer; `frontend/.nvmrc` pins the version CI builds against)
 
 ## Installation
 
@@ -92,11 +92,29 @@ gem install foreman
 
 #### Frontend
 
+The Ember app needs Node 18 or newer. `frontend/.nvmrc` and `frontend/.tool-versions` pin the
+version CI builds against, so if you use [nvm](https://github.com/nvm-sh/nvm) or
+[asdf-vm](https://asdf-vm.com/) you can let them pick it for you.
+
 ```bash
 cd frontend
+nvm install              # or: asdf install — optional, any Node >= 18 works
+cp env-example .env      # FACEBOOK_APP_ID is only needed for Facebook login
 npm install
+npm run dev
 ```
 
+Visit [http://localhost:4300](http://localhost:4300). `npm run dev` serves the app on its own; API
+calls are proxied to the backend on port 3000, so start the backend too if you need data.
+
+`npm install` also applies our patches and installs the remaining Bower packages via the
+`postinstall` script — no extra commands, and no `sudo`/`--unsafe-perm`, including in containers
+that run as root.
+
+If `npm install` stops with `EBADENGINE ... Required: {"node":">=18"}`, you are on an older Node.
+That check is deliberate (`engine-strict=true` in `frontend/.npmrc`) — switch versions rather than
+bypassing it, since the build does not work on Node 16 or older.
+
 #### React Native
 
 ```bash
@@ -109,8 +127,9 @@ npm install
 ### Prerequisites
 
 - Populate the necessary environment parameters with `cp backend/env-example backend/.env && cp frontend/env-example frontend/.env`
+    - The two files are read independently: the Rails app reads `backend/.env`, and the Ember build reads `frontend/.env`.
 - Create a [Facebook dev app](https://developers.facebook.com/docs/development/create-an-app) and paste your own ID into `frontend/.env` file's `FACEBOOK_APP_ID` parameter.
-    - Note: This is not necessary in `backend/.env` but we have not yet cleaned up these two files into the necessary components.
+    - Only needed for Facebook login; the rest of the app runs without it.
 - Reset, migrate, load fixtures, and seed your database using `make seed` or `bundle exec rails app:setup`
 
 ### Running
@@ -149,7 +168,7 @@ Addons are used for Heroku Postgres, Heroku Redis, Heroku Scheduler + Papertrail
 ### 🎨 [Figma Assets](https://www.figma.com/proto/MBVn73pD6JbBkxd65KSZHr/Flaredown-Guide?page-id=0%3A1&node-id=1%3A3&viewport=241%2C48%2C0.45&scaling=contain&starting-point-node-id=1%3A3)
 
 ## Common Problems
-* On first load, the app displays a blank beige screen instead of the login screen. Temporary fix is to add  `console.log(process.env.FACEBOOK_APP_ID)` right inside of the module.exports at the top of the `frontend/config/environment.js` file. You can then refresh the page (no need to kill Docker) and this should fix it. You can now remove the log.
+*  If you still hit a blank screen on first load, check that `frontend/.env` exists (`cp frontend/env-example frontend/.env`).
 
 ## License
 Copyright 2015-2024 Logan Merriam and contributors.

frontend/.bowerrc

@@ -1,4 +1,5 @@
 {
   "directory": "bower_components",
-  "analytics": false
+  "analytics": false,
+  "allow_root": true
 }

frontend/.nvmrc

@@ -1 +1 @@
-v14.21.3
+22

frontend/.tool-versions

@@ -1 +1 @@
-nodejs 14.21.3
+nodejs 22.23.2

frontend/Dockerfile

@@ -1,27 +1,24 @@
-FROM node:14.21.3-bullseye
+FROM node:22-bookworm
 
 WORKDIR /app
 
 RUN apt-get update -qq && \
       apt-get install -y --no-install-recommends chromium && \
       rm -rf /var/lib/apt/lists/*
 
-RUN npm i -g npm@6.14.18
-
 COPY bin/docker-entrypoint /usr/local/bin/frontend-entrypoint
 
 RUN chmod +x /usr/local/bin/frontend-entrypoint && \
       chown -R node:node /app
 
 ENV CHROME_BIN=/usr/bin/chromium
-ENV OPENSSL_CONF=/dev/null
 
 USER node
 
 COPY --chown=node:node package*.json bower.json .bowerrc .npmrc ./
 COPY --chown=node:node patches ./patches
 
-RUN npm install && \
+RUN npm ci && \
       { \
         for file in package.json package-lock.json bower.json .bowerrc .npmrc; do \
           [ -f "$file" ] && sha256sum "$file"; \

frontend/README.md

@@ -1,59 +1,84 @@
-# Flaredown
+# Flaredown web app
 
-This README outlines the details of collaborating on this Ember application.
-A short introduction of this app could easily go here.
+The Ember.js client for Flaredown, served at app.flaredown.com. It talks to the Rails API in
+`backend/`; there is no separate frontend server in development.
 
 ## Prerequisites
 
-You will need the following things properly installed on your computer.
-
 * [Git](http://git-scm.com/)
-* [Node.js](http://nodejs.org/) (with NPM)
-* [Bower](http://bower.io/)
-* [Ember CLI](http://ember-cli.com/)
-* [Google Chrome](https://google.com/chrome/)
+* Node 18 or newer. `.nvmrc` and `.tool-versions` pin the version CI builds against, so
+  `nvm install` or `asdf install` will pick it up automatically.
+* [Google Chrome](https://google.com/chrome/) or Chromium, to run the test suite.
+
+You do not need a global `ember-cli` or `bower` install — both come from `npm install`, and the
+local binaries live in `node_modules/.bin`.
 
 ## Installation
 
-* `git clone <repository-url>` this repository
-* `cd flaredown`
-* `npm install`
-* `bower install`
+```bash
+cd frontend
+nvm install            # optional; any Node >= 18 works
+cp env-example .env
+npm install
+```
+
+`npm install` runs a `postinstall` script that applies our patches (`patch-package`) and installs
+the remaining Bower packages.
+
+Prefer `npm ci` when you want an install that exactly matches `package-lock.json`, such as in CI or
+a fresh container.
 
-## Running / Development
+## Running
 
-* `ember serve`
+```bash
+npm run dev
+```
 
-* Visit your app at [http://localhost:4300](http://localhost:4300).
-* Visit your tests at [http://localhost:4300/tests](http://localhost:4300/tests).
+* App: [http://localhost:4300](http://localhost:4300)
+* Tests in the browser: [http://localhost:4300/tests](http://localhost:4300/tests)
 
-## Running / Development via Fastboot server
+API requests are proxied to `http://localhost:3000`, so run the backend as well if you need data.
+From the repository root, `rake run` starts the backend and this app together.
 
-* DIST=tmp/deploy-dist PORT=$PORT node fastboot-server.js
+## Configuration
 
-### Code Generators
+`config/environment.js` reads `frontend/.env` (see `env-example` for the full list):
 
-Make use of the many generators for code, try `ember help generate` for more details
+| Variable | Purpose |
+| --- | --- |
+| `PORT` | Port the backend API is listening on. Defaults to 3000. |
+| `FRONTEND_PORT` | Port this app is served from. Defaults to 4300. |
+| `FACEBOOK_APP_ID` | Facebook login. Only required if you are working on that flow. |
+| `PUSHER_KEY` | Realtime updates. |
+| `RECAPTCHA_SITE_KEY` | Signup captcha. `env-example` ships with Google's public test key. |
 
-### Running Tests
+## Testing and linting
 
-* `ember test`
-* `ember test --server`
+```bash
+npm test               # ember test, needs Chrome
+npm run lint:js        # eslint
+```
 
-### Building
+Set `CHROME_BIN` if Chrome is not on the default path, e.g. `CHROME_BIN=$(which chromium) npm test`.
 
-* `ember build` (development)
-* `ember build --environment production` (production)
+## Building
 
-### Deploying
+```bash
+npm run build          # production build into dist/
+npm start              # serve a built dist/ (used on Heroku)
+```
 
-Specify what it takes to deploy your app.
+## Dependencies
 
-## Further Reading / Useful Links
+Most dependencies are npm packages. Three remain in `bower.json` — `pace`, `pickadate` and `At.js`
+— because the addons that consume them (`ember-cli-pickadate`, `ember-at-js`) import from
+`bowerDirectory`. Moving those to npm means patching those addons, which has not been done yet.
+
+Patches to third-party packages live in `patches/` and are applied by `patch-package` on install.
+To add one, edit the package under `node_modules/`, then run `npx patch-package <package-name>`.
+
+## Further reading
 
 * [ember.js](https://emberjs.com/)
 * [ember-cli](https://ember-cli.com/)
-
-* Development Browser Extensions
-  * [ember inspector for chrome](https://chrome.google.com/webstore/detail/ember-inspector/bmdblncegkenkacieihfhpjfppoconhi)
-  * [ember inspector for firefox](https://addons.mozilla.org/en-US/firefox/addon/ember-inspector/)
+* [Ember Inspector for Chrome](https://chrome.google.com/webstore/detail/ember-inspector/bmdblncegkenkacieihfhpjfppoconhi)

frontend/config/environment.js

@@ -1,5 +1,14 @@
 'use strict';
 
+var path = require('path');
+
+// Load frontend/.env before the config below reads process.env. This has to
+// happen here rather than through an addon: ember-cli evaluates this file
+// before addon config hooks run, so on a cold build process.env would still be
+// empty and FACEBOOK_APP_ID, PUSHER_KEY and RECAPTCHA_SITE_KEY would silently
+// drop out of the built config.
+require('dotenv').config({ path: path.join(__dirname, '..', '.env') });
+
 module.exports = function(environment) {
   var ENV = {
     rootURL: '/',
@@ -57,14 +66,16 @@ module.exports = function(environment) {
     }
   };
 
+  var STATIC_URL;
+
   if (environment === 'development') {
     // ENV.APP.LOG_RESOLVER = true;
     // ENV.APP.LOG_ACTIVE_GENERATION = true;
     // ENV.APP.LOG_TRANSITIONS = true;
     // ENV.APP.LOG_TRANSITIONS_INTERNAL = true;
     // ENV.APP.LOG_VIEW_LOOKUPS = true;
-    ENV.apiHost    = 'http://localhost:' + (process.env.PORT || '3000');
-    var STATIC_URL = 'http://localhost:' + (process.env.FRONTEND_PORT || '4300');
+    ENV.apiHost = 'http://localhost:' + (process.env.PORT || '3000');
+    STATIC_URL = 'http://localhost:' + (process.env.FRONTEND_PORT || '4300');
   }
 
   if (environment === 'test') {
@@ -78,7 +89,7 @@ module.exports = function(environment) {
     ENV.APP.rootElement = '#ember-testing';
     ENV.APP.autoboot = false;
     ENV.apiHost = 'http://localhost:3000';
-    var STATIC_URL = 'http://localhost:4300';
+    STATIC_URL = 'http://localhost:4300';
   }
 
   if (environment === 'production') {
@@ -87,7 +98,7 @@ module.exports = function(environment) {
     };
 
     ENV.apiHost = process.env.API_HOST;
-    var STATIC_URL = process.env.STATIC_URL;
+    STATIC_URL = process.env.STATIC_URL;
   }
 
   ENV.staticUrl = STATIC_URL;

frontend/ember-cli-build.js

@@ -13,12 +13,6 @@ module.exports = function(defaults) {
 
     'ember-cli-babel': {},
 
-    dotEnv: {
-      path: {
-        development: '../backend/.env',
-      }
-    },
-
     sassOptions: {
       includePaths: [
         'node_modules/bourbon/core',