Skip to content

Latest commit

Β 

History

History
366 lines (272 loc) Β· 8.93 KB

TYPESCRIPT_MIGRATION.md

File metadata and controls

366 lines (272 loc) Β· 8.93 KB

TypeScript Migration & GitHub Actions Deployment Guide

πŸš€ Overview

This guide explains the complete migration from CDN-based development to a TypeScript build process with automated GitHub Pages deployment.

πŸ“¦ What Changed

Before (CDN-based)

  • React, Babel, and Tailwind loaded from CDN
  • No build process
  • Direct HTML file served
  • No type checking
  • Manual deployment

After (TypeScript + Build)

  • All dependencies in package.json
  • Vite build system
  • TypeScript for type safety
  • Automated CI/CD with GitHub Actions
  • Progressive Web App support
  • Optimized production builds

πŸ—‚οΈ New File Structure

.
β”œβ”€β”€ .github/
β”‚   └── workflows/
β”‚       └── deploy.yml          # GitHub Actions deployment workflow
β”œβ”€β”€ src/                        # TypeScript source files (to be created)
β”‚   β”œβ”€β”€ main.tsx               # Application entry point
β”‚   β”œβ”€β”€ App.tsx                # Main App component
β”‚   β”œβ”€β”€ components/            # React components
β”‚   β”œβ”€β”€ utils/                 # Utility functions
β”‚   β”œβ”€β”€ types/                 # TypeScript type definitions
β”‚   └── styles/                # CSS/Tailwind styles
β”œβ”€β”€ dist/                       # Build output (generated, gitignored)
β”œβ”€β”€ node_modules/              # Dependencies (gitignored)
β”œβ”€β”€ index.html                 # HTML template
β”œβ”€β”€ package.json               # Dependencies and scripts
β”œβ”€β”€ tsconfig.json              # TypeScript configuration
β”œβ”€β”€ tsconfig.node.json         # TypeScript config for Node files
β”œβ”€β”€ vite.config.ts             # Vite bundler configuration
β”œβ”€β”€ tailwind.config.js         # Tailwind CSS configuration
β”œβ”€β”€ postcss.config.js          # PostCSS configuration
└── .gitignore                 # Git ignore rules

βš™οΈ Configuration Files Explained

package.json

Defines project dependencies and scripts:

  • Dependencies: React, YAML parser, crypto, intro.js
  • DevDependencies: TypeScript, Vite, Tailwind, types
  • Scripts:
    • npm run dev - Start development server
    • npm run build - Build for production
    • npm run preview - Preview production build

tsconfig.json

TypeScript compiler configuration:

  • Target: ES2020 (modern browsers)
  • Strict type checking enabled
  • React JSX support
  • Source maps for debugging

vite.config.ts

Vite bundler configuration:

  • React plugin with Fast Refresh
  • PWA plugin for offline support
  • GitHub Pages base path configuration
  • Code splitting for optimal caching
  • Source maps generation

tailwind.config.js

Tailwind CSS configuration:

  • Content paths for purging
  • Dark mode support (class-based)
  • Custom Ubuntu colors
  • Custom animations

πŸ”§ Setup Instructions

1. Install Dependencies

# Using npm
npm install

# Or using yarn
yarn install

# Or using pnpm
pnpm install

2. Development

# Start development server (hot reload enabled)
npm run dev

# Server will start at http://localhost:3000

3. Build for Production

# TypeScript compilation + Vite build
npm run build

# Output in ./dist folder

4. Preview Production Build

# Preview the production build locally
npm run preview

# Server will start at http://localhost:4173

5. Type Checking

# Check for TypeScript errors without building
npm run type-check

πŸ€– GitHub Actions Workflow

Workflow File: .github/workflows/deploy.yml

The workflow consists of two jobs:

Job 1: Build

  1. βœ… Checkout repository code
  2. βœ… Setup Node.js 20 with npm caching
  3. βœ… Install dependencies (npm ci)
  4. βœ… Run TypeScript type checking
  5. βœ… Build the project (npm run build)
  6. βœ… Upload dist folder as artifact

Job 2: Deploy

  1. βœ… Download build artifact
  2. βœ… Deploy to GitHub Pages

Key Features

  • Triggers: Runs on every push to main branch
  • Permissions: Properly set for Pages deployment
  • Concurrency: Prevents conflicting deployments
  • Type Safety: Fails if TypeScript errors exist
  • Caching: npm dependencies cached for speed
  • Artifacts: Build output preserved between jobs

Environment Variables

The build sets GITHUB_PAGES=true to configure the base path correctly for GitHub Pages.

πŸ“„ Activating GitHub Pages

