PHPTime

Генерация спрайтов в 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-зависимости проекта:

Shell
npm install --save-dev spritesmith

Минимальный сценарий сборки — обычный Node.js-скрипт. Он принимает список исходных изображений и формирует спрайт вместе с картой позиций:

PHP
<?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 выглядит так:

Shell
// 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}`);

Запуск — обычной командой:

Shell
node sprite-build.mjs

Полученный sprite.json содержит координаты каждой иконки в общем полотне. Эти данные передаются в Stylus через переменные или миксины.

Интеграция со Stylus без deprecated-зависимостей

Вместо заброшенных плагинов используйте обычный Stylus и подключайте карту позиций как JSON. Современные версии Stylus корректно работают с JSON-объектами, переданными из Node.js:

PHP
<?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 миксин для использования спрайта выглядит лаконично:

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

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

Shell
// 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. Координаты при этом не меняются — кодирование без потерь сохраняет геометрию:

Shell
// Конвертация спрайта в 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 или фолбэк:

PHP
// 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 или другой конвертер. Координаты изображений при этом не меняются.

Справка по теме

Ещё в разделе «Фронтенд»

Плавающий интерфейс: как упорядочить разработку frontend + backend

Как организовать взаимодействие фронтенда и бэкенда через единый PHP-класс-контракт. Практический подход с расширениями, типами и DTO для современных проектов 2026 года.

6 мин

Система сборки фронтенда для PHP-проекта: от Grunt до современных таск-раннеров

Как подключить систему сборки CSS и JavaScript к бэкенду на PHP 8.3–8.5: минификация, конкатенация, версионирование ассетов и автодеплой в 2026 году.

6 мин

Stylus в 2026 году: стоит ли использовать CSS-препроцессор в современной разработке

Разбираем CSS-препроцессор Stylus в реалиях 2026 года: установка, синтаксис, БЭМ, миксины, подводные камни и сравнение с Sass. Практический чек-лист для разработчика.

5 мин

Правила именования CSS-классов и организации файлов стилей

Практические правила именования CSS-классов, структурирования файлов стилей и подключения ассетов в современных PHP-проектах. Разбор на примерах.

7 мин