Руководство по Nunjucks

Что вы построите

Небольшая контактная форма, отрисованная на сервере, — поле с меткой, кнопка отправки, ноль нагрузки JavaScript — сначала голая, затем оформленная, примерно за 10 минут.

Прежде чем начать

Вам понадобятся git, Node 22 или новее и pnpm 10 или новее. Подойдёт любой конвейер Nunjucks — Eleventy, Express или обычный Nunjucks.

Шаг 1 — Получите код

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-nunjucks-headless
pnpm install
pnpm test        # vitest rendering every macro

Каждый компонент — это каталог в components/ с macro.njk, его тестом и его документацией — например components/button/macro.njk. Направьте загрузчик Nunjucks на components/ (в Eleventy добавьте его в путь includes) и импортируйте нужное.

Шаг 2 — Ваш первый компонент

{% from "components/button/macro.njk" import button %}

{{ button({ text: "Save", type: "submit" }) }}

Отображает <button class="button" type="submit">Save</button>. Макросы принимают единственный объект params: text (экранированный) или html (необработанный), type, label для aria-labelи добавитель крючка класса.

Шаг 3 — Составьте небольшую форму

{% from "components/form/macro.njk" import form %}
{% from "components/label/macro.njk" import label %}
{% from "components/text-input/macro.njk" import textInput %}
{% from "components/button/macro.njk" import button %}

<form class="form" method="post">
  <div class="field">
    {{ label({ for: "name", text: "Full name" }) }}
    {{ textInput({ id: "name", name: "name", required: true }) }}
  </div>
  {{ button({ text: "Save", type: "submit" }) }}
</form>

Поскольку всё отрисовывается на сервере, браузер получает чистый семантический HTML с крючками классов — нагрузка JavaScript в ноль байт.

Проверьте свою работу: загрузите страницу, и форма выглядит голой — именно так, как задумано: оформление ещё впереди. Нажмите Tab: фокус проходит через каждый элемент управления, метка озвучивается, а отправка работает. Поведение готово; внешний вид за вами, и это следующий шаг.

Шаг 4 — Оформите её

Оформите крючки — .button, .text-input, .label, .field — в вашей таблице стилей, или подключите готовую тему в базовом макете:

<link rel="stylesheet" href="/themes/united-kingdom-government-digital-service.css" />

Шаг 5 — Посмотрите, как всё работает

Пример приложения Nunjucks + Eleventy собирает полный каталог как статический сайт с демонстрационными страницами для каждого компонента:

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-nunjucks-eleventy-examples
pnpm install && pnpm run dev

Дальнейшие шаги

Темы — включая шаблон cookie Eleventy для переключения темы SSR без мерцания.
Помощники настроек — язык и размер текста.
Каталог компонентов — свойства, ARIA и клавиатура для каждого компонента.

Есть вопросы по ходу дела? Страница справки полна ответов — а если какой-то шаг можно сделать яснее, сообщите нам и мы с радостью улучшим руководство.