Генерация спрайтов в Stylus: практическое руководство для PHP-разработчика
Спрайты по-прежнему экономят HTTP-запросы, а с HTTP/2 и HTTP/3 выгода смещается в сторону кэширования и удобства управления иконками. Рассказываю, как организовать генерацию спрайтов в связке со Stylus без боли и deprecated-плагинов. В конце — чек-лист для внедрения в ваш проект.
Зачем спрайты в 2026 году
Казалось бы, с повсеместным внедрением HTTP/2 мультиплексирование должно было убить спрайты. Но практика показала: десятки отдельных файлов иконок создают другую проблему — управление кэшем, накладные расходы на загрузку метаданных и усложнение деплоя. Один файл спрайта проще версионировать, он быстрее отдаётся с CDN, а парсинг одного CSS-правила обходится браузеру дешевле, чем разбор сотни мелких.
Кроме того, спрайты незаменимы для анимации по кадрам, когда каждая фаза движения — это отдельное изображение в общем полотне. SVG-спрайты решают часть задач с масштабированием, но растровые иконки и элементы интерфейса с пиксельной точностью всё ещё востребованы.
Почему не встроенные возможности Stylus
В Stylus нет встроенной команды для склейки изображений. Функция url() может преобразовать файл в data-uri, но это не полноценный спрайт: каждая картинка кодируется в base64 и встраивается прямо в стили. Такой подход увеличивает размер CSS, усложняет обновление изображений и мешает отладке в DevTools.
Ожидать появления нативного механизма генерации спрайтов в препроцессоре не стоит: Stylus уже давно находится в режиме поддержки, основные силы сообщества переключились на PostCSS и сборщики. Поэтому генерация спрайтов выносится на уровень сборки — туда, где ей и место.
Современная архитектура: PostCSS как замена плагинам
Исторически для Stylus использовались расширения вроде stylus-sprite и stylus-lemonade. Оба плагина были основаны на библиотеке libgd для Node.js и требовали установки нативных зависимостей. Сейчас оба решения заброшены: stylus-sprite объявлен устаревшим, stylus-lemonade тоже не развивается. Использовать их в новых проектах не стоит — проблемы с установкой libgd на современных версиях Node.js и отсутствие поддержки актуальных форматов изображений перевешивают возможную выгоду.
Актуальный подход — генерировать спрайты отдельным инструментом, который не привязан к препроцессору. Самый зрелый из таких инструментов — spritesmith. Он работает с PNG, JPEG и WebP, поддерживает несколько алгоритмов упаковки и умеет отдавать метаданные в разных форматах — от чистого JSON до готовых миксинов для Stylus, SCSS и Less.
Для PHP-разработчика это означает, что фронтенд-сборка больше не зависит от серверного стека. Вы можете спокойно генерировать спрайты в окружении Node.js, а PHP отдаёт только готовые CSS и PNG. Никакого взаимодействия с графическими библиотеками на сервере.
Настройка генерации спрайтов с spritesmith
Установите движок в dev-зависимости проекта:
npm install --save-dev spritesmithМинимальный сценарий сборки — обычный Node.js-скрипт. Он принимает список исходных изображений и формирует спрайт вместе с картой позиций:
<?php
// Этот пример — псевдокод на PHP, показывающий логику.
// Реальная сборка выполняется в Node.js.
// Здесь лишь демонстрация, как PHP-разработчик может
// представить себе процесс генерации.
$icons = glob(__DIR__ . '/icons/*.png');
sort($icons);
// Псевдовызов: $result = Spritesmith::process($icons);
// В реальности это делается npm-пакетом.
// Результат: $result['image'] — Buffer, $result['coordinates'] — массив,
// $result['properties'] — размеры спрайта.На практике скрипт на Node.js выглядит так:
// sprite-build.mjs
import Spritesmith from 'spritesmith';
import fs from 'node:fs/promises';
import path from 'node:path';
const sourceDir = './icons';
const files = (await fs.readdir(sourceDir))
.filter(f => f.endsWith('.png'))
.sort();
const sprite = await new Promise((resolve, reject) => {
Spritesmith.run({
src: files.map(f => path.join(sourceDir, f)),
algorithm: 'binary-tree',
padding: 4
}, (err, result) => err ? reject(err) : resolve(result));
});
await fs.writeFile('./dist/sprite.png', sprite.image);
await fs.writeFile('./dist/sprite.json', JSON.stringify({
coordinates: sprite.coordinates,
properties: sprite.properties
}, null, 2));
console.log(`Спрайт собран: ${sprite.properties.width}x${sprite.properties.height}`);Запуск — обычной командой:
node sprite-build.mjsПолученный sprite.json содержит координаты каждой иконки в общем полотне. Эти данные передаются в Stylus через переменные или миксины.
Интеграция со Stylus без deprecated-зависимостей
Вместо заброшенных плагинов используйте обычный Stylus и подключайте карту позиций как JSON. Современные версии Stylus корректно работают с JSON-объектами, переданными из Node.js:
<?php
// Пример PHP-скрипта, который подключает Stylus через Node.js
// и передаёт данные спрайта в компиляцию.
// Это не выполняется прямо в PHP, но показывает интеграцию.
declare(strict_types=1);
$spriteJson = file_get_contents(__DIR__ . '/dist/sprite.json');
$spriteData = json_decode($spriteJson, true, 512, JSON_THROW_ON_ERROR);
$coords = $spriteData['coordinates'] ?? [];
// Данные передаются в Node.js-скрипт компиляции Stylus
// через переменные окружения или временный файл.В Stylus миксин для использования спрайта выглядит лаконично:
// stylus/sprites.styl
sprite($name, $coords = $sprite-coords, $sprite-path = $sprite-file)
$pos = $coords[$name]
background: url($sprite-path) no-repeat
background-position: -($pos.x)px -($pos.y)px
width: $pos.width px
height: $pos.height px
// Использование
.icon-search
sprite('search.png')
.icon-close
sprite('close.png')Передача переменных из Node.js:
// stylus-compile.mjs
import stylus from 'stylus';
import fs from 'node:fs/promises';
const spriteJson = JSON.parse(await fs.readFile('./dist/sprite.json', 'utf-8'));
const source = await fs.readFile('./styles/main.styl', 'utf-8');
stylus(source)
.set('filename', 'main.styl')
.define('sprite-coords', spriteJson.coordinates)
.define('sprite-file', new stylus.nodes.String('../img/sprite.png'))
.render((err, css) => {
if (err) throw err;
await fs.writeFile('./dist/main.css', css);
});Такой подход не зависит от внешних плагинов для Stylus и работает с официальной версией препроцессора. Обновление спрайта сводится к повторному запуску сборки.
Альтернативы: Gulp и другие сборщики
Если вы используете Gulp, для spritesmith есть обёртка gulp.spritesmith. Она упрощает конвейер: результат генерации сразу передаётся в буфер, а метаданные — в поток для Stylus:
// gulpfile.mjs
import gulp from 'gulp';
import spritesmith from 'gulp.spritesmith';
import stylus from 'gulp-stylus';
import buffer from 'vinyl-buffer';
import merge from 'merge-stream';
const spriteData = gulp.src('./icons/*.png')
.pipe(spritesmith({
imgName: 'sprite.png',
cssName: '_sprite.styl',
algorithm: 'binary-tree',
padding: 2,
cssTemplate: (data) => {
// data.sprites содержит координаты каждой иконки
const coords = data.sprites.map(s =>
`$sprite-${s.name} = { x: ${s.x}, y: ${s.y}, w: ${s.width}, h: ${s.height} }`
).join('\n');
return coords;
}
}));
const imgStream = spriteData.img.pipe(buffer())
.pipe(gulp.dest('./dist/img'));
const cssStream = spriteData.css
.pipe(gulp.dest('./styles/generated'));
export const sprite = () => merge(imgStream, cssStream);Преимущество Gulp-подхода — всё в одном конвейере: спрайт генерируется, переменные для Stylus создаются автоматически, и компиляция стилей запускается сразу после этого. Не нужно вручную синхронизировать JSON-файлы.
Сравнение подходов к генерации спрайтов
| Инструмент | Статус | Зависимости | Гибкость |
|---|---|---|---|
stylus-sprite | Заброшен | libgd, node-gd | Низкая, один спрайт на файл |
stylus-lemonade | Заброшен | libgd, форк Stylus | Средняя, несколько спрайтов |
spritesmith (Node API) | Активен | Только npm | Высокая, любые форматы и алгоритмы |
gulp.spritesmith | Активен | Только npm | Высокая, интеграция с конвейером |
Как видно, выбор очевиден: решения, встроенные в Stylus, мертвы. Внешние инструменты не только живы, но и активно развиваются, поддерживают WebP и AVIF, что критично для современной веб-разработки.
WebP и AVIF в спрайтах: что важно знать
Классические спрайты — это PNG. Но в 2026 году форматы WebP и AVIF используются повсеместно. Поддержка сжатия в spritesmith зависит от движка: базовый pixelsmith работает только с PNG. Для WebP можно использовать форк или внешний конвертер.
Практичный компромисс: генерируйте спрайт в PNG, а затем конвертируйте его в WebP с помощью sharp или avifenc. Координаты при этом не меняются — кодирование без потерь сохраняет геометрию:
// Конвертация спрайта в WebP после генерации
import sharp from 'sharp';
const png = await fs.readFile('./dist/sprite.png');
await sharp(png).webp({ quality: 90, lossless: false }).toFile('./dist/sprite.webp');В CSS добавляйте оба формата через image-set или фолбэк:
// stylus/sprite.styl
sprite($name, $coords = $sprite-coords)
$pos = $coords[$name]
width: $pos.width px
height: $pos.height px
background-image: url('../img/sprite.png')
background-image: image-set(url('../img/sprite.png') 1x, url('../img/sprite.webp') 1x)
background-position: -($pos.x)px -($pos.y)px
background-repeat: no-repeatБраузер, поддерживающий image-set, выберет WebP автоматически. Для старых браузеров останется PNG-версия.
Чек-лист внедрения
- Проверьте, нужны ли вам именно растровые спрайты: если иконки векторные, рассмотрите SVG-спрайт на
<symbol>сuse. - Используйте
spritesmithилиgulp.spritesmith— не берите заброшенные Stylus-плагины с libgd. - Храните исходные иконки в отдельной директории, а генерируемые файлы — в
dist, не коммитьте артефакты в репозиторий. - Передавайте координаты в Stylus как JSON-переменные или сгенерированный styl-файл.
- Добавьте WebP-версию спрайта для современных браузеров.
- Запускайте сборку спрайтов перед компиляцией стилей в CI/CD конвейере.
- Версионируйте имя файла спрайта (например,
sprite-{hash}.png), чтобы избежать проблем с кэшем. - Оптимизируйте упаковку: выбирайте
binary-treeдля плотной компоновки илиtop-downдля предсказуемости координат. - Документируйте добавление новых иконок в README — процесс должен быть одинаковым для всей команды.
Частые вопросы
Можно ли генерировать спрайты только средствами Stylus?
Нет, в Stylus нет встроенной генерации спрайтов. Единственная встроенная возможность — конвертация изображения в data-uri через url(), но это не спрайт. Для склейки нужны внешние инструменты на уровне сборки.
Почему не стоит использовать stylus-sprite и stylus-lemonade?
Оба плагина заброшены авторами и требуют установки графической библиотеки libgd, что создаёт проблемы на современных версиях Node.js и операционных систем. Вместо них используйте spritesmith или его обёртки для Gulp.
Как передать координаты спрайта в Stylus?
Сгенерируйте карту позиций в JSON или styl-файле с переменными, затем передайте через define() в Node.js API Stylus или подключите как обычный styl-файл. Координаты каждой иконки передаются в пикселях.
Поддерживает ли spritesmith WebP и AVIF?
Базовый движок pixelsmith работает только с PNG. Для WebP и AVIF используйте постобработку готового PNG-спрайта через sharp или другой конвертер. Координаты изображений при этом не меняются.