signal-works/ice
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

Update documentation for TypeScript frontend build system

Browse source 
- 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 <noreply@anthropic.com>
This commit is contained in:
Claude Code 2025-07-07 20:36:58 -04:00
parent 1d346bf9f2
commit 56c846a44b
3 changed files with 98 additions and 44 deletions
Download patch file Download diff file Expand all files Collapse all files

84
CLAUDE.md
View file

@ -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`

56
README.md
View file

@ -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:**

2
scripts/deploy.sh
View file

@ -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 ""