Step-by-Step:

  1. Go to Repository Settings

    • Navigate to your GitHub repository
    • Click "Settings" tab
  2. Navigate to Pages Section

    • In the left sidebar, click "Pages"
  3. Configure Source

    • Under "Build and deployment"
    • Source: Select "GitHub Actions"
    • (NOT "Deploy from a branch")
  4. Save Configuration

    • GitHub will now use the Actions workflow
    • No need to select a branch
  5. Verify Deployment

    • Go to "Actions" tab
    • Check workflow runs
    • Click on a run to see logs
    • Once complete, visit your Pages URL

Your Pages URL will be:

https://YOUR_USERNAME.github.io/automaticinstall-GUI-Ubuntu/

Important: Update Base Path

In vite.config.ts, update the base path:

base: process.env.GITHUB_PAGES ? '/automaticinstall-GUI-Ubuntu/' : '/',
//                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^
//                                  Change to your repo name

Or if using a custom domain:

base: '/',

πŸ”„ Workflow Triggers

The workflow runs automatically when:

  • βœ… Code is pushed to main branch
  • βœ… Pull request is merged to main

To trigger manually:

  1. Go to "Actions" tab
  2. Select "Deploy to GitHub Pages" workflow
  3. Click "Run workflow"
  4. Select branch and click "Run workflow"

🚨 Troubleshooting

Build Fails

Issue: TypeScript compilation errors

Solution:

# Run type check locally
npm run type-check

# Fix all TypeScript errors
# Then commit and push

Deployment Fails

Issue: Pages deployment permission denied

Solution:

  1. Check repository Settings β†’ Actions β†’ General
  2. Under "Workflow permissions"
  3. Select "Read and write permissions"
  4. Check "Allow GitHub Actions to create and approve pull requests"
  5. Save

Issue: 404 on deployed site

Solution:

  • Verify base path in vite.config.ts matches repo name
  • Check that Pages is set to "GitHub Actions" source
  • Ensure workflow completed successfully

Assets Not Loading

Issue: CSS/JS files return 404

Solution:

  • Check base path in vite.config.ts
  • Should be /repo-name/ with trailing slash
  • Rebuild and redeploy

πŸ“Š Build Optimizations

The build process includes:

Code Splitting

  • React/React-DOM β†’ react-vendor.js
  • YAML parser β†’ yaml-vendor.js
  • Crypto library β†’ crypto-vendor.js
  • Intro.js β†’ intro-vendor.js

Benefits:

  • Better caching (vendors change less)
  • Faster page loads
  • Parallel downloads

Tree Shaking

  • Removes unused code
  • Smaller bundle sizes

Minification

  • JavaScript minified
  • CSS minified
  • HTML minified

Source Maps

  • Enabled for debugging
  • Can be disabled in production

πŸ” Security

Environment Variables

Never commit sensitive data. Use GitHub Secrets:

  1. Go to Settings β†’ Secrets and variables β†’ Actions
  2. Click "New repository secret"
  3. Add secrets
  4. Reference in workflow: ${{ secrets.SECRET_NAME }}

Dependency Updates

Regularly update dependencies:

# Check for updates
npm outdated

# Update all dependencies
npm update

# Or use npm-check-updates
npx npm-check-updates -u
npm install

πŸ“ˆ Performance

Development Server

  • ⚑ Vite's Fast HMR (~20ms updates)
  • πŸ”₯ Hot Module Replacement
  • πŸ’¨ Lightning-fast cold starts

Production Build

  • πŸ“¦ Optimized bundles
  • πŸ—œοΈ Gzip compression
  • 🎯 Code splitting
  • πŸ“± PWA support
  • 🌐 Offline functionality

🎯 Next Steps

  1. Create TypeScript Files: Convert existing JavaScript to TypeScript
  2. Add Type Definitions: Create interfaces and types
  3. Test Locally: Run npm run dev and test all features
  4. Build: Run npm run build and verify output
  5. Deploy: Push to main branch and watch Actions workflow
  6. Configure Pages: Set source to "GitHub Actions"
  7. Verify: Visit your GitHub Pages URL

πŸ“š Resources

✨ Benefits of This Setup

  1. Type Safety: Catch errors at compile time
  2. Modern Tooling: Vite, TypeScript, Tailwind
  3. Automated Deployment: Push to deploy
  4. PWA Support: Offline functionality
  5. Optimized Builds: Fast loading, small bundles
  6. Developer Experience: Hot reload, fast builds
  7. Production Ready: Minified, optimized, secure
  8. Maintainable: Type definitions, modern code

Migration Status: Configuration files created βœ…

Next: Convert JavaScript files to TypeScript and update imports