Skip to content

npm-scripts.md

Latest commit

 

History

History
105 lines (84 loc) · 21.9 KB

npm-scripts.md

File metadata and controls

105 lines (84 loc) · 21.9 KB

NPM Scripts Catalog (POWERBACK)

This document catalogues all npm run scripts in this repo, across:

  • Root: package.json (server / backend / tooling)
  • Client: client/package.json (React frontend)

It also flags scripts that appear broken, platform-specific, or redundant, based on whether referenced files exist in the repository workspace.

How to run scripts

  • Root scripts (default):
    • npm run <script>
  • Client scripts:
    • npm run <script> --prefix client
    • or cd client && npm run <script>

Root scripts (/package.json)

Script Command What it's for Notes / prerequisites Status
test jest --runInBand Run Jest suite (backend __tests__/ + client client/src/__tests__/) Uses jest.config.js, test/setup.js (in-memory MongoDB), __mocks__/; excludes tests-examples/, client/src/App.test.js. See Testing Strategy. Active
test:watch jest --watch --runInBand Watch-mode tests Same config as test Active
test:coverage jest --coverage --runInBand Test coverage Writes coverage/ Active
test:client npm test --prefix client Run client tests Delegates to client package (CRA/CRACO Jest) Active
test:all npm run test && npm run test:client Run root Jest suite then client suite Backend + client; two separate runs Active
build tsc --project tsconfig.json && tsc-alias -p tsconfig.json Compile backend TypeScript and rewrite path aliases Requires tsconfig.json + tsc-alias config Active
dev npm run validate:env && concurrently "nodemon --ignore 'client/*'" "npm run client" "npm run start:watchers" "npm run stripe:listen" Local dev: backend auto-reload + client + watchers + Stripe CLI forwarding Requires stripe CLI installed + logged in Active
dev:all concurrently "npm run dev" "npm run client" "npm run start:watchers" Alternate dev runner Removed – superseded by dev; previously duplicated work and could double-start client/watchers Removed
client npm start --prefix client Start the React dev server Delegates to client's start Active
start:watchers node jobs/runWatchers.js Run/schedule backend watcher jobs Uses node-cron; logs watchers start Active
stripe:listen stripe listen --forward-to localhost:3000/api/webhooks/stripe Forward Stripe webhook events to local API API route exists at POST /api/webhooks/stripe Active (requires Stripe CLI)
lint eslint . --ext .js,.jsx,.ts,.tsx Lint JS/TS across repo Assumes ESLint config is set up Active
lint:fix eslint . --ext .js,.jsx,.ts,.tsx --fix Auto-fix lint where possible Might rewrite many files Active
clean node scripts/clean.js Remove build artifacts/caches in root + client/ Cross-platform; uses rimraf. See scripts/README.md. Active
clean:client:build rimraf build dist out .next .nuxt .cache .parcel-cache ... Delete a wide set of common build/cache directories Removed – overlapped with clean and was unused Removed
clean:client npm run clean:client:build --prefix client Intended: clean the client build output Removed – referenced a non-existent client script and is no longer needed Removed
validate:env node scripts/validate-environment.js Validate environment variables/config Used by dev and by smoke. See scripts/README.md. Active
smoke bash scripts/deploy/smoke.sh Smoke checks: validate env, lint, backend/client tests, build Options: --no-build, --no-lint, etc. See scripts/deploy/smoke.sh --help. Active
smoke:fast bash scripts/deploy/smoke.sh --no-build Smoke without backend build Same as smoke with --no-build Active
smoke:e2e bash scripts/deploy/smoke.sh --e2e Smoke plus Playwright E2E tests Requires Playwright installed and browsers. Active
env:switch node dev/env-manager.js switch Switch environment presets Removed – script referenced missing dev/env-manager.js Removed
env:status node dev/env-manager.js status Show current environment status Removed – script referenced missing dev/env-manager.js Removed
deploy powershell -ExecutionPolicy Bypass -File dev/deploy-enhanced.ps1 Deployment helper Removed – script referenced missing PowerShell helper and was platform-specific Removed
deploy:dry powershell -ExecutionPolicy Bypass -File dev/deploy-enhanced.ps1 -DryRun Deployment dry-run Removed – script referenced missing PowerShell helper and was platform-specific Removed
github:commit powershell -ExecutionPolicy Bypass -File dev/github-safe-commit.ps1 Safe Git commit helper Removed – script referenced missing PowerShell helper and was unused Removed
github:commit:dry powershell -ExecutionPolicy Bypass -File dev/github-safe-commit.ps1 -DryRun Dry-run safe commit Removed – script referenced missing PowerShell helper and was unused Removed
worktree:list powershell -ExecutionPolicy Bypass -File dev/git-worktree-manager.ps1 -Action list Manage git worktrees Removed – script referenced missing PowerShell helper Removed
worktree:create powershell -ExecutionPolicy Bypass -File dev/git-worktree-manager.ps1 -Action create Create worktree Removed – script referenced missing PowerShell helper Removed
worktree:remove powershell -ExecutionPolicy Bypass -File dev/git-worktree-manager.ps1 -Action remove -WorktreeName Remove worktree Removed – script referenced missing PowerShell helper Removed
worktree:clean powershell -ExecutionPolicy Bypass -File dev/git-worktree-manager.ps1 -Action clean Cleanup worktrees Removed – script referenced missing PowerShell helper Removed
test:stripe (not an npm script) Validate server Stripe config (local sanity) Run manually: node scripts/tests/test-stripe-api.js. See scripts/README.md. Manual
test:client-stripe (not an npm script) Validate client Stripe config Run manually: node scripts/tests/test-stripe-client.js. See scripts/README.md. Manual
setup:dev node dev/setup-development-env.js Bootstrap local dev env Removed – script referenced missing setup helper Removed
setup:remote-dev node dev/setup-remote-dev-env.js Bootstrap remote dev env File exists: dev/setup-remote-dev-env.js Active

