Почему сайт получает трафик, но не конвертирует посетителей в клиентов?

У бизнеса может быть современный сайт, настроенная реклама и стабильный поисковый трафик. Но при этом заявок — единицы. Или стоимость лида оказывается слишком высокой.

В большинстве случаев проблема не связана с одной критической ошибкой. Обычно сайт просто не помогает пользователю принять решение и пройти путь до обращения.

Ниже — 10 распространённых причин, из-за которых сайты теряют потенциальных клиентов.

Пользователь не понимает, чем занимается компания

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

Пользователь должен быстро получить ответы на три вопроса:

• Что это за компания?
• Какие услуги или продукты здесь предлагают?
• Подходит ли это под мою задачу?

Если сайт не даёт понятного ответа — посетитель уходит.

Частая ошибка — абстрактные формулировки на первом экране:

• «Комплексные digital-решения»
• «Инновационный подход к развитию бизнеса»
• «Создаём будущее вместе»

Такие фразы выглядят универсально, но не объясняют ценность.

Намного эффективнее работают конкретные формулировки:

• «Разработка интернет-магазинов на Tilda под ключ»
• «Настройка рекламы в Яндекс Директ для стоматологий»
• «Производство кухонь на заказ в Москве за 30 дней»

Чем понятнее предложение, тем выше вероятность, что пользователь продолжит изучать сайт.

Интерфейс перегружен лишними элементами

Избыточный дизайн часто снижает конверсию.

Когда на странице одновременно используются:

• анимации;
• слайдеры;
• всплывающие окна;
• видео;
• автозапуск чатов;
• сложные визуальные эффекты —

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

Вместо того чтобы вести посетителя к заявке, сайт начинает отвлекать.

Эффективный продающий сайт строится вокруг понятного сценария:

1. проблема;
2. решение;
3. преимущества;
4. кейсы;
5. подтверждение экспертизы;
6. заявка.

Чем меньше визуального шума — тем проще пользователю принять решение.

На сайте нет сильного оффера

Даже качественный дизайн не компенсирует отсутствие понятного предложения.

После просмотра страницы пользователь должен понимать почему стоит обратиться именно в эту компанию.

Слабый оффер выглядит так:

Разработка сайтов для бизнеса

Более сильный вариант:

Разрабатываем сайты для B2B-компаний, которые помогают получать заявки из SEO и рекламы

Или:

Запускаем интернет-магазины на Tilda за 21 день с интеграцией оплаты и доставки

Хороший оффер содержит:

• конкретику;
• понятную выгоду;
• специализацию;
• результат;
• сроки или ограничения.

Чем меньше пользователю приходится додумывать ценность самостоятельно, тем выше конверсия.

Сайт медленно загружается

Скорость напрямую влияет на количество заявок.

Если страница загружается 5–7 секунд, часть пользователей не дождётся открытия сайта — особенно с мобильных устройств.

Типовые причины:

• тяжёлые изображения;
• перегруженный frontend;
• большое количество сторонних скриптов;
• слабый хостинг;
• избыточные анимации.

Медленный сайт влияет не только на удобство пользователя, но и на:

• конверсию;
• стоимость рекламы;
• SEO-показатели;
• глубину просмотра;
• поведенческие факторы.

Чем медленнее работает сайт, тем выше потери рекламного бюджета.

Мобильная версия неудобна

Во многих нишах мобильный трафик уже превышает 70%.

При этом часть сайтов по-прежнему проектируется преимущественно под десктоп.

В результате на смартфоне:

• текст слишком мелкий;
• кнопки неудобны для нажатия;
• формы работают некорректно;
• элементы интерфейса ломаются;
• страницы долго загружаются.

Пользователь не будет адаптироваться под неудобный интерфейс. Он просто уйдёт к конкурентам.

Проверить качество мобильной версии можно очень просто: открыть сайт с телефона и попробовать оставить заявку одной рукой.

Большинство проблем становятся очевидны сразу.

Сайт не вызывает доверия

Пользователь редко оставляет заявку компании, о которой невозможно получить базовую информацию.

Особенно в сегментах с высоким чеком.

Если на сайте отсутствуют:

• кейсы;
• отзывы;
• примеры работ;
• информация о компании;
• реальные фотографии;
• юридические данные;
• понятные контакты —

доверие к бизнесу снижается.

Даже если компания работает давно и качественно.

Сильнее всего доверие повышают:

• реальные цифры;
• конкретные результаты;
• фотографии проектов;
• видео;
• разборы кейсов;
• упоминания клиентов и партнёров.

Блоки доверия — это не второстепенный контент, а один из ключевых факторов конверсии.

Слишком сложные формы заявки

Чем больше полей содержит форма — тем ниже вероятность, что пользователь её заполнит.

Типичная ошибка — попытка собрать максимум информации на первом контакте:

• имя;
• телефон;
• email;
• компания;
• бюджет;
• комментарий;
• количество сотрудников;
• удобное время звонка.

Для большинства сайтов это избыточно.

Основная задача первой формы — не собрать подробную анкету, а начать коммуникацию.

Во многих случаях достаточно:

• имени;
• телефона или Telegram.

Остальные детали можно уточнить позже.

Нет понятного призыва к действию

Иногда пользователь готов обратиться, но сайт не даёт понятного следующего шага.

Типовые проблемы:

• кнопки плохо заметны;
• форма находится слишком низко;
• CTA не объясняет выгоду;
• непонятно, что произойдёт после отправки заявки.

Слабые CTA:

Отправить

Подробнее

Более эффективные варианты:

• «Получить расчёт стоимости»
• «Обсудить проект»
• «Получить аудит сайта»
• «Узнать сроки запуска»

Хороший призыв к действию всегда:

• конкретен;
• понятен;
• связан с ценностью для клиента.

Сайт создаётся «для себя», а не для клиента

Многие компании пытаются сделать сайт максимально необычным:

• сложный дизайн;
• нестандартную навигацию;
• большое количество анимаций;
• креативные интерфейсные решения.

Но задача пользователя — не оценивать дизайнерские эксперименты.

Он хочет быстро решить свою задачу.

Если интерфейс мешает получить информацию или оставить заявку, сайт начинает снижать конверсию.

На практике самые эффективные коммерческие сайты часто выглядят достаточно сдержанно.

Потому что их основная цель — не производить впечатление, а приводить клиентов.

Нет аналитики и данных

Без аналитики невозможно понять, почему сайт не приносит заявки.

Если не настроено отслеживание действий пользователей, бизнес не видит:

• где теряется трафик;
• какие страницы работают хуже;
• какие источники приводят клиентов;
• сколько стоит лид;
• какие каналы окупаются.

В результате любые изменения превращаются в предположения.

Базовый набор аналитики должен включать:

• Яндекс Метрику;
• Google Analytics;
• настройку целей;
• отслеживание форм;
• коллтрекинг при необходимости;
• аналитику рекламных кампаний.

Только данные позволяют системно повышать конверсию сайта.

Вывод

Проблема большинства сайтов не в дизайне. Чаще всего сайт просто не помогает пользователю принять решение и сделать следующий шаг.

На конверсию влияют:

• понятность предложения;
• скорость работы;
• мобильная версия;
• доверие;
• структура страницы;
• качество оффера;
• сценарий взаимодействия.

Эффективный сайт — это не набор визуальных эффектов, а инструмент продаж.

И чем проще пользователю:

• понять предложение;
• оценить выгоду;
• убедиться в надёжности компании;
• оставить заявку —

тем выше вероятность конверсии.

MAX-боты умееют получать события от платформы несколькими способами:

• В режиме ожидания запросов от сервера (long-polling);
• В режиме получения событий через webhook;

В документации к официальной typescript библиотеке для создания MAX-ботов есть примеры запуска ботов в режиме ожидания запросов. В котором бот подключается к серверам MAX и ждёт события обновления. Как только сервер присылает обновление, бот обрабатывает его.

К сожалению такой режим работы не подходит для serverless окружений, а примеров запуска бота через получение событий по вебхуку, на момент написания этой статьи, в документации не нашлось.

В этой статье я постараемся исправить этот недочёт.

Решение для тех кто торопится

Для тех кто спешит и умеет настраивать бота для работы с webhook, сразу публикуем базовое готовое решение:

import { Update } from '@maxhub/max-bot-api/dist/core/network/api';
import { Bot, Context } from '@maxhub/max-bot-api';

export async function handler(event: YandexCloudFunctionEvent) {
  if (event.body) {
    if (typeof event.body === 'string' && event.body.length > 0) {
      try {
        // Парсим тело запроса
        const update: Update = JSON.parse(event.body) as Update;

        // Создаём бота
        const bot = await createBot();

        // Ниже то, для чего нужна эта статья
        const ctx = new Context(update, bot.api, bot.botInfo);
        await bot.middleware()(ctx, () => Promise.resolve(undefined));

        return { statusCode: 200, body: 'ok' };
      } catch (error) {
        return { statusCode: 500, body: 'error' };
      }
    }
  }
  return { statusCode: 200, body: 'ok' };
}

export const createBot = async () => {
  // В данном примере токен для бота хранится в переменной окружения
  const token = process.env.MAX_BOT_TOKEN;
  if (!token) {
    throw new Error('MAX_BOT_TOKEN не найден');
  }

  const bot = new Bot(token);

  // Тут описываете вашу логику работы бота

  return bot;
}

Разбор решения

Не буду долго и подробно расписывать как мы его нашли, но тем не менее отмечу пару важных моментов:

Мы искали что-то похожее на

bot.handleUpdate(update)

из grammY, библиотеки для Telegram-ботов.

И действительно, такой метод у класса Bot есть, но он приватный и не доступен для вызова.

Тут наверное можно было бы кастануть Bot к нужному мне типу с не приватным handleUpdate, но мы решили чуть-чуть покопать и изучить код библиотеки.

В итоге поняли что можно вызвать middleware(), предварительно добавив событие Update в контекст бота.

Подписка функции на получение событий

Для того чтобы подписать облачную функцию на обработку событий нужно:

• Знать публичный url для вызова функции (можно посмотреть в настройках функции в консоли управления Yandex Cloud);
• Отправить API запрос

На этом всё. Спасибо за внимание!

⚠️ В ноябре 2025 года, npm изменили свою политику использования access tokens. Подробнее.

Поэтому часть статьи про получение токена устарела.

Не так давно мы выпустили npm-пакет @baranov-guru/react-telegram-widgets. В этой статье решили поделиться своим опытом по автоматизации сборки и публикации обновлений npm-пакетов.

В начале статьи дана небольшая справка, о том что такое NPM и Github Actions.

Что такое NPM?

NPM (Node Package Manager) — это менеджер пакетов для JavaScript. Проще говоря - это программа, которая помогает устанавливать и управлять чужими библиотеками (частями кода), и использовать их в своём JavaScript-проекте.

Она идёт в комплекте с Node.js и позволяет:

• быстро подключать нужные инструменты и функции,
• обновлять их до новых версий,
• удалять, если больше не нужны.

Также через NPM можно найти тысячи готовых решений, которые другие разработчики выложили в общий доступ.

Что такое Github Actions?

GitHub Actions — это инструмент внутри GitHub, который предоставляет инструменты для непрерывной интеграции и непрерывной поставки (CI/CD). Или если проще, то помогает автоматически выполнять задачи с вашим кодом:

• собирать проект,
• проверять, работает ли код (прогонять тесты),
• выкладывать его на сервер или в облако.

Всё это происходит автоматически, по заранее созданным правилам, описанным в workflow файлах. Это удобно, потому что не нужно делать всё вручную.

Собираем свой Github workflow

Углубляться во все подробности написания workflow файлов, так же известных как "рабочие процессы", в этой статье не будем, оставим лишь ссылку на официальную документацию.

Нас интересует два момента:

• Когда запускать workflow?;
• Как публиковать в npm;

Когда запускать workflow?

Для себя мы выбрали следующую схему работы:

• Все изменения вливаются в main ветку проекта;
• Публикация же в npm происходит после ручного создания Github Release.

Для этого надо добавить следующий код в workflow:

on:
  release:
    types: [published]

Если же вы хотите публиковаться каждый раз при добавлении коммита в main ветку, то надо прописать следующее:

on:
  push:
    branches: [main]

Как публиковать в npm?

Тут всё просто, необходимо использовать команду:

npm publish

Шаг в workflow может выглядеть следующим образом:

- name: Publish to npm
  run: npm publish

Однако, если запустить такой workflow, то он упадёт с ошибкой авторизации, при публикации пакета.

Причина банальна - нельзя опубликовать пакет анонимно, нужно представиться.

Для этого необходимо добавить токен.

Получение токена

Получить токен можно в личном кабинете NPM.

Для этого надо:

• перейти на страницу с токенами;

• затем создать токен, нажав на кнопку "Generate New Token";

Для простых целей, нам хватит классического legacy access token. Его и выберем:

• заполнить форму и скопировать полученный токен;

Так как мы собираемся публиковаться через Github Actions, то выбираем тип токена "Automation".

Полученный токен необходимо добавить в repository secrets в репозитории проекта на github.

Добавление токена в Secrets на Github

Нам необходимо создать секрет NPM_TOKEN. Для этого необходимо:

• перейти в настройки репозитория;
• развернуть вкладку Secrets And Variables;
• выбрать Actions;

На открывшейся странице нажать кнопку New Repository Secret и вставить в модальном окне полученный ранее токен

Теперь осталось только указать токен в переменной окружения NODE_AUTH_TOKEN в нашем workflow:

- name: Publish to npm
  run: npm publish
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Особенности публикации @scoped пакетов

Если у вас, как и у нас, scoped package, то по умолчанию пакет не будет публично доступен.

Для решиния этой проблемы необходимо добавить параметр access со значением public.

npm publish --access public

Как не трудно догадаться это сделает пакет публичным и предоставит к нему открытый доступ.

Происхождение публикуемых пакетов (Provenance)

Так же, Github Actions из коробки позволяют создавать сведения о происхождении публикуемых пакетов (Provenance).

Provenance содержит подписанную информацию о сборке и публикации проекта, тем самым повышает безопасность цепочки поставок пакетов и просто классно смотрится. 😉

npm publish --provenance

Однако, если запустить такой workflow, то мы увидим следующую ошибку:

npm error code EUSAGE
npm error Provenance generation in GitHub Actions requires "write" access to the "id-token" permission

Как и написано в ошибке, необходимо добавить в workflow пермиссию id-token со значением write. Выглядит она следующим образом:

permissions:
  id-token: write
  contents: read

Теперь, если вы всё сделали правильно, в опубликоманном пакете можно будет увидеть следующую плашку:

Итоговый workflow

# Название workflow
name: Publish Package

# Когда выполнять
on:
  release:
    types: [published]

# Работа с разрешениями
permissions:
  id-token: write
  contents: read

# Описание job
jobs:
  build-and-publish:
    runs-on: ubuntu-latest

    steps:
      # Получение актуального кода проекта
      - name: Checkout code
        uses: actions/checkout@v4

      # Настройка окружения
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "18"
          registry-url: "https://registry.npmjs.org"
          cache: "npm"

      # Опционально: Установка зависимостей, линтинг, прогон тестов
      # ...

      # Сборка пакета
      - name: Build package
        run: npm run build

      # Публикация пакета
      - name: Publish to npm
        run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Что такое Telegram Widgets?

Telegram Widgets - API от Telegram, которое позволяет быстро добавить на сайт кнопку "Поделиться", встроить посты из публичных каналов или групп. С его помощью пользователи также могут авторизоваться через Telegram или просматривать обсуждения прямо на сайте.

Проблема с использованием в React приложенияx

Дело в том что Telegram Widget - это script-тег вида:

<script
  async
  src="https://telegram.org/js/telegram-widget.js?22"
  data-telegram-post="baranov_guru/61"
  data-width="100%"
></script>

Он инициализируется и добавляет в родительский контейнер iframe, который рендерит контент с нужными параметрами.

Из-за этого с виджетами очень неудобно работать в декларативном стиле, присущем React-компонентам. Поэтому нам пришлось написать небольшую обёртку над скриптами, позволяющую:

• Подписываться на события загрузки;
• Отслеживать ошибки;
• В удобном декларативном стиле пробрасывать необходимые свойства виджетов;
• Корректно обрабатывать изменения свойств и перерендеры компонентов;

А так как официального React-пакета для виджетов нет и не предвиделось, поэтому мы решили оформить её в виде npm-пакета @baranov-guru/react-telegram-widgets.

Что делает пакет @baranov-guru/react-telegram-widgets?

Сейчас он поддерживает два типа Telegram-виджетов:

• Комментарии (TelegramDiscussionWidget) — возможность встроить обсуждение постов прямо на сайте.
• Посты из ТГ-каналов (TelegramPostWidget) — удобный способ вставить отдельный пост из публичного Telegram-канала или группы.

Установка

npm install @baranov-guru/react-telegram-widgets

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

Виджет комментариев (TelegramDiscussionWidget)

import { TelegramDiscussionWidget } from "@baranov-guru/react-telegram-widgets";

function App() {
  return (
    <div>
      <h1>Discussion</h1>
      <TelegramDiscussionWidget
        discussion="baranov_guru"
        commentsLimit={10}
        height={400}
        color="#ff0000"
        colorful={true}
        dark={true}
        onLoad={() => console.log("Comments loaded!")}
        onError={(error) => console.error("Failed to load comments:", error)}
      />
    </div>
  );
}

Этот компонент можно встроить под статьёй или любым другим контентом. Все комментарии будут сохраняться в Telegram и синхронизироваться между пользователями.

Комментарии к посту доступны в Telegram.

Встраивание поста (TelegramPostWidget)

import { TelegramPostWidget } from "@baranov-guru/react-telegram-widgets";

const App = () => (
  <TelegramPostWidget
    post="baranov_guru/61"
    userpic
    color="#ff0000"
    onLoad={() => console.log("Post loaded!")}
    onError={(error) => console.error("Failed to load post:", error)}
    className="w-full flex p-2"
  />
);

Просто указываете название канала и ID поста — и он появляется на странице.

Открыть пост в Telegram

Документация

Все доступные пропсы и примеры есть в npm-профиле пакета. Там всё кратко и по делу.

Поддержите проект ⭐️

Если вам пригодился этот пакет — будем рады, если поставите ему звёздочку на GitHub. Это поможет другим разработчикам найти его.

С 30 мая 2025 года в России вступили в силу новые требования по защите персональных данных (ПДн). Ужесточены штрафы, усилена уголовная ответственность и расширен список нарушений.

Эти изменения касаются всех — от владельцев интернет-магазинов до авторов Telegram-ботов.

🏛️ Обзор новых законов и штрафов

Согласно последним поправкам в законы № 420‑ФЗ и № 421‑ФЗ:

• Штрафы от 100 000 до 300 000 ₽ — за отсутствие регистрации в Роскомнадзоре как оператора ПДн.
• Оборотные штрафы от 1 до 3 млн ₽ — за утечку данных, даже если виноват подрядчик.
• Уголовная ответственность — в случае умышленного или массового нарушения (например, при продаже баз).
• Штрафы для юрлиц и ИП — до 5 млн ₽ за отсутствие согласия, нарушение хранения и несоблюдение срока обработки.

🎯 Кто считается оператором персональных данных?

Если вы:

• собираете заявки или комментарии через сайт;
• принимаете оплату онлайн;
• используете email- или мессенджер-рассылки;
• подключили чат-бот или CRM;

— то вы оператор персональных данных и обязаны соблюдать законодательство.

Это касается всех — от крупных компаний до ИП и самозанятых.

🖥️ Что нужно сделать владельцам сайтов?

1. Зарегистрироваться в Роскомнадзоре

Если ваш сайт собирает любые данные (имя, телефон, email, cookies и пр.) — вы обязаны уведомить Роскомнадзор и зарегистрироваться как оператор ПДн.

2. Разместить политику конфиденциальности

На сайте должна быть доступна и легко читаемая политика обработки персональных данных, содержащая:

• наименование и контакты оператора;
• цели и способы обработки;
• категории собираемых данных;
• срок хранения;
• права пользователей;
• способы отзыва согласия.

Политика размещается в футере и отображается при первом входе на сайт (например, в виде баннера).

3. Запросить согласие перед сбором

Перед тем как собирать любые данные:

• покажите текст согласия;
• добавьте чекбокс или кнопку "Согласен", без которой форма не отправляется;
• фиксируйте дату, IP и содержание согласия.

Согласие должно быть свободным, конкретным, информированным и осознанным.

4. Уведомить о cookie и сторонних скриптах

Если сайт использует cookies, аналитические сервисы (Google Analytics, Яндекс.Метрика) или сторонние пиксели (TikTok), вы обязаны:

• уведомлять пользователей при входе на сайт;
• позволять отключать cookies;
• давать выбор — принимать или отклонять их.

🤖 Как собирать данные в чат-ботах

Если вы используете чат-ботов (Telegram, WhatsApp, ВКонтакте, Viber, Web):

1. Зарегистрируйтесь как оператор ПДн

Даже если бот — только для получения заявок, это уже обработка персональных данных.

2. Получите явное согласие

Попросите пользователя нажать «Согласен» или ввести команду (например, /agree) перед отправкой имени или телефона.

3. Разместите ссылку на политику

Политика конфиденциальности должна быть доступна из бота — через кнопку или автоответ.

4. Фиксируйте факт согласия

Сохраняйте дату, время, ID пользователя и текст, который он подтвердил.

🔐 Общие требования по безопасности

• Собирайте только нужное — минимизируйте объем данных.
• Храните данные в зашифрованном виде.
• Ограничьте доступ — только для сотрудников, которым он необходим.
• Удаляйте устаревшие данные — в срок, указанный в политике.
• Заключайте договоры с подрядчиками, которые обрабатывают ПДн от вашего имени.

📋 Чек-лист для владельцев сайтов и чат-ботов

📌 Выводы

1. Новые законы усилили контроль — штрафы стали выше, а ответственности больше.
2. Каждый сайт и бот — это потенциальный обработчик данных.
3. Главное правило — явное согласие: без него любые сборы ПДн незаконны.
4. Автоматизация ≠ безответственность — даже если все делает бот, ответственность несет владелец.
5. Правильная настройка сайта и чат-бота сегодня — защита от миллионов штрафов завтра.

На этом всё. Спасибо за внимание!

⚠️ Изначально статья была опубликована в 2025 году, в старом блоге проекта по адресу alexeybaranov.dev.

