templates/vitekit-claude/CLAUDE.md

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

# 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

// 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

// Создание компонента
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

// 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 для связи между компонентами разных страниц