Ensiklopedia VibeKoding: Principles of Frontend Project Architecture.Ensiklopedia VibeKoding: Principles of Frontend Project Architecture.
How do you choose the right architecture for projects of different sizes, from simple HTML pages to complex enterprise applications? It's like asking: from a studio apartment to a large shopping mall, how do you design different spatial layouts based on needs? Good architecture should evolve with the project, rather than being over-engineered from the start.How do you choose the right architecture for projects of different sizes, from simple HTML pages to complex enterprise applications? It's like asking: from a studio apartment to a large shopping mall, how do you design different spatial layouts based on needs? Good architecture should evolve with the project, rather than being over-engineered from the start.
------
Frontend project architecture should match project complexity. We classify projects into three levels based on technical complexity and user scale:Frontend project architecture should match project complexity. We classify projects into three levels based on technical complexity and user scale:
| Level | Tech Stack | User Scale | Typical Scenarios | Core Focus |
|---|---|---|---|---|
| Beginner | HTML/CSS/JS | Individual/small team | Personal blogs, landing pages, simple tools | Quick launch, simple maintenance |
| Intermediate | Vue/React + build tools | Small-to-medium business | Management systems, e-commerce frontends, SaaS | Component reuse, state management |
| Enterprise | Framework + micro-frontend/SSR | Large applications | Large platforms, complex business systems | Performance optimization, team collaboration, scalability |
Don't over-engineer! Many projects start with simple HTML and gradually introduce frameworks and tools as needs grow. - Personal projects → Beginner level - Startup MVP → Beginner or intermediate level - Enterprise management systems → Intermediate level - Large internet platforms → Enterprise levelDon't over-engineer! Many projects start with simple HTML and gradually introduce frameworks and tools as needs grow. - Personal projects → Beginner level - Startup MVP → Beginner or intermediate level - Enterprise management systems → Intermediate level - Large internet platforms → Enterprise level
------
CODE my-simple-project/ ├── index.html # Homepage ├── about.html # About page (if needed) ├── css/ │ ├── reset.css # Reset styles │ ├── variables.css # CSS variables (colors, fonts, etc.) │ ├── components.css # Component styles (buttons, cards, etc.) │ └── main.css # Main stylesheet ├── js/ │ ├── utils.js # Utility functions │ ├── api.js # Simple API calls │ └── main.js # Main logic ├── assets/ │ ├── images/ # Image assets │ └── fonts/ # Font files └── README.md # Project documentation
HTML: Semantic tags, clear structureHTML: Semantic tags, clear structure
html <!-- index.html --> <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>My Personal Blog</title> <link rel="stylesheet" href="css/reset.css"> <link rel="stylesheet" href="css/variables.css"> <link rel="stylesheet" href="css/components.css"> <link rel="stylesheet" href="css/main.css"> </head> <body> <header class="site-header"> <nav class="main-nav"> <a href="index.html">Home</a> <a href="about.html">About</a> </nav> </header> <main class="content"> <article class="blog-post"> <h1>Article Title</h1> <p>Article content...</p> </article> </main> <footer class="site-footer"> <p>© 2024 My Blog</p> </footer> <script src="js/utils.js"></script> <script src="js/main.js"></script> </body> </html>
CSS: Use CSS variables to manage themesCSS: Use CSS variables to manage themes
css /* variables.css */ :root { --primary-color: #3498db; --text-color: #333; --bg-color: #fff; --spacing-sm: 8px; --spacing-md: 16px; --spacing-lg: 24px; --font-base: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; } /* components.css - Reusable component styles */ .btn { padding: var(--spacing-sm) var(--spacing-md); border: none; border-radius: 4px; background: var(--primary-color); color: white; cursor: pointer; } .card { padding: var(--spacing-md); border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
JavaScript: Modular organization (using ES6 modules or simple splitting)JavaScript: Modular organization (using ES6 modules or simple splitting)
javascript // utils.js const utils = { // Simplified DOM operations $(selector) { return document.querySelector(selector); }, // Simple debounce debounce(fn, delay) { let timer; return function(...args) { clearTimeout(timer); timer = setTimeout(() => fn.apply(this, args), delay); }; }, // Local storage wrapper storage: { get(key) { return JSON.parse(localStorage.getItem(key) || 'null'); }, set(key, value) { localStorage.setItem(key, JSON.stringify(value)); } } }; // main.js document.addEventListener('DOMContentLoaded', () => { // Page initialization logic initNavigation(); loadBlogPosts(); });
✅ Do:✅ Do:
❌ Avoid:❌ Avoid:
style="...")Inline styles (style="...")------
CODE my-vue-project/ ├── public/ # Static assets │ ├── index.html │ └── favicon.ico ├── src/ │ ├── assets/ # Styles, images, fonts │ │ ├── styles/ │ │ │ ├── variables.scss │ │ │ ├── mixins.scss │ │ │ └── global.scss │ │ └── images/ │ ├── components/ # Shared components │ │ ├── common/ # Global shared (Button, Modal, etc.) │ │ │ ├── Button/ │ │ │ │ ├── index.vue │ │ │ │ └── Button.scss │ │ │ └── Modal/ │ │ └── business/ # Business components (UserCard, etc.) │ ├── views/ # Page components │ │ ├── Home/ │ │ ├── User/ │ │ │ ├── List.vue │ │ │ └── Detail.vue │ │ └── Product/ │ ├── router/ # Route configuration │ │ └── index.js │ ├── stores/ # Pinia/Vuex state management │ │ ├── user.js │ │ └── app.js │ ├── services/ # API services │ │ ├── request.js # axios wrapper │ │ ├── user.js │ │ └── product.js │ ├── utils/ # Utility functions │ │ ├── format.js │ │ ├── validate.js │ │ └── storage.js │ ├── composables/ # Composable functions │ │ ├── useAuth.js │ │ └── useLoading.js │ ├── constants/ # Constant definitions │ │ └── index.js │ ├── App.vue │ └── main.js ├── tests/ # Test files ├── .env # Environment variables ├── vite.config.js ├── package.json └── README.md
CODE my-react-project/ ├── public/ ├── src/ │ ├── assets/ │ ├── components/ │ │ ├── common/ # Shared components │ │ │ ├── Button/ │ │ │ │ ├── index.jsx │ │ │ │ └── Button.module.css │ │ │ └── Modal/ │ │ └── business/ # Business components │ ├── pages/ # Page components │ │ ├── Home/ │ │ ├── User/ │ │ └── Product/ │ ├── hooks/ # Custom Hooks │ │ ├── useAuth.js │ │ └── useFetch.js │ ├── services/ # API services │ │ ├── api.js │ │ └── userService.js │ ├── store/ # Redux/Zustand state management │ │ ├── slices/ │ │ └── index.js │ ├── utils/ │ ├── constants/ │ ├── App.jsx │ └── main.jsx ├── tests/ └── package.json
Single Responsibility: One component does one thingSingle Responsibility: One component does one thing
vue <!-- ❌ Bad example: Component does too much --> <template> <div> <form @submit="handleSubmit"> <!-- Form content --> </form> <table> <!-- Data table --> </table> <div class="charts"> <!-- Charts --> </div> </div> </template> <!-- ✅ Good example: Split into independent components --> <template> <div> <UserForm @submit="fetchData" /> <UserTable :data="users" /> <UserStats :data="users" /> </div> </template>
| State Type | Storage Location | Example |
|---|---|---|
| Global state | Pinia/Redux | User info, login status, theme settings |
| Page state | Page component | List query conditions, pagination info |
| Component state | Component internal | Form inputs, modal show/hide |
| Server state | TanStack Query/SWR | Server data, caching |
Approach 1: Organize by type (suitable for small projects)Approach 1: Organize by type (suitable for small projects)
CODE src/ ├── components/ # All components ├── views/ # All pages ├── stores/ # All state └── services/ # All services
Approach 2: Organize by feature (suitable for medium-to-large projects)Approach 2: Organize by feature (suitable for medium-to-large projects)
CODE src/ ├── features/ │ ├── auth/ # All code for authentication feature │ ├── user/ # All code for user feature │ └── product/ # All code for product feature ├── shared/ # Shared resources └── App.vue
- Project pages < 10 → Organize by type - Project pages > 20 → Organize by feature - Team > 5 people → Organize by feature for parallel development- Project pages < 10 → Organize by type - Project pages > 20 → Organize by feature - Team > 5 people → Organize by feature for parallel development
------
When a project grows to a certain size and a single codebase becomes difficult to maintain, micro-frontend architecture can be considered.When a project grows to a certain size and a single codebase becomes difficult to maintain, micro-frontend architecture can be considered.
CODE Large E-Commerce Platform/ ├── Base Application (Main Framework) │ ├── Top Navigation │ ├── Side Menu │ ├── User Center Entry │ └── Sub-application Container ├── Product Sub-application (Independently deployed) │ ├── Product List │ ├── Product Details │ └── Product Management ├── Order Sub-application (Independently deployed) │ ├── Shopping Cart │ ├── Order List │ └── Payment Flow ├── User Sub-application (Independently deployed) │ ├── Personal Center │ ├── Shipping Addresses │ └── Coupons └── Marketing Sub-application (Independently deployed) ├── Campaign Pages ├── Coupon Distribution └── Points Mall
Advantages of micro-frontends:Advantages of micro-frontends:
CODE enterprise-project/ ├── apps/ # Micro-frontend sub-applications │ ├── main/ # Base application │ ├── product/ │ ├── order/ │ └── user/ ├── packages/ # Shared packages (Monorepo) │ ├── ui-components/ # Shared component library │ ├── utils/ # Utility functions │ ├── constants/ # Constant definitions │ └── types/ # TypeScript types ├── shared/ # Shared configuration │ ├── eslint-config/ │ ├── ts-config/ │ └── vite-config/ ├── docs/ # Project documentation ├── scripts/ # Build scripts └── package.json
Large applications need to focus on performance optimization:Large applications need to focus on performance optimization:
CODE Performance Optimization Strategy/ ├── Build-time Optimization │ ├── Code Splitting │ ├── Route Lazy Loading │ ├── Tree Shaking │ └── Asset Compression ├── Runtime Optimization │ ├── Virtual Scrolling (long lists) │ ├── Image Lazy Loading │ ├── On-demand Component Rendering │ └── Caching Strategy └── Network Optimization ├── CDN Acceleration ├── HTTP Caching ├── Resource Preloading └── Service Worker
For scenarios requiring SEO or fast first-screen performance:For scenarios requiring SEO or fast first-screen performance:
| Approach | Suitable Scenarios | Representative Frameworks |
|---|---|---|
| SSR | Needs SEO, fast first-screen rendering | Next.js, Nuxt.js |
| SSG | Static content, infrequent updates | Astro, VitePress |
| Hybrid | Part static, part dynamic | Next.js (ISR) |
------
Characteristics: Fast iteration, limited resources, rapidly changing requirementsCharacteristics: Fast iteration, limited resources, rapidly changing requirements
Recommended Architecture:Recommended Architecture:
Directory Structure: Simple organization by typeDirectory Structure: Simple organization by type
Characteristics: Complex business, team collaboration, stability requiredCharacteristics: Complex business, team collaboration, stability required
Recommended Architecture:Recommended Architecture:
Directory Structure: Organize by feature, establish standardsDirectory Structure: Organize by feature, establish standards
Characteristics: High concurrency, multi-team collaboration, long-term maintenanceCharacteristics: High concurrency, multi-team collaboration, long-term maintenance
Recommended Architecture:Recommended Architecture:
Directory Structure: Monorepo + micro-frontendDirectory Structure: Monorepo + micro-frontend
------
CODE Stage 1: Personal Blog (HTML/CSS/JS) ↓ Need: Backend management needed Stage 2: Add Admin Panel (Vue/React + simple structure) ↓ Need: User system, comments feature Stage 3: Feature Modularization (organize by feature) ↓ Need: Multi-team collaboration, independent deployment Stage 4: Micro-frontend Architecture (Monorepo)
| Signal | Description | Suggestion |
|---|---|---|
| Build time > 5 minutes | Project too large | Code splitting, micro-frontend |
| Frequent merge conflicts | Collaboration difficulties | Organize by feature, module splitting |
| Fix one thing, break another | Severe coupling | Refactor, strengthen testing |
| First screen load > 3 seconds | Performance issues | Lazy loading, SSR, optimization |
| Slow onboarding for new members | Disorganized structure | Documentation, standards, refactoring |
------
There is no silver bullet for architecture — what fits is best. - Small projects: Don't over-engineer, HTML/CSS/JS is sufficient - Medium projects: Establish standards, componentization, modularization - Large projects: Consider micro-frontends, performance optimization, team collaboration Remember these points: 1. Progressive evolution: Start simple, grow with needs 2. Unified conventions: Keep naming, structure, and code style consistent 3. Documentation first: Record architecture decisions for knowledge transfer 4. Regular refactoring: Pay off technical debt in a timely manner Ultimate goal: Make code like an organized space — regardless of size, running efficiently.There is no silver bullet for architecture — what fits is best. - Small projects: Don't over-engineer, HTML/CSS/JS is sufficient - Medium projects: Establish standards, componentization, modularization - Large projects: Consider micro-frontends, performance optimization, team collaboration Remember these points: 1. Progressive evolution: Start simple, grow with needs 2. Unified conventions: Keep naming, structure, and code style consistent 3. Documentation first: Record architecture decisions for knowledge transfer 4. Regular refactoring: Pay off technical debt in a timely manner Ultimate goal: Make code like an organized space — regardless of size, running efficiently.
------