Данные в статье могли устареть. Если вы нашли ошибку, пожалуйста напишите нам.

Что такое брендированные типы в TypeScript?

Брендированные типы — это паттерн в TypeScript, позволяющий повысить безопасность типов, добавляя уникальные метки к существующим типам (например, string или number).

Это особенно полезно, когда несколько значений имеют одинаковый базовый тип, но несут разную семантическую нагрузку — например, UserId, PostId, OrderId.

Несмотря на то что на уровне выполнения это всё те же строки или числа, компилятор TypeScript воспринимает их как разные типы. Это предотвращает случайную подстановку одного значения вместо другого.

Зачем нужны брендированные типы?

TypeScript обеспечивает структурную типизацию — тип считается корректным, если у него есть нужные поля, независимо от его имени. Это может привести к ошибкам, когда два значения совместимы по структуре, но не по смыслу. Например:

type User = { id: string, name: string }
type Post = { id: string, ownerId: string }

function getPostByUser(userId: string, postId: string) { ... }

// вызов
getPostByUser(post.id, user.id) // ❌ ошибка смысла, но TypeScript не ругается

С брендированными типами TypeScript «поймёт» ошибку на этапе компиляции:

type UserId = string & { __brand: 'UserId' }
type PostId = string & { __brand: 'PostId' }

function getPostByUser(userId: UserId, postId: PostId) { ... }

getPostByUser(post.id, user.id) // ❌ ошибка типов: PostId ≠ UserId

Как создать брендированный тип?

Существует несколько подходов. Простейший — через пересечение типов с объектом-брендом:

type Brand<K, T> = K & { __brand: T };

type UserId = Brand<string, "UserId">;
type ProductId = Brand<string, "ProductId">;

Чтобы избежать дублирования имён и скрыть бренд от автодополнения в редакторе, можно использовать unique symbol:

declare const __brand: unique symbol;

type Brand<T, B> = T & { [__brand]: B };

type UserId = Brand<string, "UserId">;

Преимущества брендированных типов

• ✅ Повышенная безопасность типов (type safety): предотвращают подстановку несовместимых значений.
• 📖 Ясность кода: код становится самодокументируемым — UserId, OrderId говорят сами за себя, упрощают понимание, поддержку и рефакторинг кода
• 🧪 Простота тестирования и валидации: можно создавать отдельные функции-валидаторы, возвращающие брендированный тип только при успешной проверке.

Ограничения

• 🧱 Бренды — это compile-time метки: во время выполнения они не существуют.
• 💡 Можно случайно обойти типизацию, используя as без валидации — будьте осторожны.
• 🧠 Требуется внимание разработчиков: особенно в больших командах важно соблюдать договорённости при создании брендированных типов.

Применение на практике

1. Разделение ID-шников

type UserId = Brand<string, 'UserId'>
type PostId = Brand<string, 'PostId'>

function getComments(postId: PostId, authorId: UserId) { ... }

getComments(user.id, post.id) // ❌ TypeScript выдаст ошибку

2. Валидация пользовательского ввода

type EmailAddress = Brand<string, "EmailAddress">;

function validateEmail(input: string): EmailAddress {
  // Не валидируйте так email! Этот код написан для примера.
  if (!input.includes("@")) throw new Error("Invalid email");
  return input as EmailAddress;
}

3. Работа с числовыми значениями, например, возрастом

type Age = Brand<number, "Age">;

function createAge(age: number): Age {
  if (age < 0 || age > 125)
    throw new Error("Возраст вне допустимого диапазона");
  return age as Age;
}

function getBirthYear(age: Age): number {
  return new Date().getFullYear() - age;
}

const myAge = createAge(30);
const birthYear = getBirthYear(myAge);

Заключение

Branded Types — это мощный приём TypeScript, позволяющий повысить читаемость, надёжность и безопасность кода. Несмотря на то, что они не влияют на выполнение, их сила в compile-time проверках, помогающих предотвратить трудноуловимые ошибки.

Используйте брендированные типы там, где одинаковые по структуре значения имеют разное семантическое значение. Это особенно важно в больших приложениях, API-интеграциях и при валидации пользовательского ввода.

На этом всё. Спасибо за внимание!

⚠️ Изначально статья была опубликована в 2025 году, в старом блоге проекта по адресу alexeybaranov.dev.

Данные в статье могли устареть. Если вы нашли ошибку, пожалуйста напишите нам.

Важным элементом SEO-оптимизации является правильная работа с ошибками. В этой статье вы узнаете, что такое ошибка 404, и как правильно работать с ней в приложении на Next.js.

Что такое Not Found или 404 страница?

Ошибка 404, также известная как «Not Found» или «Не найдено», является стандартным HTTP-статусным кодом, который указывает на отсутствие запрашиваемого ресурса на сервере.

Файл not-found.js | not-found.ts

В Next.js, начиная с 13 версии, для работы с отображением 404 ошибки используется файл not-found.js.

Вот так может выглядеть код файла:

import Link from "next/link";

export default function NotFound() {
  return (
    <div>
      <h2>Не найдено</h2>
      <p>Запрашиваемый ресурс не доступен</p>
      <Link href="/">Вернуться на главную</Link>
    </div>
  );
}

Для отображения 404 ошибки необходимо поместить данный файл в корень директории app/,

app/not-found.tsx

страница будет отображаться для всех ненайденных URL приложения.

По умолчанию, NotFound - серверный компонент, и если необходимо получить какие-то данные перед отрисовкой, то необходимо сделать его асинхронным (async).

import Link from 'next/link'
import { headers } from 'next/headers'

export default async function NotFound() {
  const authorization = (await headers()).get('authorization');
  const res = await fetch('...', {
    headers: { authorization },
  })
  const user = await res.json();
  return (
     <div>
      <h2>Ничего не найдено, {user.name}.</h2>
      <p>Но ты можешь попробовать снова, вдруг это просто ошибка?</p>
    </div>
  )
}

Если же необходимо получить какие-то данные уже на клиенте, то можно вынести часть содержимого страницы в клиентский компонент, и запросить данные из него.

Подробную информацию можно найти в официальной документации по странице.

Функция notFound()

Так же отрисовку файла not-found.js можно вызвать принудительно с помощью функции notFound().

Примерно вот так:

import { notFound } from "next/navigation";

export default async function Post({ params }: Params) {
  const post = getPostBySlug(params.slug);

  if (!post) {
    return notFound();
  }

  ...

}

Эта функция позволяет кинуть ошибку NEXT_NOT_FOUND, а затем вызвать рендер страницы not-found.js в пределах сегмента пути и отдать 404 код ошибки HTTP.

В дополнение к этому, функция вставит на страницу мета-тег robots, при её использовании в серверном компоненте.

<meta name="robots" content="noindex" />

Функцию notFound() можно использовать в серверных компонентах (Server Components), обработчиках пути (Route Handlers) и серверных действиях (Server Actions).

Подробную информацию можно найти в официальной документации по функции.

На этом всё! 🎉

⚠️ Изначально статья была опубликована в 2025 году, в старом блоге проекта по адресу alexeybaranov.dev.

Данные в статье могли устареть. Если вы нашли ошибку, пожалуйста напишите нам.

Важным элементом SEO-оптимизации является наличие файла sitemap.xml. В этой статье вы узнаете, что такое sitemap.xml и как добавить его в свое приложение на Next.js.

Что такое sitemap.xml?

Sitemap.xml - это файл формата Sitemaps XML format, который сообщает поисковым системам (например Google или Yandex), какие страницы есть на вашем сайте и как часто они обновляются.

Этот файл должен находиться в корневой папке вашего сайта, и обычно доступен по адресу:

домен.зона/sitemap.xml

Например, sitemap.xml этого блога лежит по адресу https://baranov.guru/sitemap.xml и выглядит следующим образом:

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://baranov.guru/</loc>
    <lastmod>2025-03-13T12:07:00.337Z</lastmod>
    <changefreq>daily</changefreq>
    <priority>0.7</priority>
  </url>
  ...
</urlset>

Более подробную информацию о том как как поисковые системы обрабатывают файлы sitemap.xml можно найти в справке от Яндекса или документации Google.

Первый способ: Добавляем статический файл

Первый способ - очень простой. Next.js из коробки умеет отдавать статические файлы, например изображения, добавленные в папку public в корне проекта.

Этот же подход можно использовать для добавления файла sitemap.xml. Всё что необходимо сделать - добавить файл в папку public.

Подробнее про работу со статикой и папку public можно почитать в официальной документации Next.js.

Как видите, способ действительно очень простой, но подойдёт он вам только в случае, если у вас небольшой сайт, с редко меняющимся содержимым. В противном случае лучше прибегнуть к динамической генерации sitemap.xml.

Альтернативный способ добавления статического файла

Начиная с версии 13.3 Next.js умеет корректно обрабатывать статический файл sitemap.xml лежащий в корне папки app.

Подробнее в документации.

Второй способ: Динамическая генерация sitemap.xml

Для того чтобы динамически создавать файл sitemap.xml необходимо в папку app добавить файл robots.js или robots.ts, который будет возвращать объект типа MetadataRoute.Sitemap.

import { MetadataRoute } from "next";

import { URL_BASE } from "@/lib/constants";

export default function sitemap(): MetadataRoute.Sitemap {
  return [
    {
      url: `${URL_BASE}/`,
      lastModified: new Date(),
      changeFrequency: "daily",
      priority: 0.7,
    },
    {
      url: `${URL_BASE}/about/`,
      lastModified: new Date(),
      changeFrequency: "daily",
      priority: 0.7,
    },
    {
      url: `${URL_BASE}/posts/`,
      lastModified: new Date(),
      changeFrequency: "daily",
      priority: 0.7,
    },
  ];
}

Данный код сгенерирует файл со следующим содержимым:

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://baranov.guru/</loc>
    <lastmod>2025-03-13T12:07:00.337Z</lastmod>
    <changefreq>daily</changefreq>
    <priority>0.7</priority>
  </url>
  <url>
    <loc>https://baranov.guru/about/</loc>
    <lastmod>2025-03-13T12:07:00.337Z</lastmod>
    <changefreq>daily</changefreq>
    <priority>0.7</priority>
    </url>
  <url>
    <loc>https://baranov.guru/posts/</loc>
    <lastmod>2025-03-13T12:07:00.337Z</lastmod>
    <changefreq>daily</changefreq>
    <priority>0.7</priority>
  </url>
</urlset>

Генерация Image Sitemaps

Так же, начиная с 15 версии в Next.js есть встроенная возможность генерировать Image Sitemaps. Для этого надо всего лишь добавить свойство images (см. спецификацию) к странице.

import { MetadataRoute } from "next";

import { URL_BASE } from "@/lib/constants";

export default function sitemap(): MetadataRoute.Sitemap {
  return [
    {
      url: `${URL_BASE}/`,
      lastModified: new Date(),
      changeFrequency: "daily",
      priority: 0.7,
      images: ["https://baranov.guru/assets/authors/avatar.webp"],
    },
  ];
}

В результате получим следующий файл:

<urlset
  xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
  xmlns:image="http://www.google.com/schemas/sitemap-image/1.1"
>
  <url>
    <loc>https://baranov.guru/</loc>
    <image:image>
      <image:loc>https://baranov.guru/assets/authors/avatar.webp</image:loc>
    </image:image>
    <lastmod>2025-03-13T12:07:00.337Z</lastmod>
    <changefreq>daily</changefreq>
    <priority>0.7</priority>
  </url>
