Как использовать шаблоны Templates в Nuxt

Введение

Nuxt значительно упрощает разработку современных Vue-приложений — одна из его сильных сторон заключается в гибких возможностях шаблонизации. Шаблоны (templates) в Nuxt — это не только уже встроенные механизмы формирования страниц, но и инструмент, с помощью которого вы можете расширять проект, автоматизировать работу и добавлять кастомный функционал. В этой статье мы подробно разберём, где используются шаблоны в Nuxt, как с ними работать, какие бывают сценарии использования, а также приведём практические примеры, чтобы вы могли быстро и эффективно применять шаблоны в своих проектах.

Зачем нужны шаблоны в Nuxt?

Шаблоны в Nuxt отвечают за автоматическую генерацию содержимого — например, отдельных файлов при сборке, HTML-шеллов страниц, мета-тегов, настроек конфигурации и даже серверных обработчиков. Другими словами, это участки кода, которые могут автоматически дополняться, изменяться или полностью создаваться в момент сборки или запуска приложения.

Смотрите, почему именно с помощью шаблонов можно:

• Автоматически генерировать файлы, которые до этого приходилось создавать вручную
• Использовать переменные окружения или данные из nuxt.config при формировании итогового файла или страницы
• Кастомизировать базовые файлы (например, app.html, error.vue) под ваши нужды
• Использовать шаблоны плагинов для подключения сторонних решений или обёрток над функционалом

Теперь давайте посмотрим подробнее, как это реализовано в Nuxt.

Шаблоны - это основа для создания пользовательского интерфейса в Nuxt-приложениях. Но для создания действительно красивых и функциональных шаблонов необходимо понимать, как работает синтаксис Vue, как использовать компоненты и как интегрировать шаблоны с другими частями вашего приложения. Если вы хотите узнать больше о том, как использовать шаблоны в Nuxt, приходите на наш большой курс Nuxt - fullstack Vue фреймворк. На курсе 129 уроков и 13 упражнений, AI-тренажеры для безлимитной практики с кодом и задачами 24/7, решение задач с живым ревью наставника, еженедельные встречи с менторами.

Основные типы шаблонов в Nuxt

Nuxt использует несколько направлений шаблонизации. Рассмотрим основные варианты:

1. Генерация файлов на лету: директория templates

Внутри директорий ваших модулей, а порой и в корне проекта (например, если вы делаете собственный шаблонный проект) можно разместить папку templates. Всё, что лежит внутри, будет обработано Nuxt во время сборки, а в результирующую папку .nuxt попадут сгенерированные файлы с подставленными переменными.

Как работает templates в Nuxt?

Nuxt копирует файлы-исходники из папки templates, заменяя в них специальные маркеры переменными, которые вы укажете. Например, вы можете создать шаблонный файл с подстановками:

// templates/custom-inject.js
export default () => {
  // Используем специальные маркеры <% %> для шаблонных переменных
  return `<template>
    <div>Hello from <%= name %> template!</div>
  </template>`
}

При этом при добавлении этого шаблона в модуль или при расширении сборки Nuxt вы можете передать объект с данными для этих переменных:

// nuxt.config.js или модуль
export default defineNuxtConfig({
  hooks: {
    'nitro:config'(nitroConf) {
      nitroConf.templates = [
        {
          src: './templates/custom-inject.js', // Путь к шаблону
          dst: 'custom-inject.js', // Куда сохранять файл в .nuxt/
          options: { name: 'MyAwesome' }
        }
      ]
    }
  }
})

Nuxt самостоятельно просканирует файл, заменит <%= name %> на MyAwesome, и положит полученный результат в .nuxt/custom-inject.js.

Использование шаблонов в модулях

Частый кейс — вы делаете Nuxt-модуль, и хотите, чтобы он генерировал динамические файлы (например, плагины с вашим кодом). Давайте разберем процесс на практике.

1. В модуле создайте templates/my-plugin.js:

// templates/my-plugin.js
export default defineNuxtPlugin(nuxt => {
  // <% pluginMessage %> будет заменён на содержимое из опций
  console.log('<%= pluginMessage %>')
})

2. При подключении модуля укажите генерацию шаблона:

// Внутри setup() вашего Nuxt-модуля
nuxt.options.build.templates.push({
  src: resolve(__dirname, 'templates/my-plugin.js'),
  fileName: 'my-plugin.js',
  options: {
    pluginMessage: 'Привет из вашего плагина!'
  }
})

3. Nuxt сгенерирует соответствующий файл в .nuxt/my-plugin.js, где <%= pluginMessage %> будет заменён на строку из ваших опций.

Формат шаблонов

В шаблоны обычно вставляют переменные с помощью выражений вида <%= variable %>. Используется ejs-подобный синтаксис. Вы можете проводить простые вычисления, добавлять условия и другие описания.

2. Настраиваем app.html — HTML-шелл приложения

В корне проекта можно создать свой файл app.html. Он заменит стандартный HTML-шаблон, который Нuxt генерирует сам.

Это мощный способ полностью контролировать HTML-структуру root-документа. Например, для внедрения нестандартной разметки, дополнительных метатегов, CDN, подключения аналитики и других кастомных скриптов.

Пример:

<!-- app.html -->
<!DOCTYPE html>
<html {{ HTML_ATTRS }}>
  <head {{ HEAD_ATTRS }}>
    {{ HEAD }}
    <link rel="stylesheet" href="https://cdn.example.com/styles.css">
  </head>
  <body {{ BODY_ATTRS }}>
    <div id="__nuxt">{{ APP }}</div>
    <!-- Можно добавить свой шаблонный блок: -->
    <script>
      window.myConfig = '{{ MY_CUSTOM_CONFIG }}'
    </script>
  </body>
</html>

Как видите, значки {{ VAR }} — это специальные плейсхолдеры Nuxt, которые будут автоматически подставлены при формировании страницы (например, {{ APP }} — основной Vue-приложение, {{ HEAD }} — мета-теги и т.д.).

3. Генерация Error страниц и кастомизированных layout

Вы можете создавать и автоматически использовать шаблоны для error-страниц (например, кастомный error.vue в директории layouts или pages). Nuxt при необходимости сам подставит этот layout для страниц с ошибками.

Пример файла:

<!-- layouts/error.vue -->
<template>
  <div class="error-page">
    <h1>Ошибка {{ error.statusCode }}</h1>
    <p>{{ error.message }}</p>
    <!-- Можно добавить кастомный шаблонный контент -->
  </div>
</template>
<script setup>
defineProps({
  error: Object
})
</script>

4. Кастомизация конфигурационных файлов с помощью шаблонов

С помощью шаблонов можно влиять даже на содержимое конфигурационных или серверных файлов:

// В модуле
build: {
  templates: [
    {
      src: resolve(__dirname, 'templates/server-middleware.js'),
      fileName: 'middleware/generated-mw.js',
      options: { middlewareParam: 'custom value' }
    }
  ]
}

Здесь при сборке middleware-файл будет автоматически сформирован с вашими параметрами.

5. Использование шаблонов для Nuxt-плагинов

Когда вы добавляете плагины через модуль или кастомировку, вы можете использовать шаблоны, чтобы подстраивать плагин под параметры пользователя.

Пример простого плагина-шаблона:

// templates/dynamic-api.js
export default defineNuxtPlugin(nuxtApp => {
  // <%= apiBase %> будет заменён на значение
  nuxtApp.provide('apiBase', '<%= apiBase %>')
})

Код добавления из модуля:

// В модулях
nuxt.options.build.templates.push({
  src: resolve(__dirname, 'templates/dynamic-api.js'),
  fileName: 'dynamic-api.js',
  options: { apiBase: 'https://api.mysite.ru/v1/' }
})

Теперь вы сможете во всех компонентах получать значение через inject:

const apiBase = inject('apiBase') // будет https://api.mysite.ru/v1/

Варианты подключения и генерации шаблонов

Через модули

Большинство кастомных шаблонов встраиваются через Nuxt-модули. Ваш модуль может добавлять к сборке файлы, которых нет изначально, а также генерировать кастомные плагины, middleware, utils и другие артефакты на основе параметров конфигурации пользователя.

Через nuxt.config