Client scripts (/client/package.json)

Script Command What it's for Notes / prerequisites Status
start craco start Start React dev server (CRA + CRACO) Uses craco.config.js Active
build craco build && compress-cra -d ./build Build the React app and compress build output compress-cra runs after build Active
prebuild node ../scripts/build/build-content.js && node ../scripts/build/build-breakpoints-css.js Build FAQ outputs + breakpoints CSS See FAQ content sync and scripts/README.md. Active
prestart node ../scripts/build/build-breakpoints-css.js Generate breakpoints CSS before start Ensures client/src/breakpoints.css is current from breakpoints.js. Active
test craco test Run client tests CRA/Jest runner via CRACO Active
analyze source-map-explorer 'build/static/js/*.js' Bundle analysis on an existing build Requires npm run build first Active (manual)
eject react-scripts eject Eject CRA config One-way operation; usually avoid Active (but discouraged)
css:audit node scripts/css-audit.mjs --out reports/css-audit.json Audit CSS and write a report Removed – script referenced missing client/scripts/css-audit.mjs Removed
lint:css stylelint "src/**/*.css" Lint client CSS Requires Stylelint config in repo Active
lint:css:fix stylelint "src/**/*.css" --fix Auto-fix client CSS lint Will rewrite CSS files Active

FAQ content sync (prebuild)

Sync is one-way only. The source of truth is client/src/tuples/faq.js.

  • Tuple → outputs: Running prebuild (e.g. via npm run build in client) reads the tuple and overwrites:
    • the FAQ JSON-LD block in client/public/index.html
    • docs/FAQ.md
  • Doc or index.html → tuple: Editing docs/FAQ.md or client/public/index.html does not update the tuple. There is no reverse sync. To change FAQ content, edit the tuple and run a client build (or node ../scripts/build/build-content.js from client).
  • Hyperlinks: The tuple uses HTML (<a href="...">text</a>). The build script converts those for each output:
    • Markdown (FAQ.md): <a href="url">text</a> → [text](url)
    • JSON-LD (index.html): HTML is stripped to plain text; links become text (url) so the schema stays free of markup.

Tests: Jest vs scripts/tests

  • Jest suite (npm test, npm run test:client, etc.): Automated tests in __tests__/ and client/src/__tests__/. Config and conventions: Testing Strategy and .cursor/rules/11-testing.mdc.
  • Development utility tests (scripts/tests/): Manual scripts to exercise Stripe config, donation limits, email templates, donor validation, social webhooks, etc. They are not part of the Jest run. Run from project root with node scripts/tests/<name>.js. Full list and usage: scripts/README.md.

Related Documentation