miracles_in_motion/docs/QuickStart.md

Quick Start Guide

Fast path to get the Miracles in Motion project running, tested, and deployed.

1. Prerequisites

Tool	Recommended Version	Notes
Node.js	20.x / 22.x	Functions runtime Standard supports node:20; local dev can use 22
npm	10+	Bundled with recent Node
Azure CLI	>= 2.60	For infra & Static Web Apps commands
SWA CLI (@azure/static-web-apps-cli)	latest	Local API + front-end emulation
Git	latest	Source control
WSL2	Enabled	Shell environment (Ubuntu recommended)

# Verify versions
node -v
npm -v
az version

2. Clone & Install

git clone https://github.com/Miracles-In-Motion/public-web.git
cd public-web
npm install --legacy-peer-deps
cd api && npm install --legacy-peer-deps && cd ..

3. Environment Setup

Create a .env.local (frontend) and api/local.settings.json (Azure Functions) as needed.

Example .env.local (do NOT commit secrets):

VITE_API_BASE=/api
VITE_STRIPE_PUBLISHABLE_KEY=pk_test_xxx
VITE_DEFAULT_LANGUAGE=en
VITE_SUPPORTED_LANGUAGES=en,es,fr,de,zh,ar,pt,ru

Example api/local.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node"
  }
}

4. Run Locally (Integrated)

Use SWA CLI to serve front-end + Functions together.

npm run build:api       # Optional: compile API TypeScript
swa start http://localhost:5173 --api-location ./api --devserver-run-command "npm run dev" --api-language node

If you prefer two terminals:

npm run dev            # Front-end (Vite)
cd api && npm start   # Functions runtime

5. Testing

npm test                 # Front-end tests (Vitest / Testing Library)

Add more tests under src/components/__tests__/ or src/test.

6. Build

npm run build            # Produces front-end dist/
cd api && npm run build  # Compiles Functions to dist (if configured)

7. Azure Deployment (Static Web App Standard)

# Login
az login

# Ensure resource group exists
az group create --name rg-mim-prod --location eastus2

# Create Static Web App (front-end + managed functions)
az staticwebapp create \
  --name mim-prod-web-standard \
  --resource-group rg-mim-prod \
  --location eastus2 \
  --source . \
  --branch main \
  --app-location / \
  --output-location dist

To deploy updates without GitHub Actions (manual token):

TOKEN=$(az staticwebapp secrets list --name mim-prod-web-standard --resource-group rg-mim-prod --query properties.apiKey -o tsv)
swa deploy ./dist --env production --deployment-token $TOKEN

8. Custom Domain

1. Add CNAME www → <defaultHostname>.
2. Set hostname:

az staticwebapp hostname set \
  --name mim-prod-web-standard \
  --resource-group rg-mim-prod \
  --hostname miraclesinmotion.org

Azure provisions SSL automatically.

9. Configuration (staticwebapp.config.json)

Key elements:

• navigationFallback ensures SPA routing.
• globalHeaders for security (CSP, HSTS). Adjust Content-Security-Policy as integrations evolve.

10. Useful Scripts

Script	Purpose
npm run dev	Start Vite dev server
npm test	Run tests
npm run build	Build front-end
npm run analyze	(If defined) Bundle analysis

11. Troubleshooting

Issue	Resolution
404 on portal route	Ensure hash routing /#/portals or SPA fallback set
Functions 500 error	Check api logs, run locally with func start if using standalone Functions
CSP blocking script	Update CSP in staticwebapp.config.json to allow required domain
Node version mismatch	Use Node 20 for SWA managed functions, 22 locally if desired

12. Next Steps

• Configure GitHub Actions for CI/CD.
• Add monitoring (Application Insights) if using standalone Functions.
• Replace test Stripe keys with live keys in production.

---

Last updated: 2025-11-11