</urlset>

Генерация Video Sitemaps

Так же, начиная с 15 версии в Next.js есть встроенная возможность генерировать Video Sitemaps. Для этого надо всего лишь добавить свойство videos (см. спецификацию) к странице.

import { MetadataRoute } from "next";

import { URL_BASE } from "@/lib/constants";

export default function sitemap(): MetadataRoute.Sitemap {
  return [
    {
      url: `${URL_BASE}/posts/yandex-gpt-intro/`,
      lastModified: new Date(),
      changeFrequency: "daily",
      priority: 0.7,
      videos: [
        {
          title: "Название видео",
          thumbnail_loc:
            "https://baranov.guru/assets/posts/yandex-gpt-intro/cover.webp",
          description: "Это описание видео",
        },
      ],
    },
  ];
}

В результате получим следующий файл:

<urlset
  xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
  xmlns:video="http://www.google.com/schemas/sitemap-video/1.1"
>
  <url>
    <loc>https://baranov.guru/posts/yandex-gpt-intro/</loc>
    <video:video>
      <video:title>Название видео</video:title>
      <video:thumbnail_loc>https://baranov.guru/assets/posts/yandex-gpt-intro/cover.webp</video:thumbnail_loc>
      <video:description>Это описание видео</video:description>
    </video:video>
    <lastmod>2025-03-13T12:07:00.337Z</lastmod>
    <changefreq>daily</changefreq>
    <priority>0.7</priority>
  </url>
</urlset>

Генерация локализованных Sitemaps

В Next.js есть встроенная возможность добавлять ссылки на версии страниц на другом языке при генерации sitemap.xml. Для этого надо всего лишь добавить свойство alternates (см. спецификацию) к странице.

import { MetadataRoute } from "next";

import { URL_BASE } from "@/lib/constants";

export default function sitemap(): MetadataRoute.Sitemap {
  return [
    {
      url: `${URL_BASE}/`,
      lastModified: new Date(),
      changeFrequency: "daily",
      priority: 0.7,
      alternates: {
        languages: {
          en: `${URL_BASE}/en/`,
          fr: `${URL_BASE}/fr/`,
        },
      },
    },
  ];
}

В результате получим следующий файл:

<urlset
  xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
  xmlns:xhtml="http://www.w3.org/1999/xhtml"
>
  <url>
    <loc>https://baranov.guru/</loc>
    <xhtml:link
      rel="alternate"
      hreflang="en"
      href="https://baranov.guru/en/"/>
    <xhtml:link
      rel="alternate"
      hreflang="fr"
      href="https://baranov.guru/fr/"/>
    <lastmod>2025-03-13T12:07:00.337Z</lastmod>
    <changefreq>daily</changefreq>
    <priority>0.7</priority>
  </url>
</urlset>

Спецификация MetadataRoute.Sitemap

Вот полная спецификация MetadataRoute.Sitemap, взятая из официального репозитория на Github.

type Sitemap = Array<{
  url: string;
  lastModified?: string | Date | undefined;
  changeFrequency?:
    | "always"
    | "hourly"
    | "daily"
    | "weekly"
    | "monthly"
    | "yearly"
    | "never"
    | undefined;
  priority?: number | undefined;
  alternates?:
    | {
        languages?: Languages<string> | undefined;
      }
    | undefined;
  images?: string[] | undefined;
  videos?: Videos[] | undefined;
}>;

export type Videos = {
  title: string;
  thumbnail_loc: string;
  description: string;
  content_loc?: string | undefined;
  player_loc?: string | undefined;
  duration?: number | undefined;
  expiration_date?: Date | string | undefined;
  rating?: number | undefined;
  view_count?: number | undefined;
  publication_date?: Date | string | undefined;
  family_friendly?: "yes" | "no" | undefined;
  restriction?: Restriction | undefined;
  platform?: Restriction | undefined;
  requires_subscription?: "yes" | "no" | undefined;
  uploader?:
    | {
        info?: string | undefined;
        content?: string | undefined;
      }
    | undefined;
  live?: "yes" | "no" | undefined;
  tag?: string | undefined;
};

Альтернативные решения

Так же есть несколько альтернативных решений для генерации sitemap.xml в виде npm-пакетов. Например пакет next-sitemap.

Бонус: Валидация sitemap.xml

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

• Валидатор от Google;
• Валидатор от Yandex;

На этом всё! 🎉

⚠️ Изначально статья была опубликована в 2025 году, в старом блоге проекта по адресу alexeybaranov.dev.

Данные в статье могли устареть. Если вы нашли ошибку, пожалуйста напишите нам.

Важным элементом SEO-оптимизации является наличие файла robots.txt. В этой статье вы узнаете, что такое robots.txt и как добавить его в свое приложение на Next.js.

Что такое robots.txt?

Robots.txt - это текстовый файл, основанный на спецификации Robots Exclusion Protocol, который сообщает поисковым роботам (например Googlebot или Yandex), какие страницы они могут сканировать, а какие нет.

А так же указывает на файл sitemap.xml. О том что это такое и как добавить файл sitemap.xml читайте в статье «Добавляем sitemap.xml в Next.js приложение».

Robots.txt должен находиться в корневой папке вашего сайта, и обычно доступен по адресу:

домен.зона/robots.txt

Например, у этого блога он лежит по адресу https://baranov.guru/robots.txt и выглядит следующим образом:

# *
User-agent: *
Allow: /

# Host
Host: https://baranov.guru/

# Sitemap
Sitemap: https://baranov.guru/sitemap.xml

Более подробную информацию о том как как поисковые системы обрабатывают файлы robots.txt можно найти в справке от Яндекса или документации Google.

Первый способ: Добавляем статический файл

Первый способ - очень простой. Next.js из коробки умеет отдавать статические файлы, например изображения, добавленные в папку public в корне проекта.

Этот же подход можно использовать для добавления файла robots.txt. Всё что необходимо сделать - добавить файл в папку public.

Подробнее про работу со статикой и папку public можно почитать в официальной документации Next.js.

Альтернативный способ добавления статического файла

Начиная с версии 13.3 Next.js умеет корректно обрабатывать статический файл robots.txt лежащий в корне папки app.

Подробнее в документации.

Второй способ: Динамическая генерация robots.txt

Для того чтобы динамически создавать файл robots.txt необходимо в папку app добавить файл robots.js или robots.ts, который будет возвращать объект типа MetadataRoute.Robots.

import type { MetadataRoute } from "next";

export default function robots(): MetadataRoute.Robots {
  return {
    rules: {
      userAgent: "*",
      allow: "/",
      disallow: "/private/",
    },
    sitemap: "https://baranov.guru/sitemap.xml",
    host: "https://baranov.guru/",
  };
}

Данный код сгенерирует файл со следующим содержимым:

User-Agent: *
Allow: /
Disallow: /private/

Host: https://baranov.guru/
Sitemap: https://baranov.guru/sitemap.xml

Кастомизация настроек в зависимости от user-agent

Так же есть возможность добавлять правила для различных user-agent.

import type { MetadataRoute } from "next";

export default function robots(): MetadataRoute.Robots {
  return {
    rules: [
      {
        userAgent: "Googlebot",
        allow: ["/"],
        disallow: "/private/",
      },
      {
        userAgent: ["Yandex", "Bingbot"],
        disallow: ["/"],
      },
    ],
    sitemap: "https://baranov.guru/sitemap.xml",
  };
}

На выходе получим следующий файл:

User-Agent: Googlebot
Allow: /
Disallow: /private/

User-Agent: Yandex
User-Agent: Bingbot
Disallow: /

Sitemap: https://baranov.guru/sitemap.xml

Спецификация MetadataRoute.Robots

Вот полная спецификация MetadataRoute.Robots, взятая из официальной документации.

type Robots = {
  rules:
    | {
        userAgent?: string | string[];
        allow?: string | string[];
        disallow?: string | string[];
        crawlDelay?: number;
      }
    | Array<{
        userAgent: string | string[];
        allow?: string | string[];
        disallow?: string | string[];
        crawlDelay?: number;
      }>;
  sitemap?: string | string[];
  host?: string;
};

Минусы динамической генерации и директива Clean-Param

К сожалению, динамическая генерация не поддерживает добавление кастомных директив в правила. Самым ярким примером кастомной директивы можно считать директиву Clean-Param, поддерживаемую Яндексом.

Для того чтобы её добавить придётся воспользовать либо первым способом (статический файл) либо каким-нибудь сторонним решением, например npm-пакетом next-sitemap.

Бонус: Валидация robots.txt

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

• Валидатор от Google;
• Валидатор от Yandex;

На этом всё! 🎉

⚠️ Изначально статья была опубликована в 2024 году, в старом блоге проекта по адресу alexeybaranov.dev.

Данные в статье могли устареть. Если вы нашли ошибку, пожалуйста напишите нам.

Сегодня расскажем как добавить кнопку для сбора пожертвований (донатов) к блогу или сайту.

Зачем блогеру нужна кнопка "Поддержать"

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

Выбор сервиса для сбора пожертвований

Существует множество сервисов, которые позволяют собрать пожертвования (донаты) с пользователей:

Быстрый поиск в интернете выдал следующие результаты:

• BuyMeACoffee - на первый взгляд - то что нужно, но находится за рубежом и не обслуживает клиентов из РФ;
• Ko-fi - аналогично BuyMeACoffee, но ещё говорят и кидает на деньги если ты из РФ;
• Coindrop - интересный open-source сервис, но как мне показалось больше подходит для крипты;
• ЮKassa - всё хорошо, я им даже пользовался в "У нас праздник", но не работает с физ. лицами;
• ЮMoney - та же ЮKassa, но вид сбоку;
• CloudTips - сервис для чаевых и донатов от Т-банка, предназначен именно для физиков и безвозмездных пожертвований.

В итоге я решил создать себе страницу на CloudTips.

Как выглядит "правильная" кнопка доната (требования к кнопке)

Советы по оформлению:

• Цвет — контрастный, выделяющийся на фоне сайта
• Надпись — короткая и мотивирующая: Поддержать, Купить кофе, Помочь блогу
• Размер — не слишком маленький, кнопка должна быть заметной
• Положение — в шапке, футере и внутри постов

Пример кнопки:

<a
  href="https://www.buymeacoffee.com/yourname"
  target="_blank"
  rel="noopener noreferrer"
  class="donate-button"
>
  ☕ Поддержать
</a>

Стилизуем через CSS:

.donate-button {
  background-color: #ffdd00;
  color: #000;
  padding: 0.6em 1em;
  font-weight: bold;
  border-radius: 8px;
  text-decoration: none;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
  transition: transform 0.2s;
}
.donate-button:hover {
  transform: scale(1.05);
}

Где размещать кнопку

• В шапке сайта — рядом с навигацией;
• В конце каждого поста — после текста;
• В сайдбаре (если есть);
• В футере — для постоянного доступа;
• Плавающая кнопка (например, снизу справа);

Продвинутые приёмы

• QR-код для доната — удобно если вас читают с десктопа, а платить будут с мобильного;
• Inline‑форма — некоторые сервисы позволяют вставлять форму прямо в пост;
• Цели/прогресс — показывайте цель сбора и текущий прогресс (мотивация!);

