Artyom Chshyogolev

🌐 Frontend Development Workflow

A beginner-friendly template system for creating modern websites that can be easily integrated with backend frameworks (FastAPI, Django, Flask, PHP, etc.).

🎯 What You’ll Build

With this project, you’ll create:

• Fast, modern websites using TypeScript and SCSS
• Reusable templates to avoid repeating HTML code
• Optimized images that load quickly
• Production-ready files for backend integration

🛠️ What Tools We Use

• 🟢 Bun: Fast package manager and JavaScript runtime (replaces npm)
• ⚡ Vite: Modern build tool that compiles and optimizes your code
• 📝 TypeScript: JavaScript with types to prevent bugs
• 🎨 SCSS: CSS with variables, nesting, and functions
• 📄 Handlebars: Template system to reuse HTML layouts
• 🖼️ Image Optimization: Automatic compression and format conversion

📚 Learning Path (Start Here!)

👋 Complete beginner?

• 🚀 Quick Start Guide - Get running in 5 minutes with a complete example!

🤔 Never used these tools before? Read these guides in order:

1. 📖 Understanding the Tools - What are Bun, TypeScript, and Vite?
2. 🏗️ Project Structure - How files are organized
3. 📄 Working with Templates - Creating layouts and partials

🚀 Ready to build features?

1. ✅ Adding New Pages - Step-by-step checklist
2. 🎨 Styling Guide - Working with SCSS
3. ⚡ TypeScript Basics - Writing safer JavaScript

🔧 Need help with problems?

1. 🔧 Troubleshooting Guide - Common issues and solutions

🚀 Essential Commands

# First time setup (installs all tools)
bun install

# Start development server with live preview
bun run dev
# → Opens http://localhost:5173

# Build for production (creates dist/ folder)
bun run build

# Preview the production build locally
bun run preview

👋 Brand new to this? Start with the 🚀 Quick Start Guide - get running in 5 minutes!

🎯 What This Project Does

✨ Features for You (Developer)

• 🔄 Live Reload: See changes instantly in your browser
• 🔍 Error Detection: TypeScript catches bugs before they happen
• 📱 Template System: Write HTML once, reuse everywhere
• 🎨 Modern CSS: Variables, nesting, and functions with SCSS
• 🖼️ Smart Images: Automatic compression and WebP conversion
• ⚡ Fast Builds: Optimized for development and production

📦 Output for Backend Team

After running bun run build, you get:

• Clean HTML files with all templates compiled
• Minified CSS and JavaScript for fast loading
• Optimized images in modern formats
• Cache-friendly filenames (like style-abc123.css)

🏗️ TypeScript Integration

This project includes full TypeScript support:

// ✅ Type-safe functions
function calculateTotal(price: number, tax: number): number {
    return price + tax;
}

// ✅ DOM manipulation with types  
const button = document.getElementById('submit') as HTMLButtonElement;
button.addEventListener('click', handleSubmit);

// ✅ Automatic compilation to JavaScript
// TypeScript → JavaScript happens automatically during build

Benefits:

• Catch errors early - before your site goes live
• Better autocomplete - your editor knows what each function does
• Self-documenting code - types show what data is expected
• Seamless integration - works perfectly with Vite and Bun

🖼️ Automatic Image Optimization

Images are automatically optimized during build:

// vite.config.js - Image optimization settings
viteImagemin({
  mozjpeg: { quality: 80 },     // JPEG compression
  pngquant: { quality: [0.6, 0.8] }, // PNG optimization  
  svgo: true,                   // SVG optimization
  webp: { quality: 75 },        // WebP conversion
})

What happens to your images:

src/images/photo.jpg (2MB)
    ↓ Vite processes it
dist/assets/photo-abc123.jpg (400KB)  ← 80% smaller!
dist/assets/photo-abc123.webp (300KB) ← Modern format

📁 What Gets Built

dist/               # 📦 Production-ready files for backend
├── index.html      # Compiled homepage  
├── assets/         # 🎨 Optimized assets
│   ├── index-a1b2c3.js     # Minified TypeScript → JavaScript
│   ├── style-d4e5f6.css    # Compiled SCSS → CSS
│   ├── photo-g7h8i9.jpg    # Compressed images
│   └── photo-g7h8i9.webp   # Modern image formats
└── ...

🆘 Getting Help

🚀 Just getting started?

• Begin with Quick Start Guide

🤔 Don’t understand a tool?

• Read Understanding the Tools

🏗️ Want to understand the project?

• Check Project Structure

➕ Adding a new page?

• Follow Adding Pages Checklist

🎨 Styling problems?

• Review Styling Guide

⚡ TypeScript errors?

• Study TypeScript Guide

🔧 Something not working?

• Check Troubleshooting Guide

⚠️ Important Rules

1. 🚫 Never edit dist/ folder - it gets overwritten when you build
2. 📄 Always use templates - don’t copy/paste HTML between pages
3. 📝 Write TypeScript, not JavaScript - it prevents bugs
4. 🖼️ Put images in src/images/ - they’ll be optimized automatically
5. 🔨 Run bun run build before giving files to backend team

🔧 Prerequisites

Required:

• Node.js (v18 or newer) - Download here
• Bun (latest) - Install guide

Check if installed:

node --version    # Should be v18+
bun --version     # Should be 1.0+

---

🚀 Ready to start? Read Understanding the Tools to learn what each tool does.