190 lines
7.6 KiB
Markdown
190 lines
7.6 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Project Overview
|
||
|
||
ViteKit Universal - современный универсальный сборщик проектов с Vite + Twig + компонентами. Полнофункциональная система для быстрой разработки веб-приложений с готовыми UI компонентами и модульной архитектурой.
|
||
|
||
## Common Commands
|
||
|
||
```bash
|
||
# Development
|
||
npm run dev # Запуск сервера разработки (localhost:3000)
|
||
npm run build # Сборка для продакшена
|
||
npm run preview # Предварительный просмотр сборки
|
||
|
||
# Code Quality
|
||
npm run lint # ESLint проверка JavaScript
|
||
npm run lint:fix # Автоисправление ESLint
|
||
npm run lint:css # Stylelint проверка SCSS
|
||
npm run lint:css:fix # Автоисправление Stylelint
|
||
npm run format # Prettier форматирование всех файлов
|
||
|
||
# Utilities
|
||
npm run clean # Очистка папки dist
|
||
```
|
||
|
||
## Project Architecture
|
||
|
||
### Technology Stack
|
||
- **Vite** - быстрый сборщик с HMR
|
||
- **@vituum/vite-plugin-twig** - поддержка Twig шаблонов
|
||
- **SCSS** - CSS препроцессор с модульной архитектурой
|
||
- **Vanilla JavaScript** - нативный JS без фреймворков
|
||
- **MicroModal** - доступные модальные окна (~1.9kb)
|
||
- **Toastify** - уведомления
|
||
|
||
### Directory Structure
|
||
```
|
||
src/
|
||
├── components/ # UI компоненты (modal, tabs, accordion, toast)
|
||
├── layouts/ # Twig шаблоны (base.twig)
|
||
├── pages/ # Страницы (index.twig, components-demo.twig)
|
||
├── data/ # JSON данные для Twig
|
||
├── assets/ # Статические ресурсы (images, icons, fonts)
|
||
├── styles/ # SCSS архитектура
|
||
│ ├── abstracts/ # Variables, mixins
|
||
│ ├── base/ # Reset, typography
|
||
│ ├── components/ # Component styles
|
||
│ ├── layout/ # Layout styles
|
||
│ └── pages/ # Page-specific styles
|
||
└── scripts/ # JavaScript модули
|
||
├── components/ # UI component logic
|
||
└── utils/ # Utilities and helpers
|
||
```
|
||
|
||
### Component System
|
||
- **Модульная архитектура** - каждый компонент изолирован
|
||
- **Data attributes** - инициализация через `data-*` атрибуты
|
||
- **Event-driven** - компоненты используют custom events
|
||
- **Accessibility** - полная поддержка ARIA и клавиатурной навигации
|
||
- **Responsive** - адаптивное поведение (табы → аккордеон на мобильных)
|
||
|
||
### SCSS Architecture
|
||
- **Abstracts**: переменные, миксины, функции
|
||
- **Base**: reset, типографика, базовые стили
|
||
- **Components**: стили UI компонентов
|
||
- **Layout**: сетка, контейнеры, навигация
|
||
- **Pages**: специфичные стили страниц
|
||
|
||
### Key Features
|
||
- Автоматическая оптимизация изображений
|
||
- SVG sprite injection для иконок
|
||
- Live reload и HMR
|
||
- Code splitting и tree shaking
|
||
- Legacy browser support
|
||
- Automated linting с pre-commit hooks
|
||
|
||
## Development Guidelines
|
||
|
||
### Adding New Components
|
||
1. Создать SCSS в `src/styles/components/_component.scss`
|
||
2. Создать JS в `src/scripts/components/component.js`
|
||
3. Добавить импорт в `src/styles/main.scss`
|
||
4. Добавить в компонентную систему через data attributes
|
||
|
||
### Twig Development
|
||
- Использовать JSON данные из `src/data/` для динамического контента
|
||
- Шаблоны наследуются от `layouts/base.twig`
|
||
- Все страницы автоматически обрабатываются Vite
|
||
|
||
### SCSS Best Practices
|
||
- Использовать предопределенные миксины для медиа-запросов
|
||
- Следовать БЭМ методологии для классов
|
||
- Использовать CSS custom properties для динамических значений
|
||
- Все цвета и размеры через переменные
|
||
|
||
### JavaScript Guidelines
|
||
- ES6+ modules с импортами
|
||
- Page Controller Pattern для архитектуры
|
||
- Event-driven компоненты через EventBus
|
||
- Класс-ориентированные компоненты наследуются от Component
|
||
- Performance monitoring встроен
|
||
- Graceful degradation без JavaScript
|
||
|
||
## Testing & Deployment
|
||
|
||
### Quality Assurance
|
||
- ESLint + Prettier для JavaScript
|
||
- Stylelint для SCSS
|
||
- Husky pre-commit hooks
|
||
- Автоматическое форматирование
|
||
|
||
### Build Process
|
||
- Vite handles bundling and optimization
|
||
- Automatic asset optimization (images, SVG)
|
||
- CSS/JS minification and tree shaking
|
||
- Legacy browser polyfills via @vitejs/plugin-legacy
|
||
|
||
### Performance Optimization
|
||
- Image optimization с vite-plugin-image-optimizer
|
||
- SVG sprite generation для иконок
|
||
- CSS/JS code splitting
|
||
- Preload critical resources
|
||
|
||
## Page Controller Architecture
|
||
|
||
### Создание нового page controller
|
||
```javascript
|
||
// src/scripts/pages/mypage.js
|
||
import { Component } from '../core/Component.js';
|
||
import { eventBus } from '../core/EventBus.js';
|
||
|
||
export default class MyPage extends Component {
|
||
constructor() {
|
||
super(document.body);
|
||
}
|
||
|
||
beforeInit() {
|
||
// Инициализация перед загрузкой
|
||
}
|
||
|
||
bindEvents() {
|
||
// Привязка событий страницы
|
||
}
|
||
|
||
afterInit() {
|
||
// Действия после инициализации
|
||
}
|
||
}
|
||
```
|
||
|
||
### Page detection
|
||
- Автоматическое определение по filename (mypage.html → mypage.js)
|
||
- Или через data-page атрибут: `<body data-page="custom-name">`
|
||
|
||
### Component API
|
||
```javascript
|
||
// Создание компонента
|
||
const myComponent = Component.create(element, options);
|
||
|
||
// EventBus для связи между компонентами
|
||
eventBus.on('custom:event', callback);
|
||
eventBus.emit('custom:event', data);
|
||
|
||
// Performance monitoring
|
||
performanceMonitor.mark('my-action');
|
||
performanceMonitor.measure('my-action', 'start-mark', 'end-mark');
|
||
```
|
||
|
||
### Utilities
|
||
```javascript
|
||
// DOM utilities
|
||
import { ready, createElement, scrollToElement } from '@scripts/utils/dom.js';
|
||
|
||
// Performance utilities
|
||
import { debounce, throttle, memoize } from '@scripts/utils/performance.js';
|
||
|
||
// Helper utilities
|
||
import { deepClone, formatDate, copyToClipboard } from '@scripts/utils/helpers.js';
|
||
```
|
||
|
||
## Special Considerations
|
||
|
||
- Команды терминала запускаются в фоновом режиме (не используйте циклические команды)
|
||
- Все пути используют алиасы (@, @styles, @components, @scripts, @assets)
|
||
- Responsive-first подход с мобильными брейкпоинтами
|
||
- Accessibility-first разработка с ARIA и keyboard support
|
||
- Page controllers загружаются автоматически по имени файла/страницы
|
||
- Используйте EventBus для связи между компонентами разных страниц |