Интеграция в соцсетях

• Telegram: закрепите ссылку в описании канала
• YouTube: добавьте кнопку в описание профиля

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

Нужно ли платить налоги?

Всё сложно, но на практике часто проще заплатить налог, чем потом объяснять и доказывать банку и налоговой что ты не верблюд.

Какой сервис выбрать?

Для международной аудитории — BuyMeACoffee или Donorbox. Для РФ — CloudTips или ЮMoney.

Люди не донатят, что делать?

Добавьте личный призыв, расскажите, зачем поддержка важна, дайте стимул: «донаты помогут выпустить книгу».

Кнопка доната — это не про навязчивость, а про возможность поддержать полезный контент. Сделайте её видимой, дружелюбной и понятной — и она начнёт работать.

P.S. Моя реализации кнопки для донатов на react

Компонент DonateButton

import classNames from "classnames";
import React from "react";
import { FaHeart } from "react-icons/fa";

import styles from "./DonateButton.module.css";

const DONATION_LINK = "https://pay.cloudtips.ru/p/7d0e9b9f";

const DonateButton: React.FC = () => {
  return (
    <a
      href={DONATION_LINK}
      rel="noreferrer"
      target="_blank"
      className={classNames(
        "bg-red-600 rounded-md p-2 text-white flex flex-row gap-2 justify-center items-center text-xl",
        styles.wrap
      )}
    >
      <FaHeart size={20} className={styles.heart} />
      <span>Отправить донат</span>
    </a>
  );
};

export default DonateButton;

Стили для компонента

.wrap {
  animation: glow 800ms ease-out infinite alternate;
  border-color: rgb(153, 51, 51);
  box-shadow:
    0 0 5px rgba(255, 0, 0, 0.2),
    inset 0 0 5px rgba(255, 0, 0, 0.1);
  color: rgb(255, 238, 238);
  outline: none;
}

@keyframes glow {
  0% {
    border-color: rgb(153, 51, 51);
    box-shadow:
      0 0 5px rgba(255, 0, 0, 0.2),
      inset 0 0 5px rgba(255, 0, 0, 0.1);
  }
  100% {
    border-color: rgb(255, 102, 102);
    box-shadow:
      0 0 20px rgba(255, 0, 0, 0.6),
      inset 0 0 10px rgba(255, 0, 0, 0.4);
  }
}

.heart {
  animation: heartbeat 0.9s linear infinite;
}

@keyframes heartbeat {
  0% {
    transform: scale(1.05);
  }
  50% {
    transform: scale(1);
  }
  100% {
    transform: scale(0.9);
  }
}

На этом всё! 🎉

⚠️ Изначально статья была опубликована в 2024 году, в старом блоге проекта по адресу alexeybaranov.dev.

Данные в статье могли устареть. Если вы нашли ошибку, пожалуйста напишите нам.

Сегодня расскажем как можно добавить базовую поддержку MDX в Next.js приложение и использовать .mdx файлы в качестве страниц.

Что такое MDX?

MDX - это синтаксис, который позволяет использовать JSX-синтаксис в markdown контенте, ну или наоборот. Подробнее можно почитать тут.

Вот простой пример MDX синтаксиса:

import ComplexComponent from "@/app/_components/ComplexComponent";
import ImageWrap from "@/app/_components/ImageWrap";

# Тут заголовок

обычный текст

и React-компоненты:

- например, для картинок

<ImageWrap src={"путь к картинке"}/>

- или что-нибудь сложное

<ComplexComponent />

Описание процесса

Итак, для того чтобы добавить поддержку MDX в Next.js приложение необходимо:

• Установить необходимые пакеты;
• Создать файл mdx-components.tsx;
• Включить обработку .mdx файлов в next.config.js;
• (Опционально) Настроить IDE;

Установка необходимых пакетов

Нам понадобятся пакеты:

• @next/mdx - основной пакет, который дружит Next.js и MDX;
• @mdx-js/loader - webpack loader для MDX файлов;
• @types/mdx - необходим для нормальной работы с typescript;

Установим их следующими командами:

npm i -S @next/mdx

npm install -D @mdx-js/loader @types/mdx

Создание файла mdx-components.tsx

Теперь необходимо создать файл mdx-components.tsx и положить его в src/.

Файл mdx-components.tsx необходим, для того чтобы подружить MDX и Next.js приложение использующее App Router.

import type { MDXComponents } from "mdx/types";

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    ...components,
  };
}

Включение обработки .mdx файлов в next.config.js

Осталось только подправить конфиг (файл next.config.js) нашего приложения.

const withMDX = require("@next/mdx")();

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Добавляем `mdx` в pageExtensions
  pageExtensions: ["js", "jsx", "mdx", "ts", "tsx"],
};

module.exports = withMDX(nextConfig);

Теперь вместо page.tsx для страниц можно использовать page.mdx! 🎉

Расширение для VSCode

Бонус для тех кто использует VSCode, есть неплохое расширение для поддержки MDX синтаксиса - MDX for Visual Studio Code;

На этом всё! 🎉

В этой статье разберём:

• как считается время чтения;
• какую скорость брать за основу;
• как реализовать расчёт на JavaScript / TypeScript.

Как быстро посчитать время чтения текста

Базовая логика очень простая:

• считаем количество слов в тексте;
• делим на среднюю скорость чтения.

Формула расчёта

Формула выглядит так:

время чтения (мин) = количество слов / скорость чтения

Чтобы избежать значения 0 минут, результат обычно округляют вверх.

Пример расчёта

700 слов / 140 слов в минуту ≈ 5 минут

Какая скорость чтения считается нормальной

Единого стандарта нет, но обычно используют такие значения:

• 100–120 слов/мин — сложный или технический текст
• 130–160 слов/мин — обычные статьи
• 180+ слов/мин — лёгкое чтение

Для блога с техническим контентом разумно брать около 140 слов в минуту — это даёт более реалистичную оценку.

Подсчёт количества слов

Начнём с функции подсчёта слов. Один из самых простых вариантов — использовать регулярное выражение:

export const countWords = (str: string) => {
  const words = str.match(/[ЁёА-я\w\d\’\'-]+/gi);
  return words ? words.length : 0;
};

Важный момент

Обратите внимание на часть:

ЁёА-я

Без неё кириллические слова не будут учитываться, и результат окажется некорректным (например, будет считаться только код или латиница).

Тесты для функции подсчёта слов

После этого я написал несколько тестов для функции countWords, вот один из них для примера:

it("should return correct value for cyrillic string", () => {
  // arrange
  const expectedResult = 1;
  const inputValue = "тест";

  // act
  const result = countWords(inputValue);

  // assert
  expect(result).toBe(expectedResult);
});

Расчёт скорости чтения

Теперь подсчитаем количество слов:

const AVERAGE_READ_SPEED = 140; //Слов в минуту

export const getReadTime = (content: string) => {
  return Math.ceil(countWords(content) / AVERAGE_READ_SPEED);
};

Не забудьте про округление

Обратите внимание на вызов:

Math.ceil()

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

Тесты для функции подсчёта времени чтения

it("should return 0 for an empty string", () => {
  // arrange
  const expectedResult = 0;
  const inputValue = "";

  // act
  const result = getReadTime(inputValue);

  // assert
  expect(result).toBe(expectedResult);
});

it("should return 1 for not empty string", () => {
  // arrange
  const expectedResult = 1;
  const inputValue = "тест";

  // act
  const result = getReadTime(inputValue);

  // assert
  expect(result).toBe(expectedResult);
});

Ограничения подхода

Важно понимать, что это приближённая оценка:

• не учитывается сложность текста;
• не учитываются изображения, код и форматирование;
• скорость чтения у разных людей отличается.

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

Где это может пригодиться

Индикатор времени чтения полезен не только разработчикам, но и:

• авторам блогов;
• копирайтерам;
• SEO-специалистам;
• редакторам;
• студентам;

Это простой способ сделать контент более предсказуемым для читателя.

Как проверить результат

Если вы хотите быстро проверить любой текст без кода, можно воспользоваться текстовым калькулятором: вставить текст и сразу получить количество слов и примерное время чтения.

На этом всё! Спасибо за внимание!

⚠️ Изначально статья была опубликована в 2024 году, в старом блоге проекта по адресу alexeybaranov.dev.

Данные в статье могли устареть. Если вы нашли ошибку, пожалуйста напишите нам.

Продолжаем работать над улучшением блога. В этой статье расскажем как добавляли подсветку кода (синтаксиса) в постах.

Есть множество способов сделать это, мы же решили пойти самым простым путём и остановились на использовании пакета Prism.

Процесс можно разделить на несколько этапов:

• Установка необходимых пакетов
• Статическая генерация подсвеченного кода
• Добавление подсветки необходимых языков
• Работа с плагинами Prism
• Подключение темы Prism

Установка необходимых пакетов

Сначала установим необходимые пакеты:

npm i prismjs

Так как мы статически генерируем html блога из .md файлов, то нам нужен способ запускать Prism во время сборки приложения. В этом нам поможет пакет rehype-prism.

npm i rehype-prism

Статическая генерация подсвеченного кода

В подробностях тут описывать особенно нечего, просто импортируем необходимые пакеты и включаем их в процесс генерации html.

import "prismjs";
import rehypePrism from "rehype-prism";
import rehypeStringify from "rehype-stringify";
import remarkCustomHeaderId from "remark-custom-header-id";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { unified } from "unified";

export default async function markdownToHtml(markdown: string) {
  const result = unified()
    .use(remarkParse, { sanitize: false })
    .use(remarkCustomHeaderId)
    .use(remarkRehype)
    // Внимание на следующую строку
    .use(rehypePrism)
    .use(rehypeStringify)
    .process(markdown);

  return (await result).toString();
}

Добавление подсветки необходимых языков

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

import "prismjs/components/prism-bash";
import "prismjs/components/prism-json";
import "prismjs/components/prism-typescript";

Работа с плагинами Prism

Так же Prism поддерживает множество плагинов. Мы выбрали "line-numbers", "toolbar", "copy-to-clipboard" плагины.

Для того чтобы их активировать необходимо:

• Подключить код и стили этих плагинов;
• Указать пакету rehype-prism что их необходимо использовать.

Подключение кода и стилей этих плагинов

Добавим импорт стилей для плагинов в компонент Post.

import "prismjs/plugins/line-numbers/prism-line-numbers.css";
import "prismjs/plugins/toolbar/prism-toolbar.css";

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

Пакет rehype-prism поддерживает нужные нам плагины из коробки, необходимо только указать что их следует использовать.

export default async function markdownToHtml(markdown: string) {
  const result = unified()
    .use(remarkParse, { sanitize: false })
    .use(remarkCustomHeaderId)
    .use(remarkRehype)
    // Внимание на следующую строку
    .use(rehypePrism, {
      plugins: ["line-numbers", "toolbar", "copy-to-clipboard"],
    })
    .use(rehypeStringify)
    .process(markdown);

  return (await result).toString();
}

Подключение цветовой темы Prism

Prism поддерживает множество цветовых тем. Для того чтобы использовать выбранную тему, необходимо импортировать .css файл нужной темы.

import "prismjs/themes/prism.css";

На этом всё! 🎉

Результат можно посмотреть в любом из постов блога.

⚠️ Изначально статья была опубликована в 2024 году, в старом блоге проекта по адресу alexeybaranov.dev.

Данные в статье могли устареть. Если вы нашли ошибку, пожалуйста напишите нам.

Продолжаем работать над улучшением блога и одновременно разбираться в Next.js. В этой статье расскажем как добавить пагинацию к статическим страницам блога.

Процесс можно разделить на несколько этапов:

• Разделение логики страницы на динамическую и статическую
• Добавление навигационного компонента
• Работа над поисковой выдачей

Результат можно посмотреть в самом низу страницы с постами.

Разделение логики страницы на динамическую и статическую

Нам не хотелось менять структуру страниц сайта, поэтому мы решили что страницу будем прокидывать через query string.

Статические страницы в Next.js имеют ряд ограничений при работе с query string. По сути, единственный доступный в моём случае способ получить доступ к параметрам из URL - воспользоваться хуком useSearchParams из клиентского компонента.

Для этого необходимо вынести получение данных о постах в код статической страницы, и передать их в клиентский компонент, который сможет отфильтровать их нужным нам способом и отрисовать нужный нам список постов.

import { Suspense } from "react";

export default function PostsPage() {
  const posts = getAllPostsMeta();
  const tags = getAllTags();

  return (
    <>
      // ...
      <Suspense fallback={<StaticPosts posts={posts} tags={tags} />}>
        <DynamicPosts posts={posts} tags={tags} />
      </Suspense>
      // ...
    </>
  );
}

Заметьте что компонент DynamicPosts обёрнут в Suspense. Фоллбек будет отрендерен в build-time. А компонент DynamicPosts будет отрендерен уже во время исполнения кода страницы на клиенте.

"use client"

// ...

const DynamicPage: React.FC<Props> = ({ posts, tags }) => {
  const searchParams = useSearchParams();

  const page = Number(searchParams.get("page")) || 1;
  const maxPage = Math.ceil(posts.length / POSTS_PER_PAGE);

  const pageOffset = (page - 1) * POSTS_PER_PAGE;

  const pagePosts = posts.slice(pageOffset, pageOffset + POSTS_PER_PAGE);

  if (!pagePosts.length) return notFound();

  return (
    <>
      <Posts posts={pagePosts} title={"Посты"} withFilter tags={tags} />
      <PageSelector page={page} maxPage={maxPage} />
    </>
  );
};

Добавление навигационного компонента

Для навигационного компонента, будем использовать компонент Link из встроенного пакета next/link и прокидывать в параметр href необходимую нам страницу.

<Link href={`./?page=${page}`}>{page}</Link>

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

Работа над поисковой выдачей

Для того чтобы не получить дублирующиеся страницы в поиске, и не усложнить себе жизнь долгим процессом удалением дублей, необходимо сделать следующее:

• Добавить ссылку на каноническую страницу;
• Добавить директиву Clean-Param в robots.txt;

Добавление ссылки на каноническую страницу

Для того чтобы правильно пройти через процесс нормализации, необходимо добавить ссылку на каноническую страницу.

<link rel="canonical" href="https://baranov.guru/posts" />

В Next.js есть специальное Metadata API, которое можно использовать как раз для этих целей.

Воспользуемся им:

export const metadata: Metadata = {
  title: "Посты | Алексей Баранов. Блог",
  description: "Страница со всеми опубликованными постами",
  alternates: {
    canonical: `/posts`,
  },
};

Добавление директивы Clean-Param в robots.txt

Яндекс поддерживает специальную директиву Clean-param в файлах robots.txt.

Давайте добавим её:

User-agent: Yandex
Clean-param: page
Allow: /

На этом всё! 🎉

⚠️ Изначально статья была опубликована в 2024 году, в старом блоге проекта по адресу alexeybaranov.dev.

Данные в статье могли устареть. Если вы нашли ошибку, пожалуйста напишите нам.

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

Вот так он выглядит на момент написания этой статьи:

Процесс можно разделить на несколько этапов:

• Добавление тегов к статьям
• Генерация страниц для каждого тега
• Добавление ссылок на страницы
• Работа над поисковой выдачей

Добавление тегов к постам

Тут всё просто, как и в случае с рекомендациями, мы решили захардкодить в frontmatter каждой статьи массив с тегами.

Например, для этой статьи массив выглядит следующим образом:

tags: ["улучшения блога", "nextjs"]

Если вы пойдёте этим же путём, то обратите внимание на то, что в названии тегов лучше не использовать кириллицу и спец. символы. О том как всё же использовать в тегах кириллицу читайте далее в статье.

Генерация страниц для каждого тега

Генерация страниц для тегов очень похожа на генерацию страниц постов.

Алгоритм очень простой и выглядит следующим образом:

• Проходим по всем постам и собираем уникальные теги
• Для каждого тега генерируем страницу с постами

Сбор уникальных тегов

О том как получить все посты и их метаданные мы писали в статье о добавлении RSS фида.

Там же можно найти и полную реализацию метода getAllPosts.

А нам же остаётся только добавить все теги в массив и удалить оттуда дубли:

export function getAllTags(): string[] {
  const notUniqueTags = getAllPosts().flatMap((p) =>
    p.tags ? [...p.tags] : [],
  );

  return Array.from(new Set(notUniqueTags));
}

Генерация страниц

Для того чтобы сгенерировать страницы, нам нужен не только список тегов, но и список постов по тегу:

export function getAllPostsByTag(tag: string): Post[] {
  return getAllPosts().filter((p) => p.tags?.includes(tag));
}

Далее добавляем компонент для отображения страницы:

type Params = {
  params: {
    tag: string;
  };
};

// Компонент для отображения страницы
export default async function TagPage({ params }: Params) {
  const decodedTag = getTagFromURI(params.tag);

  const posts = getAllPostsByTag(decodedTag);

  if (!posts.length) {
    return notFound();
  }

  return (
    <>
      // Отображаем тут наши посты
    </>
  );
}

И генерируем статические страницы:

// Генерируем статические страницы в build-time
export async function generateStaticParams() {
  const tags = getAllTags();

  return tags.map((t) => ({
    tag: getTagURI(t),
  }));
}

Неочевидные моменты

Вы наверняка заметили что мы используем функции getTagFromURI и getTagURI при работе с тегами.

Дело в том что на данный момент в Next.js существуют сложности с кириллическими путями.

export const getTagURI = (tag: string) => {
  return process.env.NODE_ENV === "development" ? encodeURIComponent(tag) : tag;
};

export const getTagFromURI = (uri: string) => {
  return decodeURIComponent(uri);
};

Добавление ссылок на страницы

Тут сказать особо нечего, единственный момент, который следует учитывать - не забывайте оборачивать теги в encodeURIComponent.

const TagLinks: React.FC = () => {
  const tags = getAllTags();

  return (
    <div>
      {tags.map((item, i) => (
        <Link
          href={`/tags/${getTagURI(item)}`}
          key={i}
        >
          {`#${item}`}
        </Link>
      ))}
    </div>
  );
};

Работа над поисковой выдачей

Для улучшения индексирования сгенерированные страницы можно добавить в файл sitemap сайта.

Для этого, в файл sitemap.ts, лежащий в корне сайта добавляем следующий код:

import { MetadataRoute } from "next";

import { getAllTags, getTagURI } from "@/lib/api";

export default function sitemap(): MetadataRoute.Sitemap {
  const tags = getAllTags();
  return [
    // тут остальные страницы сайта
    ...tags.map((tag) => ({
      url: `https://baranov.guru/tags/${getTagURI(tag)}`,
      lastModified: new Date(),
      priority: 0.7,
    })),
  ];
}

На этом всё! 🎉

⚠️ Изначально статья была опубликована в 2024 году, в старом блоге проекта по адресу alexeybaranov.dev.

Данные в статье могли устареть. Если вы нашли ошибку, пожалуйста напишите нам.

Изучали различные блоги, аналогичные нашему и решили добавить блок "Поделиться в соц. сетях", а так же простейший механизм рекомендаций статей. Вот что из этого вышло...

Добавляем рекомендации постов

Тут всё просто, мы решили захардкодить в frontmatter каждой статьи массив со ссылками на другие статьи, схожие по тематике.

Только вместо ссылок мы использовали slug постов.

recommendations: ["collabic", "vk-feed"]

У нас уже был компонент PostPreview для отображения описания поста. Он используется на главной странице. Поэтому мы просто переиспользовали его.

В компоненте поста, мы получаем список данных о рекомендованных постах:

const recommendations = post.recomendations.map((s) => getPostBySlug(s));

И передаём их в компонент PostPreview, который рендерим после тела статьи:

{recommendations.map((r) => (
    <PostPreview
    key={r.slug}
    title={r.title}
    coverImage={r.coverImage}
    date={r.date}
    slug={r.slug}
    excerpt={r.excerpt}
    />
))}

В результате блок рекомендаций выглядит следующим образом:

Добавляем блок "Поделиться в соц. сетях"

Для кнопок соц. сетей мы использовали готовое решение - пакет react-share.

Установим его:

npm i react-share

Далее всё просто, импортим оттуда кнопки и иконки:

"use client";

import { TelegramIcon, TelegramShareButton } from "react-share";

И передаём в них базовые данные о посте:

const ICON_SIZE = 40;

<TelegramShareButton url={url} title={post.title}>
  <TelegramIcon
    size={ICON_SIZE}
    className="rounded-3xl grayscale hover:grayscale-0"
  />
</TelegramShareButton>

С кнопками соц. сетей всё просто. Но нам хотелось ещё добавить возможность использовать нативный механизм "поделиться" на мобильных устройствах и просто удобно копировать ссылку на статью на десктопах.

Поэтому мы решил сделать свою кнопку.

С разметкой там всё просто, поэтому остановлюсь только на интересном, а именно на использовании navigator.share API.

Сначала подготовим данные:

const shareData = {
  title: post.title,
  text: post.description,
  url: post.url,
};

Затем вызовем navigator.share:

const handler = async () => {
  try {
    await navigator.share(shareData);
  } catch (e) {
    // Тут нужен фоллбек на копирование ссылки
    writeToClipboard(post.url);
  }
};

Нужно учитывать что navigator.share может быть недоступен по множеству причин, поэтому я добавил фоллбек на запись ссылки в clipboard.

Но и запись в clipboard может быть недоступен по множеству причин, поэтому и это надо учитывать.

const writeToClipboard = async (text: string) => {
  try {
    await navigator.clipboard.writeText(text);
  } catch (error) {
    console.error((error as Error).message);
  }
};

А вот так этот блок выглядит при включенном Ad Block:

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

На этом всё! 🎉

В живую результат статьи можно увидеть ниже 🙂

⚠️ Изначально статья была опубликована в 2024 году, в старом блоге проекта по адресу alexeybaranov.dev.

Данные в статье могли устареть. Если вы нашли ошибку, пожалуйста напишите нам.

Решили добавить Google Analytics на страницы блога для базового отслеживания переходов по страницам.

Если коротко, то есть очень много способов сделать это, в этой статье мы остановимся на двух из них:

• Старый способ, который мы использовали раньше;
• Новый способ, появившийся не так давно;

Старый способ

Ранее мы добавляли аналитику от гугла следующим образом:

import Script from "next/script";
import React from "react";

const GA_MEASUREMENT_ID = "G-1234567890"; //Не настоящий

type Props = {
  enabled: boolean;
};

const GtagContainer: React.FC<Props> = ({ enabled }) => {
  if (!enabled) return null;

  return (
    <>
      <Script
        src={`https://www.googletagmanager.com/gtag/js?id=${GA_MEASUREMENT_ID}`}
      />
      <Script id="google-analytics">
        {`
          window.dataLayer = window.dataLayer || [];
          function gtag(){dataLayer.push(arguments);}
          gtag('js', new Date());

          gtag('config', '${GA_MEASUREMENT_ID}');
        `}
      </Script>
    </>
  );
};

export default GtagContainer;

Новый способ

Теперь же Vercel выпустили пока ещё экспериментальный пакет @next/third-parties, с которым добавить аналитику становится чуть удобнее.

Установим его.

npm i @next/third-parties@latest

Далее добавим компонент GoogleAnalytics в RootLayout

import { GoogleAnalytics } from '@next/third-parties/google'

const GA_MEASUREMENT_ID = "G-1234567890"; //Не настоящий

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
      <GoogleAnalytics gaId={GA_MEASUREMENT_ID} />
    </html>
  )
}

