From 56c846a44b3f51e6aa2b45d247b266fa400b25f7 Mon Sep 17 00:00:00 2001 From: Claude Code Date: Mon, 7 Jul 2025 20:36:58 -0400 Subject: [PATCH] Update documentation for TypeScript frontend build system MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: Add comprehensive build system section explaining TypeScript backend/frontend compilation, esbuild usage, and development commands - CLAUDE.md: Update architecture documentation to reflect TypeScript frontend with shared components and esbuild compilation - scripts/deploy.sh: Update deployment instructions to use new unified build command 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 84 ++++++++++++++++++++++++++++++++--------------- README.md | 56 ++++++++++++++++++++++--------- scripts/deploy.sh | 2 +- 3 files changed, 98 insertions(+), 44 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ae66fb2..2ce4ec7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,14 +9,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co # Install dependencies npm install -# Start the server (production mode - TypeScript) +# Start the server (production mode - builds everything) npm start # Development mode options: -npm run dev # TypeScript development with auto-reload +npm run dev:ts # TypeScript backend development with auto-reload npm run dev:js # Legacy JavaScript development mode -npm run dev-with-css:ts # TypeScript + CSS watching (recommended) -npm run dev-with-css # Legacy JS + CSS watching +npm run dev-with-css:ts # TypeScript backend + CSS watching +npm run dev:full # Full development: TypeScript backend + frontend + CSS (recommended) +npm run dev-with-css # Legacy JS + CSS watching ``` The application runs on port 3000 by default. Visit http://localhost:3000 to view the website. @@ -33,18 +34,32 @@ The documentation includes: - Interactive testing interface ### TypeScript Development -The backend is written in TypeScript and compiles to `dist/` directory. -```bash -# Build TypeScript (production) -npm run build:ts +Both backend and frontend are written in TypeScript. -# Build everything (TypeScript + CSS) -npm run build +**Backend TypeScript (Node.js):** +```bash +# Build backend TypeScript to dist/ directory +npm run build:ts # Development with TypeScript watching npm run dev:ts ``` +**Frontend TypeScript (Browser):** +```bash +# Build frontend TypeScript to public/dist/ directory +npm run build:frontend + +# Watch frontend TypeScript for changes +npm run watch:frontend +``` + +**Full Build:** +```bash +# Build everything (backend + frontend + CSS + i18n) +npm run build +``` + ### CSS Development CSS is generated from SCSS and should NOT be committed to git. ```bash @@ -58,6 +73,11 @@ npm run build-css:dev npm run watch-css ``` +**Generated Files (DO NOT COMMIT):** +- `public/style.css` - Compiled CSS from SCSS +- `public/dist/` - Compiled frontend JavaScript from TypeScript +- `dist/` - Compiled backend JavaScript from TypeScript + ### Code Quality ```bash # Run ESLint to check code style and quality @@ -122,6 +142,7 @@ Required environment variables: - Bearer token authentication for admin endpoints - Environment variable configuration via dotenv - Full TypeScript with strict type checking + - Compiled output in `dist/` directory ### Route Architecture Routes are organized as factory functions accepting dependencies with full TypeScript typing: @@ -156,8 +177,8 @@ CREATE TABLE locations ( **Profanity Database (`profanity.db`)**: Managed by the `ProfanityFilter` class for content moderation. -### Frontend (Progressive Web App + Progressive Enhancement) -The application is a full Progressive Web App with offline capabilities and progressive enhancement: +### Frontend (TypeScript + Progressive Web App) +The application is a full Progressive Web App with TypeScript-compiled JavaScript: **PWA Features:** - **public/manifest.json**: Web app manifest for installation @@ -166,16 +187,23 @@ The application is a full Progressive Web App with offline capabilities and prog - **public/offline.html**: Offline fallback page when network is unavailable - **PWA Meta Tags**: Added to all HTML files for proper app behavior -**JavaScript-Enhanced Experience:** -- **public/app.js**: Main implementation using Leaflet.js - - Auto-detects available geocoding services (Mapbox preferred, Nominatim fallback) - - Interactive map with real-time updates - - Autocomplete and form validation - -- **public/app-mapbox.js**: Mapbox GL JS implementation for enhanced features -- **public/app-google.js**: Google Maps implementation (alternative) -- **public/admin.js**: Admin panel functionality -- **public/utils.js**: Shared utilities across implementations +**TypeScript Frontend Architecture:** +- **src/frontend/**: TypeScript frontend source code + - **main.ts**: Main application entry point with Leaflet.js + - **admin.ts**: Admin panel functionality + - **privacy.ts**: Privacy policy page + - **shared/**: Shared components and utilities + - **header.ts**: Shared header component with i18n + - **footer.ts**: Shared footer component +- **public/dist/**: Compiled JavaScript output (via esbuild) + - **app-main.js**: Main application bundle + - **app-admin.js**: Admin panel bundle + - **app-privacy.js**: Privacy page bundle + +**Legacy JavaScript (for reference):** +- **public/app.js**: Legacy main implementation +- **public/admin.js**: Legacy admin functionality +- **public/utils.js**: Legacy shared utilities **Non-JavaScript Fallback:** - **Server-side /table route**: Complete HTML table view of all locations @@ -238,11 +266,13 @@ SCSS files are in `src/scss/`: 5. **Modular Route Architecture**: Routes accept dependencies as parameters for testability 6. **Dual Database Design**: Separate databases for application data and content moderation 7. **Type-Safe Database Operations**: All database interactions use typed models -8. **Comprehensive Testing**: 125+ tests covering units, integration, and security scenarios -9. **Graceful Degradation**: Fallback geocoding providers and error handling -10. **Automated Maintenance**: Cron-based cleanup of expired reports -11. **Accessibility-First**: noscript fallbacks and server-side static map generation -12. **Offline-First Design**: Service worker caching with automatic updates +8. **Frontend TypeScript Compilation**: Modern esbuild-based frontend bundling with TypeScript +9. **Shared Component Architecture**: Reusable TypeScript components across pages +10. **Comprehensive Testing**: 125+ tests covering units, integration, and security scenarios +11. **Graceful Degradation**: Fallback geocoding providers and error handling +12. **Automated Maintenance**: Cron-based cleanup of expired reports +13. **Accessibility-First**: noscript fallbacks and server-side static map generation +14. **Offline-First Design**: Service worker caching with automatic updates ### Deployment - Automated deployment script for Debian 12 (ARM64/x86_64) in `scripts/deploy.sh` diff --git a/README.md b/README.md index 3c49d87..2edca8d 100644 --- a/README.md +++ b/README.md @@ -46,9 +46,10 @@ A community-driven web application for tracking winter road conditions and icy h 4. **Start the server:** ```bash - npm start # Production mode - npm run dev # Development mode - npm run dev-with-css # Development with CSS watching + npm start # Production mode (builds everything) + npm run dev:ts # TypeScript development mode + npm run dev-with-css:ts # TypeScript + CSS watching (recommended) + npm run dev:full # Full development (TypeScript + frontend + CSS) ``` ## Development Commands @@ -76,21 +77,44 @@ npm run test:coverage http://localhost:3000 ``` -### CSS Development +### Build System -This project uses SCSS for styling. The CSS is **generated** and should not be committed to git. +This project uses TypeScript for both backend and frontend code, with SCSS for styling. -- **Build CSS once:** `npm run build-css` -- **Build CSS (dev mode):** `npm run build-css:dev` -- **Watch CSS changes:** `npm run watch-css` -- **Dev with CSS watching:** `npm run dev-with-css` +**Backend (TypeScript → Node.js):** +```bash +npm run build:ts # Compile TypeScript backend +npm run dev:ts # TypeScript development with auto-reload +``` -SCSS files are organized in `src/scss/`: -- `main.scss` - Main entry point -- `_variables.scss` - Theme variables and colors -- `_mixins.scss` - Reusable SCSS mixins -- `pages/` - Page-specific styles -- `components/` - Component-specific styles +**Frontend (TypeScript → Browser JavaScript):** +```bash +npm run build:frontend # Compile frontend TypeScript with esbuild +npm run watch:frontend # Watch frontend TypeScript for changes +``` + +**CSS (SCSS → CSS):** +```bash +npm run build-css # Build CSS once (production) +npm run build-css:dev # Build CSS with source maps +npm run watch-css # Watch SCSS files for changes +``` + +**Development Commands:** +```bash +npm run dev:full # Watch all: TypeScript backend + frontend + CSS +npm run dev-with-css:ts # Watch TypeScript backend + CSS +npm run build # Build everything for production +``` + +**File Organization:** +- `src/` - TypeScript backend code +- `src/frontend/` - TypeScript frontend code (compiled to `public/dist/`) +- `src/scss/` - SCSS stylesheets (compiled to `public/style.css`) +- `dist/` - Compiled backend JavaScript +- `public/dist/` - Compiled frontend JavaScript + +**Note:** Generated files (`dist/`, `public/dist/`, `public/style.css`) should not be committed to git. ## Environment Variables @@ -159,7 +183,7 @@ See `docs/deployment-quickstart.md` for a simplified deployment guide. cd /opt/icewatch sudo chown -R $USER:$USER /opt/icewatch npm install # This automatically builds CSS via postinstall - npm run build:ts # Compile TypeScript to JavaScript + npm run build # Build everything: TypeScript backend + frontend + CSS ``` 3. **Configure environment:** diff --git a/scripts/deploy.sh b/scripts/deploy.sh index b999794..b370b4f 100644 --- a/scripts/deploy.sh +++ b/scripts/deploy.sh @@ -180,7 +180,7 @@ fi echo "3. Set up the application:" echo " cd /opt/icewatch" echo " npm install" -echo " npm run build # Compile TypeScript and build CSS" +echo " npm run build # Build everything: TypeScript backend + frontend + CSS + i18n" echo " cp .env.example .env" echo " nano .env # Add your MapBox token and admin password" echo ""