Commands Reference

This page explains every command you need to run the AquaGen app — starting with the npm scripts defined in package.json, then the handful of Nx commands used for testing, linting and inspecting the workspace.

New to the project? Read the npm Scripts section top to bottom — that is 90% of what you will use.

npm Scripts

These are the scripts defined in package.json. Run them with npm run <name> (the one exception is npm start, which does not need run).

Script	What it runs	Use it to…
`npm start`	`nx serve production`	Start the app locally for daily development
`npm run start:app`	`nx serve`	Start a specific app locally
`npm run build`	`nx build production --skip-nx-cache`	Build the production app for release
`npm run build:app`	`nx build --skip-nx-cache`	Build a specific app
`npm run serve:build`	`bash-scripts/run-build.sh`	Preview a finished build locally
`npm run create:app`	`bash-scripts/duplicate-production.sh`	Create a new app by cloning `production`
`npm run create:lib`	`bash-scripts/create-lib.sh`	Create a new feature library
`npm run integrate:lib`	`bash-scripts/integrate-lib.sh`	Wire an existing library into apps
`npm run deploy`	`bash-scripts/deploy.sh`	Guided deploy (menu-driven) — the usual way
`npm run deploy:app`	`bash-scripts/deploy-app.sh`	Deploy one app to one Firebase target (manual)

tip

The apps in this repo are production, demo, lakepulse, uwms, and rwi. Wherever a command below says <app-name>, use one of these.

Running the app locally

`npm start`

npm start