Теперь всё должно работать.

На этом всё! 🎉

⚠️ Изначально статья была опубликована в 2024 году, в старом блоге проекта по адресу alexeybaranov.dev.

Данные в статье могли устареть. Если вы нашли ошибку, пожалуйста напишите нам.

Заметили в настройках сообщества в VK интересную настройку Импорт RSS.

А так как мы недавно добавили RSS фид, то мы сразу же решили её опробовать.

То как VK обрабатывает фид - тайна за семью печатями. В документации мы не нашли никаких подробностей. Там даже описания этой функции нет.

Настройка просто есть, кому надо - тот разберётся.

Нам надо, мы начали разбираться 🙂

Тестируем настройку

Итак, выставляем настройку следующим образом:

Теперь выкладываем фид и ждём.

Через несколько минут получаем результат!

На этом можно было бы и остановиться, но...

Что там было про "Публиковать в виде статьи"?

Тестируем настройку "Публиковать в виде статьи"

Меняем настройки:

• Генерим фид;
• Загружаем его в бакет;
• Ждём;

И получаем следующий результат:

При этом если кликнуть на статью, то она пустая внутри:

Добавляем содержимое статьи

Статья пустая внутри, потому что я не пишу в RSS фид содержимое статьи.

Это легко исправить. Добавляем в код для генерации фида содержимое:

allPosts.forEach((post) => {
  console.log(`Adding rss item for post ${post.slug}`);
  feed.addItem({
    // ...
    content: post.content,
  });
});

Снова проверяем результат:

Кажется что-то пошло не так. А что с содержимым статьи?

Становится очевидно что причина в том, что markdown не поддерживается

Значит попробуем добавлять в фид HTML разметку.

Снова меняем код генерации фида:

for (const post of allPosts) {
  console.log(`Adding VK item for post ${post.slug}`);

  const content = await markdownToHtml(post.content);

  feed.addItem({
    //..
    content: content,
  });
}

Проверяем результат:

А что с содержимым статьи?

Видимо VK не поддерживает якорные ссылки...

А что ещё он не поддерживает?

Добавляем ещё больше разного содержимого в статью:

• Изображения с относительным путём;
• Изображения с абсолютным путём;
• Блоки кода;

Результат:

Выводы

Выводы:

• Изображения с относительным путём - работают;
• Изображения с абсолютным путём - работают;
• Блоки кода - не работают;

С этим можно жить 🙂

На этом всё, примеры автопостинга, вы всегда можете посмотреть в нашем сообществе во Вконтакте! 🎉

⚠️ Изначально статья была опубликована в 2024 году, в старом блоге проекта по адресу alexeybaranov.dev.

Данные в статье могли устареть. Если вы нашли ошибку, пожалуйста напишите нам.

Заметили большое количество грамматических, орфографических и пунктуационных ошибок в текстах статей нашего блога.

Поняли что с этим надо бороться и начали искать варианты.

Посты мы пишем в markdown файлах, используя VS Code, поэтому начали искать линтер с возможностью проверки грамматики, орфографии и пунктуации.

Расширение code-spell-checker

Ранее мы уже использовали расширение code-spell-checker поэтому решили попробовать его и в этот раз.

Но сразу столкнулись с парой проблем:

• отсутствие поддержки русского языка из коробки;
• отсутствие проверки функций проверки грамматики и пунктуации;

Первая проблема легко решается установкой расширения с русским словарём russian-code-spell-checker.

А вот вторая проблема не решается в рамках данного решения.

LTеX

Довольно быстро нашли другое решение - LTеX.

Основные особенности LTeX:

• Поддержка Markdown, BibTEX, ConTEXt, LATEX, Org, reStructuredText, R Sweave, XHTML;
• Работает полностью локально, не делает запросов в интернет;
• Поддержка более 20 языков, в том числе русского;
• Поддержка Quick fix и подсветка ошибок;
• Поддержка пользовательских словарей;
• Нормальная документация;

Настройка расширения для VS code

Для того чтобы включить и использовать LTeX для русского языка в VS Code надо:

• Установить расширение;
• В настройках расширения, либо в файле settings.json установить следующие настройки:

  "ltex.language": "ru-RU",
  "ltex.additionalRules.motherTongue": "ru-RU"

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

Вот так выглядит подсветка ошибок в файле:

Вот так ошибки выглядят при наведении на них:

Вот так выглядит меню Quick fix:

Так же можно добавлять слова и правила в исключения:

При этом генерируются .txt файлы с добавленными словами и исключениями для каждого языка.

Пример ltex.dictionary.ru-RU.txt:

бакет
захостить

На этом всё! 🎉

⚠️ Изначально статья была опубликована в 2024 году, в старом блоге проекта по адресу alexeybaranov.dev.

Данные в статье могли устареть. Если вы нашли ошибку, пожалуйста напишите нам.

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

Пришло время сделать выдачу ещё лучше, а также поработать над выдачей в других поисковиках. Сделать это можно добавив на страницы разметку JSON-LD.

Что такое JSON-LD?

JSON-LD (JSON Lightweight Linked Data format) — это формат метаданных для поисковых систем о типе контента на каждой странице. В теории, наличие подобной разметки на сайте приводит к более высоким результатам в поисковой выдаче.

JSON-LD выглядит так:

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Добавляем JSON-LD разметку к блогу на Next.js",
  "description": "Инструкция по добавлению JSON-LD разметки к блогу на Next.js",
  "datePublished": "2024-05-18",
  "genre": "Technology",
  "author": {
    "@type": "Person",
    "name": "Алексей Баранов",
    "url": "https://baranov.guru"
  },
  "image": "https://baranov.guru/assets/posts/nextjs-json-ld/cover.webp"
}

Для чего нужен JSON-LD?

В поисковой выдаче Яндекса есть, как минимум, 2 элемента, которые напрямую зависят от JSON-LD:

• Навигационные цепочки - они же хлебные крошки;
• Сниппет Вопрос-ответ;

С поисковой выдачей Google всё ещё интереснее. Они называют такую разметку Структурированными данными.

В документации для разработчиков есть целый раздел посвящённый Структурированным данным и JSON-LD.

От Структурированных данных зависят такие функции поисковой выдачи как:

• Статья - название говорит само за себя;
• Строка навигации - аналог Навигационных цепочек Яндекса;
• Карусель - аналог Турбо карусели Яндекса;
• Часто задаваемые вопросы - аналог Вопрос-ответ от Яндекса;
• Товары - описание товаров и их характеристик;
• Видео - описание и основные моменты видео;
• Организация - название, часы работы, телефоны и прочее;
• Мероприятие - где и когда состоится;

и многие другие (я насчитал 36 штук).

Для начала мне хватит просто Навигационных цепочек и теоретического улучшения позиций в выдаче 🙂

Итак, для добавления JSON-LD нам нужно:

• Сформировать описание в формате JSON-LD;
• Добавить его на страницу;
• Протестировать что всё работает;

Ссылка на конечный результат.

Формирование JSON-LD

Как не трудно догадаться из названия, JSON-LD - это JSON объект, составленный по определённой схеме. Для валидации схемы уже есть npm пакет schema-dts.

Установим его:

npm i schema-dts

Далее создадим объект для поста этого блога.

import { BlogPosting, WithContext } from "schema-dts";

export const URL_BASE = "https://baranov.guru";
export const HOME_OG_IMAGE_URL = "https://baranov.guru/logo.webp";

const blogPosting: WithContext<BlogPosting> = {
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  name: post.title,
  headline: post.title,
  description: post.description,
  datePublished: new Date(post.date).toISOString(),
  genre: "Technology",
  author: {
    "@type": "Person",
    name: post.author.name,
    url: `${URL_BASE}/about`,
  },
  publisher: {
    "@type": "Organization",
    name: "Алексей Баранов. Блог",
    logo: {
      "@type": "ImageObject",
      url: HOME_OG_IMAGE_URL,
    },
  },
  image: [`${URL_BASE}${post.ogImage.url}`],
  mainEntityOfPage: {
    "@type": "WebPage",
    "@id": `${URL_BASE}/posts/${post.slug}`,
  },
  inLanguage: "ru-RU",
};

Теперь необходимо сформировать BreadcrumbList для Навигационных цепочек:

import { BreadcrumbList, WithContext } from "schema-dts";

export const URL_BASE = "https://baranov.guru";

const breadcrumbList: WithContext<BreadcrumbList> = {
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  itemListElement: [
    {
      "@type": "ListItem",
      position: 1,
      name: "Посты",
      item: `${URL_BASE}/posts`,
    },
    {
      "@type": "ListItem",
      position: 2,
      name: post.title,
      item: `${URL_BASE}/posts/${post.slug}`,
    },
  ],
};

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

import { VideoObject, WithContext } from "schema-dts";

const videoStructuredData: WithContext<VideoObject> = {
  "@context": "https://schema.org",
  "@type": "VideoObject",
  name: post.title,
  description: post.description,
  thumbnailUrl: `https://i.ytimg.com/vi/${post.youtubeId}/hqdefault.jpg`, // Миниатюра видео
  uploadDate: new Date(post.date).toISOString(),
  contentUrl: `https://www.youtube.com/watch?v=${post.youtubeId}`, // Ссылка на видео на Youtube
  embedUrl: `https://www.youtube.com/embed/${post.youtubeId}`, // Ссылка на встроенное видео с Youtube
};

Объединяем всё это вместе в один объект:

const jsonLd = [blogPosting, breadcrumbList, videoStructuredData];

Добавление на страницу

Для того чтобы добавить разметку на страницу, создадим компонент JsonLd:

import React from "react";

type Props = {
  data: unknown;
};

const JsonLd: React.FC<Props> = ({ data }) => (
  <script
    type="application/ld+json"
    dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }}
  />
);

export default JsonLd;

Далее просто добавляем этот компонент на страницу с постом и передаём в него данные:

const jsonLd = [blogPosting, breadcrumbList, videoStructuredData];

<JsonLd data={jsonLd} />

Теперь необходимо проверить что у нас всё получилось как надо.

Тестирование

Заходим на страницу и смотрим разметку:

Итак, разметка появилась на странице.

Теперь необходимо проверить что разметка валидная. Для этого у гугла есть специальный инструмент для проверки.