В определённых случаях, если шаблон нужен "просто так", можно добавить его к сборке через hooks в nuxt.config, воспользовавшись событиями типа build:before, nitro:config и т.д.

Пример добавления шаблона через хук:

// nuxt.config.js
export default defineNuxtConfig({
  hooks: {
    // В момент конфигурации nitro
    'nitro:config'(conf) {
      conf.templates = conf.templates || []
      conf.templates.push({
        src: './templates/custom-env.js',
        dst: 'custom-env.js',
        options: { apiKey: process.env.MY_API_KEY }
      })
    }
  }
})

Через специальные директории

Некоторые шаблоны (например, для кастомизации app.html или error.vue) нужно разместить строго в корневых директориях проекта и Nuxt автоматически их подхватит.

Лучшие практики и советы

• Используйте шаблоны для генерации файлов, которые сильно зависят от окружения или разных опций пользователя.
• Для пакетов и модулей Nuxt не кладите все шаблоны в одну кучу: разделяйте их по назначению (plugins, middleware, utils).
• В шаблоне избегайте передачи избыточных данных, чтобы не раскрывать чувствительные значения в итоговых файлах.
• Проверяйте шаблон на синтаксис перед добавлением в проект — ошибки в ejs-блоках сильно усложняют отладку.
• Используйте шаблоны для «обёртывания» сторонних библиотек: можно автоматически подставлять api-ключи, пути к сервисам, различные переменные.

Заключение

Шаблоны (templates) в Nuxt открывают множество возможностей для автоматизации рутины, инкапсуляции логики и адаптации проекта под любые требуемые параметры. С помощью шаблонов вы можете динамически формировать плагины, middleware, кастомные конфигурации, управлять HTML-шеллом приложения и многим другим. Эти средства особенно полезны при создании собственных модулей, интеграций с сервисами, организации многоразовых решений внутри одной или нескольких команд. Старайтесь применять шаблоны там, где это действительно упрощает архитектуру — и вы получите максимально гибкое и легко расширяемое Nuxt-приложение.

Шаблоны - это важная часть Nuxt-приложений, но это не единственная. Чтобы создавать гибкие и масштабируемые приложения, необходимо освоить все возможности фреймворка, включая работу с сервером, базами данных и API. На нашем курсе Nuxt - fullstack Vue фреймворк вы найдете все необходимые знания и навыки для достижения успеха. В первых 3 модулях уже доступно бесплатное содержание — начните погружаться в Nuxt прямо сегодня.

Частозадаваемые технические вопросы по теме шаблонов и их ответы

Вопрос 1. Как задать условия (if/else) внутри шаблона?

В шаблонах Nuxt можно использовать стандартные ejs-конструкции. Например:

// В шаблоне .js
<% if (isDev) { %>
console.log('Development mode!');
<% } else { %>
console.log('Production mode!');
<% } %>

Передайте isDev через options — условие выполнится корректно.

Вопрос 2. Почему шаблон не применяется, если файл лежит вне модуля?

Nuxt автоматически ищет шаблоны только в специальных директориях или внутри модулей. Если вы хотите интегрировать кастомный шаблон из произвольного места, воспользуйтесь хуками (например, в nuxt.config — build:before или nitro:config), и явно укажите путь к вашему шаблону.

Вопрос 3. Как изменить сгенерированный шаблон после сборки?

После сборки файлы попадают в папку .nuxt. Не изменяйте их вручную — используйте для этого свои шаблоны/модули или создайте плагин, который дополнительно меняет поведение при старте.

Вопрос 4. Можно ли использовать шаблоны для генерации динамических route-файлов?

Да. Шаблоны подходят для генерации любых файлов, в том числе routes. Например, при интеграции с CMS — генерируйте маршрут на каждый опубликованный материал через шаблон, получая данные из внешнего API на этапе сборки.

Вопрос 5. Какие переменные доступны в шаблоне app.html?

В шаблоне app.html доступны плейсхолдеры: {{ HTML_ATTRS }}, {{ HEAD_ATTRS }}, {{ HEAD }}, {{ BODY_ATTRS }}, {{ APP }} и переменные, которые вы явно передадите через модули/конфиг. Также вы можете передавать параметры через Nuxt плагины или middleware, если нужно что-то более специфичное.