TypeScript Demo App

A full-stack TypeScript application with Next.js frontend and Express.js backend, running on Docker Compose.

Architecture

• Frontend: Next.js 16 with App Router
• Backend: Express.js REST API
• Language: TypeScript (strict mode)
• Container: Docker Compose
• CI/CD: GitHub Actions
• Deployment: GitHub Pages (static) or Docker (full stack)

Quick Start

Full Stack with Docker Compose

docker compose up --build

• Frontend: http://localhost:3001
• Backend API: http://localhost:3000

Static Deployment (GitHub Pages)

The app automatically deploys to GitHub Pages when you push to the main branch. The static version shows demo data without requiring a backend.

Setup GitHub Pages:

1. Go to your repository Settings → Pages
2. Set Source to "GitHub Actions"
3. Push to main branch to trigger deployment

API Endpoints (Backend)

• GET / - Welcome message and available endpoints
• GET /health - Health check endpoint
• GET /api/users - Get all users
• GET /api/users/:id - Get user by ID
• POST /api/users - Create a new user (body: {name, email})

Frontend Pages

• / - Home page with navigation
• /users - Users list (fetched from API or demo data)
• /health - API health status (or demo status)

Development

Backend (API)

npm install
npm run dev    # Development with ts-node
npm run build  # Build TypeScript
npm start      # Production build

Frontend (Next.js)

cd frontend
npm install
npm run dev    # Development server (requires API running)
npm run build  # Production build (static export)
npm start      # Production server (only works with standalone)

Static Build for GitHub Pages

cd frontend
NEXT_PUBLIC_STATIC_MODE=true npm run build
# Output will be in frontend/out/

Testing Locally

Full Stack

# Terminal 1 - API
npm run dev

# Terminal 2 - Frontend
cd frontend && PORT=3001 npm run dev

Then visit http://localhost:3001

Static Version

cd frontend
NEXT_PUBLIC_STATIC_MODE=true npm run build
npx serve out

CI/CD Pipeline

Test Workflow (.github/workflows/test.yml)

Runs on every push and PR to main:

• ✅ Tests Express API endpoints
• ✅ Tests Next.js build process
• ✅ Integration tests (API + Frontend)

Deploy Workflow (.github/workflows/deploy.yml)

Runs on every push to main:

• 🚀 Builds static site
• 🚀 Deploys to GitHub Pages
• 🚀 Shows demo data (no backend required)

Deployment Modes

Mode	Platform	Backend	Data
Full Stack	Docker	✅ Express API	Live data
Static	GitHub Pages	❌ None	Demo data

Project Structure

.
├── .github/workflows/     # GitHub Actions
│   ├── test.yml          # Test pipeline
│   └── deploy.yml        # Deploy to GitHub Pages
├── frontend/             # Next.js frontend
│   ├── src/app/         # App Router pages
│   ├── public/          # Static assets
│   └── out/             # Static export output
├── src/                  # Express API
├── docker-compose.yml    # Multi-service config
└── package.json          # API dependencies