Вбиваем в него адрес нашей страницы, если она уже где-то хостится, либо HTML-разметку страницы.

Отлично, на этом всё! 🎉

Теперь выкладываем страницу и ждём индексации.

Готовое решение

Прикладываю полный код решения.

// types.ts
export type Author = {
  name: string;
  picture: string;
};

export type Post = {
  slug: string;
  title: string;
  description: string;
  date: string;
  coverImage: string;
  author: Author;
  excerpt: string;
  ogImage: {
    url: string;
  };
  keywords: string[];
  content: string;
  preview?: boolean;
  youtubeId?: string;
};

// src/lib/jsonLd.ts
import {
  BlogPosting,
  BreadcrumbList,
  VideoObject,
  WithContext,
} from "schema-dts";

import { Post } from "@/interfaces/post";

import { HOME_OG_IMAGE_URL, URL_BASE } from "./constants";

export const getPostJsonLd = (post: Post) => {
  const blogPosting: WithContext<BlogPosting> = {
    "@context": "https://schema.org",
    "@type": "BlogPosting",
    name: post.title,
    headline: post.title,
    description: post.description,
    datePublished: new Date(post.date).toISOString(),
    genre: "Technology",
    author: {
      "@type": "Person",
      name: post.author.name,
      url: `${URL_BASE}/about`,
    },
    publisher: {
      "@type": "Organization",
      name: "Алексей Баранов. Блог",
      logo: {
        "@type": "ImageObject",
        url: HOME_OG_IMAGE_URL,
      },
    },
    image: [`${URL_BASE}${post.ogImage.url}`],
    mainEntityOfPage: {
      "@type": "WebPage",
      "@id": `${URL_BASE}/posts/${post.slug}`,
    },
    inLanguage: "ru-RU",
  };

  const breadcrumbList: WithContext<BreadcrumbList> = {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    itemListElement: [
      {
        "@type": "ListItem",
        position: 1,
        name: "Посты",
        item: `${URL_BASE}/posts`,
      },
      {
        "@type": "ListItem",
        position: 2,
        name: post.title,
      },
    ],
  };

  if (post.youtubeId) {
    const videoStructuredData: WithContext<VideoObject> = {
      "@context": "https://schema.org",
      "@type": "VideoObject",
      name: post.title,
      description: post.description,
      thumbnailUrl: `https://i.ytimg.com/vi/${post.youtubeId}/hqdefault.jpg`, // this is the thumbnail for the video straight from youtube
      uploadDate: new Date(post.date).toISOString(),
      contentUrl: `https://www.youtube.com/watch?v=${post.youtubeId}`, // this is the URL for the video on youtube
      embedUrl: `https://www.youtube.com/embed/${post.youtubeId}`, // this is the URL for the video embed on youtube
    };
    return [blogPosting, breadcrumbList, videoStructuredData];
  }

  return [blogPosting, breadcrumbList];
};

// src/app/posts/[slug]/page.ts
export default async function Post({ params }: Params) {
  const jsonLd = getPostJsonLd(post);

  return (
    <>
      <JsonLd data={jsonLd} />
      ...
      </>
  );
}

На этом всё. Спасибо за внимание!

⚠️ 7 февраля 2025 года Yandex анонсировал прекращение поддержки Turbo страниц.

Поэтому содержимое этой статьи устарело и оставлено здесь просто для истории.

Для того чтобы красиво отображаться в поисковой выдаче Яндекса решил добавить Яндекс Турбо-страницы к этому блогу.

Вот так это выглядит:

Процесс этот простой и проходит в 2 основных шага:

• Сгенерировать фид;
• Добавить информацию о нём в Яндекс Вебмастер;

Генерация фида

Процесс генерации фида почти ничем не отличается от генерации RSS фида.

Для того чтобы сгенерировать фид, необходимо:

• получить список всех постов и их метаданные,
• сформировать Tурбофид в специальном формате
• делать так при каждой сборке

Получение постов и их метаданных

Так как посты у меня хранятся в репозитории проекта в формате .md, то для получения всех постов мне просто необходимо:

• получить список файлов в директории с постами,
• пройти по каждому посту и получить метаданные

Для получения метаданных я воспользовался пакетом gray-matter

npm i gray-matter

В результате получился такой код:

import fs from "fs";
import { join } from "path";

import matter from "gray-matter";

import { Post } from "@/interfaces/post";

const postsDirectory = join(process.cwd(), "_posts");

export function getPostBySlug(slug: string) {
  const realSlug = slug.replace(/\.md$/, "");
  const fullPath = join(postsDirectory, `${realSlug}.md`);
  const fileContents = fs.readFileSync(fullPath, "utf8");
  const { data, content } = matter(fileContents);

  return { ...data, slug: realSlug, content } as Post;
}

export function getAllPosts(): Post[] {
  const slugs = fs.readdirSync(postsDirectory);
  const posts = slugs
    .map((slug) => getPostBySlug(slug))
    // сортируем посты по дате в порядке убывания
    .sort((a, b) => (a.date > b.date ? -1 : 1));
  return posts;
}

Формирование Турбо фида

Для того чтобы добавить RSS фид я воспользовался пакетом turbo-rss.

Устанавливаем его командой:

npm i turbo-rss

Алгоритм следующий:

• сформировать описание фида,
• пройти по списку постов, и сформировать feedItem для каждого поста,
• записать всё в .xml файл

У меня получился вот такой скрипт:

import fs from "fs";

import path from "node:path";

import { getAllPosts } from "../api";
import { markdownToTurboHtml } from "../markdownToHtml";

// eslint-disable-next-line @typescript-eslint/no-var-requires
const TR = require("turbo-rss");

export default async function generateTurboFeed() {
  console.log("Generating Turbo feed...");

  const allPosts = await getAllPosts();
  console.log(`Found ${allPosts.length} posts.`);

  const site_url = "https://baranov.guru";

  const feedOptions = {
    language: "ru",
    title: "Baranov.Guru | RSS feed",
    description:
      "Личный блог. Пишу о разработке софта, предпринимательстве и просто об интересных мне вещах",
    id: site_url,
    link: site_url,
    image: `${site_url}/assets/authors/avatar.webp`,
    favicon: `${site_url}/favicon/favicon.ico`,
    copyright: `All rights reserved ${new Date().getFullYear()}, Baranov.Guru`,
    generator: "Feed for Node.js",
    feedLinks: {
      rss2: `${site_url}/rss.xml`,
    },
  };

  const feed = new TR(feedOptions);

  for (const post of allPosts) {
    console.log(`Adding turbo item for post ${post.slug}`);
    const content = await markdownToTurboHtml(post.content);
    feed.item({
      title: post.title,
      id: `${site_url}/posts/${post.slug}`,
      description: post.description,
      image_url: `${site_url}${post.coverImage}`,
      url: `${site_url}/posts/${post.slug}`,
      author: post.author.name,
      date: new Date(post.date),
      content: content,
      menu: [
        {
          link: "http://alexeybaranov.dev",
          text: "Главная страница",
        },
      ],
    });
  }

  const feedPath = path.resolve("./out/turbo.xml");

  fs.writeFileSync(feedPath, feed.xml());

  console.log(`Rss feed is written to ${feedPath}.`);
}

Автоматизация сборки фида

Добавляем в package.json скрипт postbuild.

{
  "scripts": {
    "build": "next build",
    "postbuild": "npx tsx ./src/lib/feeds/generate.ts"
  }
}

Он запустится сразу же после успешной сборки проекта и запишет фид в папку с результатами сборки.

Добавление информации о фиде в Яндекс Вебмастер

Теперь осталось только добавить информацию о фиде в поисковую машину Яндекса.

Заходим в Яндекс Вебмастер.

Переходим на вкладку Турбо-страницы для контентных сайтов --> Источники.

Добавляем фид удобным нам способом:

• Руками, через форму;
• Через API;

Добавить фид надо всего 1 раз, поэтому я не стал заморачиваться с API и просто добавил ссылку на фид руками.

Всё готово! 🎉

⚠️ Изначально статья была опубликована в 2024 году, в старом блоге проекта по адресу alexeybaranov.dev.

Данные в статье могли устареть. Если вы нашли ошибку, пожалуйста напишите нам.

Одним из важнейших аспектов поддержки любого сайта является работа с аналитикой.

Аналитические счётчики для сайтов играют ключевую роль в понимании поведения посетителей и оптимизации веб-ресурсов. Они позволяют владельцам сайтов собирать ценные данные о посетителях, источниках переходов, поведении пользователей на страницах сайта и многом другом.

В этой статье мы расскажем о нескольких способах подключения счётчика Яндекс Метрики к Next.js приложению.

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

Написание собственного решения

Итак, нам нужно:

• создать компонент, который будет загружать счётчик на страницу,
• добавить этот компонент в Root Layout,
• научиться обрабатывать события перехода между страницами,
• а также научиться прокидывать любые другие события в счётчик

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

Итак, наш компонент должен:

• Загрузить скрипт Яндекс Метрики с указанными настройками;
• Предоставить методы для работы с API Яндекс Метрики;

Загрузка скрипта

Добавим компонент YandexMetrikaInitializer.

Он будет принимать id счётчика и набор параметров счётчика и рендерить Script-компонент, с кодом загрузки счётчика метрики с указанными параметрами.

Это тот самый код, который можно получить в личном кабинете Яндекс Метрики при создании счётчика.

В итоге должно получиться нечто похожее:

"use client";

import Script from "next/script";
import React from "react";

import { YandexMetrikaInitParameters } from "./types";

type Props = {
  id: number;
  initParameters: YandexMetrikaInitParameters;
};

const YandexMetrikaInitializer: React.FC<Props> = ({ id, initParameters }) => {
  /* eslint-disable @next/next/no-img-element */
  return (
    <>
      <Script type="text/javascript" id={`ym_${id}`}>
        {`(function (m, e, t, r, i, k, a) {
  m[i] =
    m[i] ||
    function () {
      (m[i].a = m[i].a || []).push(arguments);
    };
  m[i].l = 1 * new Date();
  for (var j = 0; j < document.scripts.length; j++) {
    if (document.scripts[j].src === r) {
      return;
    }
  }
  (k = e.createElement(t)),
    (a = e.getElementsByTagName(t)[0]),
    (k.async = 1),
    (k.src = r),
    a.parentNode.insertBefore(k, a);
})(window, document, "script", "https://mc.yandex.ru/metrika/tag.js", "ym");

ym(${id}, "init", ${JSON.stringify(initParameters)});`}
      </Script>
      <noscript>
        <div>
          <img
            src={`https://mc.yandex.ru/watch/${id}`}
            style={{ position: "absolute", left: "-9999px;" }}
            alt=""
          />
        </div>
      </noscript>
    </>
  );
};

export default MyYandexMetrikaInitializer;

Набор параметров счётчика

Вот список параметров счётчика, взятый из официальной доки.

export type YandexMetrikaInitParameters = {
  accurateTrackBounce?: boolean | number;
  childIframe?: boolean;
  clickmap?: boolean;
  defer?: boolean;
  ecommerce?: boolean | string | [];
  params?: unknown | [];
  userParams?: unknown;
  trackHash?: boolean;
  trackLinks?: boolean;
  trustedDomains?: string[];
  type?: number;
  webvisor?: boolean;
  triggerEvent?: boolean;
  sendTitle?: boolean;
};