Runs nx serve production — starts the main production app on a local dev server (Rspack) with hot reload. Open the URL it prints (usually http://localhost:4200) in your browser. This is the command you will use most.

When to use: everyday development on the main app.

`npm run start:app`

Runs nx serve for a specific app. Pass the app name as an argument:

npm run start:app demo        # start the demo app
npm run start:app lakepulse   # start the Lake Pulse app

Equivalent to running nx serve <app-name> directly.

When to use: working on any app other than production.

Building

`npm run build`

npm run build

Runs nx build production --skip-nx-cache — produces an optimized, minified production build in dist/apps/production/. --skip-nx-cache forces a fresh build so you never ship stale cached output.

When to use: before releasing the production app.

`npm run build:app`

Builds a specific app. Pass the app name as an argument:

npm run build:app demo
npm run build:app lakepulse

Output goes to dist/apps/<app-name>/. Equivalent to nx build <app-name> --skip-nx-cache.

When to use: building any app other than production.

`npm run serve:build`

Serves an already-built app so you can preview the real production output before deploying. Pass the app name; the script serves dist/apps/<app-name>/ on port 3000 using npx serve.

# build first, then preview it
npm run build:app demo
npm run serve:build demo      # → http://localhost:3000

note

This serves a finished build, not a live dev server — there is no hot reload. If nothing shows up, build the app first.

When to use: sanity-checking a build locally before deploying.

Scaffolding apps & libraries

`npm run create:app`

Creates a brand-new app by cloning the production app. Pass the new app name as an argument:

npm run create:app staging

What it does:

Copies apps/production → apps/<new-name> (and the matching -e2e folder)
Rewrites every production reference inside the copied files to the new name (handles lower/UPPER/Capitalized/kebab-case variants)

After it finishes, review the generated files and run nx serve <new-name> to try it. You may also need to register the app in nx.json.

When to use: standing up a new product/client variant of the app.

`npm run create:lib`

Creates a new feature library under libs/. Pass the library name as an argument:

npm run create:lib my-feature

What it does:

Generates the library with nx g @nx/react:lib libs/my-feature --js
Clears the default src/ and creates the standard folders: components/, controller/, dataSource/, store/, enum/
Creates an entry page named after the lib, e.g. MyFeaturePage.jsx
Automatically runs integrate:lib afterwards so you can wire it into apps right away

Result:

libs/my-feature/
├── src/
│   ├── components/
│   ├── controller/
│   ├── dataSource/
│   ├── store/
│   ├── enum/
│   └── MyFeaturePage.jsx
├── project.json
└── tsconfig.json

When to use: starting a new feature module.

`npm run integrate:lib`

Wires an existing library into one or more apps. Pass the library name:

npm run integrate:lib my-feature

It shows an interactive menu of available apps (pick one, several like 1 2, or all). For each selected app it:

Adds an import alias @aquagen-mf-webapp/my-feature to apps/<app>/rspack.config.js
Adds the matching path to apps/<app>/tsconfig.json

It is safe to re-run — it skips apps that already have the library configured. It does not touch your routes; add the route yourself after integrating.

When to use: making a library importable from an app (e.g. after creating it, or adding it to another app later).

Deploying

`npm run deploy` (recommended)

The guided deployment script. Run it with no arguments and follow the menu:

npm run deploy

It walks you through:

Pick an app — Aquagen (production), Lake Pulse, Aqua Recycle (uwms), RWI, Demo, or All
Pick an environment — dev or prod (where the app supports it)
Confirm the summary before anything runs

Then, for each selected app, it automatically:

Sets the right build flags in libs/shared/src/constants/constants.js (analyticsEnv, currentEnv, isPreProd)
Builds the app (nx build <app> --skip-nx-cache)
Points firebase.json at the fresh build and runs firebase deploy --only hosting:<target>
Reverts the constants and restores firebase.json when done — so your working copy is left clean even if a deploy fails

note

Aquagen only supports dev deployment; Demo only supports its prod target. The menu enforces this for you.

When to use: almost always — this is the normal way to deploy.

`npm run deploy:app` (manual)

Deploys one app to one Firebase hosting target, with no menus. You supply both names as arguments:

npm run deploy:app <app-name> <hosting-target>
# example:
npm run deploy:app demo demo

What it does:

Requires the build to already exist in dist/apps/<app-name>/ (run npm run build:app <app-name> first)
Backs up firebase.json, points its public path at the build, runs firebase deploy --only hosting:<hosting-target>, then restores firebase.json

Unlike deploy, it does not build for you and does not adjust the environment constants — you are fully in control.

Prerequisites: Firebase CLI installed (npm i -g firebase-tools), logged in (firebase login), and the target defined in firebase.json.

When to use: one-off or scripted deploys where you want manual control.

Typical manual flow:

npm run build:app demo        # 1. build
npm run serve:build demo      # 2. preview at http://localhost:3000
npm run deploy:app demo demo  # 3. deploy

Local environment & backend switching

npm start talks to the PRODUCTION backend by default

libs/shared/src/constants/constants.js ships with:

constants.currentEnv = constants.env.prod;   // line 20

So a fresh checkout running npm start calls the production API. To develop against another backend you must change this yourself.

Edit libs/shared/src/constants/constants.js and set currentEnv to one of constants.env.{prod | dev | local | ngrok | demo}:

constants.currentEnv = constants.env.dev;    // use the dev backend
// or constants.env.local  → your local API

currentEnv selects the main API base URL (in libs/shared/src/services/api/urls.js):

`currentEnv`	Main API base URL
`prod`	`https://prod-aquagen.azurewebsites.net/api/user/`
`dev`	`https://dev2-aquagenapi.azurewebsites.net/api/user/`
`local`	`http://localhost:5001/api/user/`
`demo`	`https://aqua-demo-...azurewebsites.net/api/user/`

Two related flags switch independently (also in constants.js):

aiAgentEnv — AquaGPT/AI backend (prod → Azure, local → http://localhost:8000/api)
azureAdEnv — auth redirect URI (local → http://localhost:4200/)

Don't commit local env changes

Leave the committed default at prod. The deploy scripts set these flags automatically at deploy time (see Deployment), so a committed dev/local value would ship to the wrong backend. Revert constants.js before you push.

Debug flags

Also in constants.js, flip these to true to trace API traffic in the browser console (all default false):

Flag	Shows
`logRequest`	outgoing request payloads
`logResponse`	responses
`logCURL`	each call as a copy-pasteable cURL command

See Validation & Troubleshooting for how to use these when something breaks.

Nx Commands (used, but not in package.json)

There are no test, lint, or format scripts in package.json — those tasks run through Nx directly. These are the ones you will actually use.

Testing

# Unit tests for one project (lib or app)
nx test dashboard
nx test shared

# Watch mode while developing
nx test dashboard --watch

# End-to-end tests
nx e2e production-e2e

# Run tests across every project
nx run-many --target=test --all

Linting

# Lint one project
nx lint production

# Auto-fix what can be fixed
nx lint production --fix

# Lint everything
nx run-many --target=lint --all

Inspecting the workspace

nx graph                 # open the interactive dependency graph
nx show projects         # list every app and library
nx show project dashboard  # config + targets for one project

When things act up

nx reset                 # clear the Nx cache (fixes most "stale build" weirdness)

Run nx reset if you hit strange build errors after pulling changes, switching branches, or updating dependencies.

tip

You can drop the npx prefix if Nx is installed — these examples assume the local nx (via npx nx ... works too).

Quick Reference

I want to…	Command
Start the main app	`npm start`
Start another app	`npm run start:app <app-name>`
Build production	`npm run build`
Build another app	`npm run build:app <app-name>`
Preview a build	`npm run serve:build <app-name>`
Create a new library	`npm run create:lib <name>`
Add a library to apps	`npm run integrate:lib <name>`
Create a new app	`npm run create:app <name>`
Deploy (guided)	`npm run deploy`
Deploy one app manually	`npm run deploy:app <app-name> <target>`
Run tests	`nx test <project>`
Lint	`nx lint <project>`
See project graph	`nx graph`
Clear cache	`nx reset`

Next Steps

Components — the shared UI building blocks
Utilities — shared helpers and services
Deployment — environments and hosting targets in depth
Validation & Troubleshooting — smoke tests and a down-time runbook

npm Scripts​

Running the app locally​

npm start​

npm run start:app​

Building​

npm run build​

npm run build:app​

npm run serve:build​

Scaffolding apps & libraries​

npm run create:app​

npm run create:lib​

npm run integrate:lib​

Deploying​

npm run deploy (recommended)​

npm run deploy:app (manual)​

Local environment & backend switching​

Debug flags​

Nx Commands (used, but not in package.json)​

Testing​

Linting​

Inspecting the workspace​

When things act up​

Quick Reference​

Next Steps​

npm Scripts

Running the app locally

`npm start`

`npm run start:app`

Building

`npm run build`

`npm run build:app`

`npm run serve:build`

Scaffolding apps & libraries

`npm run create:app`

`npm run create:lib`

`npm run integrate:lib`

Deploying

`npm run deploy` (recommended)

`npm run deploy:app` (manual)

Local environment & backend switching

Debug flags

Nx Commands (used, but not in package.json)

Testing

Linting

Inspecting the workspace

When things act up

Quick Reference

Next Steps