# 🚀 Полное руководство

## 📋 Подготовка к установке

### Системные требования

- **Node.js** 16.0+
- **npm** 7.0+ или **yarn** 1.22+
- **Git** (для клонирования)

### Проверка версий

```bash
node --version    # v16.0+
npm --version     # 7.0+
git --version     # любая актуальная
```

## 🚀 Возможности

- **⚡ Vite + Vituum** - Молниеносная сборка и HMR
- **🎨 Шаблонизаторы** - Поддержка Pug и Twig
- **💅 SCSS** - Современный препроцессор CSS
- **🔍 Линтинг** - ESLint + Prettier + Stylelint
- **📱 Адаптивность** - Mobile-first подход
- **🖼️ Оптимизация изображений** - Автоматическое сжатие
- **🔒 HTTPS** - Безопасная разработка
- **📊 JSON данные** - Динамическая загрузка контента
- **🎯 Современный JS** - ES6+ модули и функции

## 📦 Установка

```bash
# Клонирование репозитория
git clone <repository-url>
cd modern-frontend-builder

# Установка зависимостей
npm install
```

## 🛠️ Использование

```bash
# Запуск сервера разработки
npm run dev

# Сборка для продакшена
npm run build

# Предварительный просмотр сборки
npm run preview

# Линтинг и форматирование
npm run lint          # ESLint
npm run format        # Prettier
npm run lint:style    # Stylelint

# HTTPS сервер
npm run serve
```

## 📁 Структура проекта

```
src/
├── pages/              # Страницы (HTML/PUG/TWIG)
├── layouts/            # Макеты шаблонов
├── components/         # Переиспользуемые компоненты
├── styles/             # SCSS стили
├── js/                 # JavaScript модули
├── images/             # Изображения
├── fonts/              # Шрифты
├── data/               # JSON данные
└── public/             # Статические файлы
```

## 🎨 Работа с шаблонами

### Pug

```pug
extends ../layouts/base

block content
  .hero
    h1= data.content.hero.title
    p= data.content.hero.subtitle
```

### Twig

```twig
{% extends 'layouts/main.twig' %}

{% block content %}
<div class="hero">
    <h1>{{ data.content.hero.title }}</h1>
    <p>{{ data.content.hero.subtitle }}</p>
</div>
{% endblock %}
```

## 💅 Система стилей

- **vars** - Централизованные переменные
- **Mixins** - Переиспользуемые стили
- **Components** - Модульные компоненты
- **Utilities** - Вспомогательные классы
- **BEM методология** - Структурированное именование

## 🖼️ Оптимизация изображений

Автоматическая оптимизация:

- **JPEG** - mozjpeg сжатие
- **PNG** - pngquant оптимизация
- **SVG** - SVGO минификация
- **WebP** - Современный формат

## 📊 Работа с данными

JSON файлы автоматически доступны в шаблонах:

```javascript
// В JavaScript
import { loadData } from './utils/dataLoader.js';
const data = await loadData('/src/data/content.json');
```

## 🔧 Настройка

### Vite конфигурация

Основные настройки в `vite.config.js`:

- Алиасы путей
- Плагины оптимизации
- Настройки сборки
- HTTPS сертификаты

### Линтинг

- **ESLint** - JavaScript код
- **Stylelint** - CSS/SCSS стили
- **Prettier** - Форматирование

## 🚀 Развертывание

### Сборка для продакшена

```bash
npm run build
```

Результат будет в папке `dist/` - готов для загрузки на хостинг.

### Настройка для хостинга

Большинство хостингов поддерживают статические файлы из папки `dist/`.

Для **Netlify/Vercel**:

- Подключите Git репозиторий
- Команда сборки: `npm run build`
- Папка публикации: `dist`

Для **GitHub Pages**:

```bash
# Установите gh-pages
npm install --save-dev gh-pages

# Добавьте в package.json
"scripts": {
  "deploy": "npm run build && gh-pages -d dist"
}

# Деплой
npm run deploy
```

## 🔄 Рабочий процесс

### Ежедневная разработка

1. **Запуск:** `npm run dev`
2. **Разработка:** Редактирование файлов в `src/`
3. **Проверка:** `npm run lint`
4. **Коммит:** Сохранение изменений в Git

### Перед релизом

1. **Тестирование:** `npm run build && npm run preview`
2. **Проверка качества:**
   ```bash
   npm run lint
   npm run format
   npm run lint:style
   ```
3. **Сборка:** `npm run build`
4. **Деплой:** Загрузка `dist/` на хостинг

## 📚 Дополнительные возможности

### Добавление новых шаблонизаторов

В `vite.config.js` можно добавить поддержку других шаблонов:

```javascript
import handlebars from '@vituum/vite-plugin-handlebars';

// В plugins
handlebars({
  root: './src'
});
```

### Интеграция с CMS

Для подключения к Headless CMS:

```javascript
// src/js/utils/cms.js
export const fetchContent = async endpoint => {
  const response = await fetch(`https://api.your-cms.com/${endpoint}`);
  return response.json();
};
```

### Добавление PWA

```bash
npm install --save-dev vite-plugin-pwa

# В vite.config.js
import { VitePWA } from 'vite-plugin-pwa';

// В plugins
VitePWA({
  registerType: 'autoUpdate',
  workbox: {
    globPatterns: ['**/*.{js,css,html,ico,png,svg}']
  }
})
```

### Анализ бандла

```bash
npm install --save-dev rollup-plugin-visualizer

# Добавить в vite.config.js
import { visualizer } from 'rollup-plugin-visualizer';

// В plugins
visualizer({
  filename: 'dist/stats.html',
  open: true
})
```

## 📖 Полезные ссылки

- **Vite документация:** https://vitejs.dev/
- **Vituum документация:** https://vituum.dev/
- **Pug документация:** https://pugjs.org/
- **Twig документация:** https://twig.symfony.com/
- **SCSS документация:** https://sass-lang.com/
- **ESLint правила:** https://eslint.org/docs/rules/
- **Prettier опции:** https://prettier.io/docs/en/options.html