This guide explains the complete migration from CDN-based development to a TypeScript build process with automated GitHub Pages deployment.
- React, Babel, and Tailwind loaded from CDN
- No build process
- Direct HTML file served
- No type checking
- Manual deployment
- 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
.
βββ .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
Defines project dependencies and scripts:
- Dependencies: React, YAML parser, crypto, intro.js
- DevDependencies: TypeScript, Vite, Tailwind, types
- Scripts:
npm run dev- Start development servernpm run build- Build for productionnpm run preview- Preview production build
TypeScript compiler configuration:
- Target: ES2020 (modern browsers)
- Strict type checking enabled
- React JSX support
- Source maps for debugging
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 CSS configuration:
- Content paths for purging
- Dark mode support (class-based)
- Custom Ubuntu colors
- Custom animations
# Using npm
npm install
# Or using yarn
yarn install
# Or using pnpm
pnpm install# Start development server (hot reload enabled)
npm run dev
# Server will start at http://localhost:3000# TypeScript compilation + Vite build
npm run build
# Output in ./dist folder# Preview the production build locally
npm run preview
# Server will start at http://localhost:4173# Check for TypeScript errors without building
npm run type-checkThe workflow consists of two jobs:
- β Checkout repository code
- β Setup Node.js 20 with npm caching
- β
Install dependencies (
npm ci) - β Run TypeScript type checking
- β
Build the project (
npm run build) - β
Upload
distfolder as artifact
- β Download build artifact
- β Deploy to GitHub Pages
- Triggers: Runs on every push to
mainbranch - 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
The build sets GITHUB_PAGES=true to configure the base path correctly for GitHub Pages.
-
Go to Repository Settings
- Navigate to your GitHub repository
- Click "Settings" tab
-
Navigate to Pages Section
- In the left sidebar, click "Pages"
-
Configure Source
- Under "Build and deployment"
- Source: Select "GitHub Actions"
- (NOT "Deploy from a branch")
-
Save Configuration
- GitHub will now use the Actions workflow
- No need to select a branch
-
Verify Deployment
- Go to "Actions" tab
- Check workflow runs
- Click on a run to see logs
- Once complete, visit your Pages URL
https://YOUR_USERNAME.github.io/automaticinstall-GUI-Ubuntu/
In vite.config.ts, update the base path:
base: process.env.GITHUB_PAGES ? '/automaticinstall-GUI-Ubuntu/' : '/',
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^
// Change to your repo nameOr if using a custom domain:
base: '/',The workflow runs automatically when:
- β
Code is pushed to
mainbranch - β
Pull request is merged to
main
To trigger manually:
- Go to "Actions" tab
- Select "Deploy to GitHub Pages" workflow
- Click "Run workflow"
- Select branch and click "Run workflow"
Issue: TypeScript compilation errors
Solution:
# Run type check locally
npm run type-check
# Fix all TypeScript errors
# Then commit and pushIssue: Pages deployment permission denied
Solution:
- Check repository Settings β Actions β General
- Under "Workflow permissions"
- Select "Read and write permissions"
- Check "Allow GitHub Actions to create and approve pull requests"
- Save
Issue: 404 on deployed site
Solution:
- Verify base path in
vite.config.tsmatches repo name - Check that Pages is set to "GitHub Actions" source
- Ensure workflow completed successfully
Issue: CSS/JS files return 404
Solution:
- Check
basepath invite.config.ts - Should be
/repo-name/with trailing slash - Rebuild and redeploy
The build process includes:
- 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
- Removes unused code
- Smaller bundle sizes
- JavaScript minified
- CSS minified
- HTML minified
- Enabled for debugging
- Can be disabled in production
Never commit sensitive data. Use GitHub Secrets:
- Go to Settings β Secrets and variables β Actions
- Click "New repository secret"
- Add secrets
- Reference in workflow:
${{ secrets.SECRET_NAME }}
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- β‘ Vite's Fast HMR (~20ms updates)
- π₯ Hot Module Replacement
- π¨ Lightning-fast cold starts
- π¦ Optimized bundles
- ποΈ Gzip compression
- π― Code splitting
- π± PWA support
- π Offline functionality
- Create TypeScript Files: Convert existing JavaScript to TypeScript
- Add Type Definitions: Create interfaces and types
- Test Locally: Run
npm run devand test all features - Build: Run
npm run buildand verify output - Deploy: Push to
mainbranch and watch Actions workflow - Configure Pages: Set source to "GitHub Actions"
- Verify: Visit your GitHub Pages URL
- Type Safety: Catch errors at compile time
- Modern Tooling: Vite, TypeScript, Tailwind
- Automated Deployment: Push to deploy
- PWA Support: Offline functionality
- Optimized Builds: Fast loading, small bundles
- Developer Experience: Hot reload, fast builds
- Production Ready: Minified, optimized, secure
- Maintainable: Type definitions, modern code
Migration Status: Configuration files created β
Next: Convert JavaScript files to TypeScript and update imports