README

Современный стартовый набор для создания веб-приложений на Laravel. Включает в себя все необходимые инструменты для разработки, сборки и деплоя.

Laravel Starter Kit - готовый к использованию шаблон проекта с предустановленными компонентами, стилями и утилитами для быстрого старта разработки.

🚀 Особенности

Laravel 12 - современный PHP фреймворк
Blade компоненты - переиспользуемые UI компоненты
Vue 3 - реактивные компоненты (опционально)
SCSS - препроцессор для стилей с BEM методологией
Vite - быстрый сборщик для фронтенда
PHPStan - статический анализ PHP кода
Laravel Pint - форматирование PHP кода

📋 Требования

PHP: ^8.3
Composer
Node.js: ^20.19.0 || >=22.12.0 (для фронтенда)
npm или yarn

🛠 Установка

Быстрая установка через Laravel Installer

Установите Laravel Installer (если еще не установлен):

composer global require laravel/installer

Создайте новый проект с помощью starter kit:

laravel new my-project --using=mTresk/laravel-starter-kit
cd my-project

Запустите проект в режиме разработки:

composer run dev

Проект будет доступен по адресу http://localhost:8000

📜 Доступные команды

Разработка

php artisan serve - запуск Laravel сервера
composer run dev - запуск полного стека разработки (Laravel + Vite + Queue + Logs)
npm run dev - запуск Vite dev сервера для фронтенда

Сборка

npm run build - сборка фронтенда (включает оптимизацию и линтинг)
npm run build:vite - только сборка Vite

Анализ кода

composer run analyse - статический анализ PHP (PHPStan + Pint)
npm run lint - проверка фронтенда (ESLint + Stylelint)
npm run lint:fix - автоматическое исправление фронтенда

Утилиты

npm run fonts - генерация woff2 шрифтов из исходников
npm run px-to-rem - конвертация px в rem
npm run fix-all - полная оптимизация (px-to-rem + линтинг)

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

├── app/                # Laravel приложение
│   ├── Http/           # HTTP контроллеры
│   ├── Models/         # Eloquent модели
│   └── Providers/      # Сервис провайдеры
├── database/           # База данных
│   ├── migrations/     # Миграции
│   ├── factories/      # Фабрики для тестов
│   └── seeders/        # Сидеры
├── public/             # Публичные файлы
│   ├── build/          # Собранные ресурсы (Vite)
│   ├── images/         # Статические изображения
│   └── index.php       # Точка входа Laravel
├── resources/          # Ресурсы для компиляции
│   └── views/          # Blade шаблоны
│       ├── components/ # Blade компоненты
│       │   ├── form/   # Формы и инпуты
│       │   ├── layout/ # Компоненты макета
│       │   ├── ui/     # UI компоненты
│       │   └── ...     # Остальные компоненты
│       └── *.blade.php # Страницы
├── routes/             # Маршруты
│   └── web.php         # Web маршруты
├── src/                # Фронтенд ресурсы
│   ├── app.ts          # Инициализация JavaScript приложения
│   ├── vue.ts          # Инициализация Vue компонентов
│   ├── assets/         # Ресурсы для обработки
│   │   ├── fonts/      # Оптимизированные шрифты (woff2)
│   │   ├── fonts-raw/  # Исходные шрифты (ttf/otf)
│   │   ├── icons/      # SVG иконки
│   │   └── images/     # Изображения для разработки
│   ├── styles/         # SCSS стили
│   │   ├── helpers/    # Переменные, миксины
│   │   ├── libs/       # Стили библиотек
│   │   └── index.ts    # Точка входа стилей
│   └── utils/          # JavaScript утилиты
│       ├── base/       # Базовые скрипты
│       ├── forms/      # Работа с формами
│       ├── libs/       # JavaScript библиотеки
│       └── tasks/      # Задачи сборки
├── storage/            # Файлы приложения
├── tests/              # Тесты (Pest)
└── vendor/             # Composer зависимости

Разница между папками

public/ - статические файлы, доступные напрямую через веб-сервер
resources/ - Blade шаблоны и ресурсы для компиляции
src/ - фронтенд ресурсы (CSS, JS), обрабатываемые Vite

🎨 Стилизация

Проект использует SCSS с BEM методологией для стилизации.

Основные файлы стилей:

src/styles/helpers/variables.scss - SCSS переменные
src/styles/helpers/mixins.scss - SCSS миксины
src/styles/colors.scss - цветовая палитра
src/styles/fonts.scss - стили шрифтов (генерируются через npm run fonts)
src/styles/globals.scss - глобальные стили
src/styles/null.scss - сброс стилей

🧩 Компоненты

Blade компоненты:

Layout компоненты:

main - основной макет страницы с мета-тегами и структурой
header - шапка сайта
footer - подвал сайта
breadcrumb - хлебные крошки
content - контентная секция

UI компоненты:

icon - SVG иконки из спрайта
button - кнопки различных типов
menu-button - кнопка меню

Form компоненты:

form-field - поля форм
checkbox - чекбоксы
radio - радиокнопки
select - селекты
quantity - счетчики количества
range - слайдеры диапазонов

Интерактивные компоненты:

accordion - аккордеоны с анимацией
popup - модальные окна
map - интеграция с картами

Использование:

Icon

Для использования иконок:

Добавьте SVG символы в файл public/images/icons.svg
Используйте Blade компонент Icon:

<x-ui.icon name="close" size="24" />
<x-ui.icon name="pin" width="32" height="32" />

Props:

name - ID символа в icons.svg
size - размер иконки в пикселях (приоритет над width/height)
width - ширина иконки
height - высота иконки

Структура icons.svg:

<svg xmlns="http://www.w3.org/2000/svg">
    <symbol id="close" viewBox="0 0 20 20">
        <path d="..." fill="currentColor" />
    </symbol>
    <symbol id="pin" viewBox="0 0 40 40">
        <path d="..." fill="currentColor" />
    </symbol>
</svg>

Accordion

Компонент аккордеона с плавной анимацией открытия/закрытия. Поддерживает различные режимы работы и настройки анимации.

Структура компонентов:

accordion-root - корневой контейнер для группы аккордеонов
accordion - отдельный элемент аккордеона

Базовое использование:

<x-accordion.accordion-root is-single is-close-outside duration="500">
    <x-accordion.accordion>
        <x-slot name="header">
            <h3>Заголовок 1</h3>
        </x-slot>
        <x-slot name="content">
            <p>Содержимое первого аккордеона</p>
        </x-slot>
    </x-accordion.accordion>

    <x-accordion.accordion>
        <x-slot name="header">
            <h3>Заголовок 2</h3>
        </x-slot>
        <x-slot name="content">
            <p>Содержимое второго аккордеона</p>
        </x-slot>
    </x-accordion.accordion>
</x-accordion.accordion-root>

AccordionRoot Props:

is-single - режим "только один открытый" (по умолчанию false)
is-close-outside - закрытие по клику вне области (по умолчанию false)
duration - длительность анимации в миллисекундах (по умолчанию 300)

Особенности:

✅ Плавная анимация с использованием max-height
✅ Поддержка множественных аккордеонов на странице
✅ Автоматическая инициализация через JavaScript класс
✅ Синхронизация CSS и JavaScript анимации
✅ Доступность (semantic HTML с <details> и <summary>)

🧩 Vue компоненты (опционально)

Проект поддерживает использование Vue 3 компонентов в Blade шаблонах для создания интерактивных элементов.

Подключение Vue

Vue настроен в src/vue.ts и подключается через Vite
Создайте Vue компонент в папке src/components/
Зарегистрируйте компонент в src/vue.ts
Используйте компонент в Blade шаблоне

Пример использования

Создание Vue компонента:

<!-- src/components/VueExample.vue -->
<template>
  <h2>Пример Vue компонента в Laravel</h2>
</template>

Регистрация в vue.ts:

// src/vue.ts
import { createApp } from 'vue'
import VueExample from '@/components/VueExample.vue'

const VueExampleInstance = createApp({
  components: {
    'component-example': VueExample,
  },
})

if (document.querySelector('#example-component')) {
  VueExampleInstance.mount('#example-component')
}

Использование в Blade:

<x-layout.main title="Пример">
    <div id="example-component">
        <component-example />
    </div>
</x-layout.main>

🔤 Работа со шрифтами

Подготовка шрифтов

Поместите исходные шрифты в папку src/assets/fonts-raw/ в формате TTF или OTF
Запустите генерацию оптимизированных шрифтов:
```
npm run fonts
```
Оптимизированные шрифты (WOFF2) будут созданы в папке src/assets/fonts/

Использование шрифтов

После генерации шрифты автоматически подключаются в проекте. Используйте их в CSS:

// В styles/fonts.scss
@font-face {
  font-family: 'Inter';
  src: url('@/assets/fonts/Inter-Regular.woff2') format('woff2');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

@font-face {
  font-family: 'Inter';
  src: url('@/assets/fonts/Inter-Bold.woff2') format('woff2');
  font-weight: 700;
  font-style: normal;
  font-display: swap;
}

🔧 Утилиты

JavaScript библиотеки (в src/utils/libs/):

Accordion - нативные аккордеоны с анимацией
Gallery - lightbox галерея изображений
Map - инициализация Yandex Карт
Menu - логика бургер-меню
Parallax - параллакс эффекты
Popup - управление модальными окнами
Quantity - счетчики количества
ResponsiveAdapter - изменения порядка элементов на определенной ширине
Scroll - навигация и направление скрола
ScrollWatcher - отслеживание скрола
ShowMore - показать еще
Spoilers - JS аккордеоны
Tabs - табы

Формы (в src/utils/forms/):

DatePicker - выбор даты
InputMask - маски ввода
Range - диапазоны
Select - JavaScript селект

Базовые утилиты (в src/utils/base/):

helpers - вспомогательные функции
scrollbar - кастомные скроллбары
sliders - слайдеры
tippy - тултипы

📖 Документация по использованию: snippets.maximtresk.ru

Активация утилит

Для активации утилит раскомментируйте соответствующие строки в src/app.ts:

// src/app.ts
function initializeApp() {
  new Accordion() // уже активен
  // new Gallery()
  // new Map()
  // new Menu()
  // new Parallax({})
  // new Popup()
  // new ResponsiveAdapter('max')
  // new ScrollWatcher({})
  // new ShowMore()
  // new Spoilers()
  // new Tabs()
  // new Quantity()
  // const scroll = new Scroll()
}

⚙️ Конфигурация

Vite (vite.config.js)

Поддержка Vue 3 компонентов
Автоматическая оптимизация изображений
SCSS препроцессор с глобальными переменными
Алиасы путей (@ для src/)

ESLint & Stylelint

Конфигурация @antfu/eslint-config
SCSS линтинг
Автоформатирование

🎯 SEO

Laravel SEO

Blade директивы - управление мета-тегами
Open Graph - поддержка социальных сетей

Использование в Blade

<x-layout.main title="Заголовок страницы" description="Описание страницы" og-title="'Заголовок для соцсетей'"
    og-description="'Описание для соцсетей'">
    <!-- Контент страницы -->
</x-layout.main>

📚 Дополнительные ресурсы

📄 Лицензия

MIT License

Создано с ❤️ для современной веб-разработки на Laravel

mtresk / laravel-starter-kit

Maintainers

Details