Релиз Start Mission Shekinah

Введение

Добро пожаловать в релиз шаблона Tailwind Nextjs Starter Blog v2.0. Этот выпуск представляет собой масштабный рефакторинг кодовой базы для поддержки каталога Next.js App и React Server Components. Читайте дальше, чтобы узнать о новых функциях и о том, как перейти с V1.

• Введение
• Переход с V1 на V2
• Next.js App Directory и React Server Components
• В первую очередь TypeScript
• Contentlayer
• Pliny
• Новый компонент поиска
  • Algolia
  • Kbar
• Обновления стилей и макетов
  • Тематическое оформление
  • Новые макеты
• Рекомендации по миграции
• Заключение
• Поддержка
• Лицензия

Переход с V1 на V2

Шаблон был впервые выпущен в январе 2021 года и с тех пор используется тысячами пользователей. Он представлен на Next.js Templates, Tailwind Awesome и других каталогах. Ежедневно его посещают более 200 уникальных посетителей с 1500-2000 просмотрами страниц, а также насчитывается 1,3 тысячи форков и множество других копий.

Большое спасибо сообществу пользователей и контрибьюторов за успех этого шаблона! Я создал небольшой видеомонтаж блогов (одновременно с обновлением списка в файле readme), чтобы продемонстрировать разнообразие блогов, созданных с использованием этого шаблона, и отпраздновать это достижение:

Версия 2 развивает успех предыдущей версии и представляет множество новых функций и улучшений. Кодовая база была переработана для поддержки каталога Next.js App и React Server Components. Теперь Markdown/MDX обрабатывается с помощью Contentlayer — типобезопасного SDK для контента, который проверяет и преобразует ваш контент в типобезопасные JSON-данные. Интеграция с Pliny, новой библиотекой, предоставляет готовые компоненты Next.js для улучшения статического сайта с аналитикой, комментариями и подпиской на рассылку. Также добавлен новый компонент поиска с командной палитрой (⌘-k).

Давайте рассмотрим новые функции и улучшения в V2.

Next.js App Directory и React Server Components

Теперь, когда Next.js App Router наконец стабилен и в основном совместим по функциям с Page Router, кодовая база была перенесена на новую настройку. Это позволяет использовать гибридный подход к рендерингу, используя React Server Components, генерируемые на стороне сервера для более быстрой загрузки страниц и уменьшения размера бандла, сохраняя при этом возможность добавлять клиентские React-компоненты для интерактивности.¹

С новыми возможностями приходит и новая парадигма, которую необходимо изучить. Я перенес кодовую базу, чтобы максимально использовать новые функции. Это включает изменения в структуре папок, разделение компонентов на серверные и клиентские, использование серверного получения данных и использование рекомендуемого API Metadata для SEO-оптимизации.

Хотя это в некоторой степени упрощает кодовую базу, это усложняет миграцию со старой версии. Если вы планируете мигрировать, я рекомендую начать с чистого шаблона и перенести в него ваши настройки и существующий контент. Подробнее см. в разделе рекомендации по миграции.

В первую очередь TypeScript

Кодовая база была перенесена на TypeScript. Хотя предыдущая версия шаблона была доступна как на JavaScript, так и на TypeScript, я решил сократить нагрузку на поддержку и сосредоточиться на TypeScript. Это также обеспечивает лучшую проверку типов и автодополнение кода в средах разработки.

TypeScript также идеально сочетается с нашим новым типобезопасным процессором разметки — Contentlayer.

Contentlayer

Contentlayer — это SDK для работы с контентом, который проверяет и преобразует ваш контент в типобезопасные JSON-данные, которые можно легко импортировать в приложение. Это делает работу с локальными файлами markdown или MDX невероятно простой. Он заменяет MDX-bundler и наш собственный процесс обработки markdown.

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

export const Blog = defineDocumentType(() => ({
  name: 'Blog',
  filePathPattern: 'blog/**/*.mdx',
  contentType: 'mdx',
  fields: {
    title: { type: 'string', required: true },
    date: { type: 'date', required: true },
    tags: { type: 'list', of: { type: 'string' }, default: [] },
    ...
  },
  computedFields: {
    readingTime: { type: 'json', resolve: (doc) => readingTime(doc.body.raw) },
    slug: {
      type: 'string',
      resolve: (doc) => doc._raw.flattenedPath.replace(/^.+?(\/)/, ''),
    }
    ...
  },
}))

Затем Contentlayer обрабатывает файлы MDX с помощью выбранных плагинов markdown remark или rehype, проверяет схему, генерирует определения типов и выводит JSON-файлы, которые можно легко импортировать на страницы. Горячая перезагрузка работает из коробки, поэтому изменения в файлах markdown сразу же отображаются в браузере!

Pliny

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

Для решения этой проблемы я вынес логику в отдельный репозиторий - Pliny. Pliny предоставляет готовые компоненты Next.js для улучшения статических сайтов:

• Аналитика
  • Google Analytics
  • Plausible Analytics
  • Simple Analytics
  • Umami Analytics
  • Posthog
• Комментарии
  • Disqus
  • Giscus
  • Utterances
• Рассылка (использует Next 13 API Routes)
  • Buttondown
  • Convertkit
  • Email Octopus
  • Klaviyo
  • Mailchimp
  • Revue
• Поиск с командной палитрой и таблицей стилей tailwind
  • Algolia
  • Kbar (локальный поиск)
• Вспомогательные UI-компоненты
  • Bleed
  • Рассылка / Блог-рассылка
  • Блоки Pre / Code
  • Оглавление

Выберите предпочитаемый сервис, изменив соответствующие поля в siteMetadata.js. Например, чтобы перейти с Umami Analytics на Plausible, измените следующие поля:

analytics: {
-   umamiAnalytics: {
-     // Используем переменную окружения, чтобы избежать клонирования нашего ID аналитики
-     umamiWebsiteId: process.env.NEXT_UMAMI_ID, // например, 123e4567-e89b-12d3-a456-426614174000
-   },
+    plausibleAnalytics: {
+      plausibleDataDomain: '', // например, tailwind-nextjs-starter-blog.vercel.app
+    },
},

Изменения в конфигурационном файле автоматически применяются к компонентам. Изменения в шаблоне не требуются.

Внутри Pliny экспортирует высокоуровневые компоненты, такие как <Analytics analyticsConfig={analyticsConfig}/> и <Comments commentsConfig={commentsConfig}/>, которые принимают объект конфигурации и отображают соответствующий компонент. Поскольку макеты определены на стороне сервера, Next.js может использовать объект конфигурации для определения, какой компонент отображать, и отправлять на клиент только необходимый бандл компонента.

Новый компонент поиска

Какой же блог в 2023 году без строки поиска с командной палитрой?

Добавлена одна из самых востребованных функций 🎉! Компонент поиска поддерживает 2 провайдера - Algolia и локальный поиск Kbar.

Algolia

Algolia Docsearch - популярный бесплатный сервис, используемый на многих сайтах документации. Он автоматически индексирует отправленный на индексацию веб-сайт и предоставляет результаты поиска через красивое модальное окно. Компонент pliny вдохновлен реализацией Docusaurus и поставляется с таблицей стилей, совместимой с темой Tailwind CSS.

Kbar

Kbar - это быстрый, переносимый и расширяемый интерфейс cmd+k. Реализация pliny использует kbar для создания диалогового окна локального поиска. Компонент загружает JSON-файл (по умолчанию search.json), созданный в процессе сборки contentlayer. Попробуйте нажать ⌘-k или ctrl-k, чтобы увидеть поисковую строку в действии!

Обновления стилей и макетов

Тематическое оформление

tailwind.config.js был обновлен для использования стандартных настроек типографики Tailwind, где это возможно, и встроенной поддержки темного режима через класс prose-invert. Это заменяет предыдущий класс prose-dark и его конфигурацию.

Основной цвет темы изменен с teal на pink, а основная серая тема - с neutral на gray.

Шрифт по умолчанию теперь Space Grotesk вместо Inter.

Новые макеты

Компоненты макетов, доступные в директории layouts, предоставляют простой способ настройки внешнего вида блога.²

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

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

Макет списка блогов по умолчанию также был обновлен и теперь включает боковую панель с тегами. Поисковая строка в предыдущем макете была заменена на новую командную палитру поиска. Чтобы вернуться к старому макету, просто замените компонент ListLayoutWithTags на оригинальный ListLayout на соответствующих страницах.

Рекомендации по миграции

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

Изменения стилей должны быть относительно незначительными, и их можно скопировать из старого tailwind.config.js в новый. При копировании может потребоваться добавить обратно класс prose-dark к компонентам, использующим типографику Tailwind. Обязательно измените импорт шрифта в корневом компоненте макета, чтобы использовать предпочитаемый шрифт.

Изменения в обработке MDX и схеме можно легко перенести в новую настройку Contentlayer. Если есть изменения в полях frontmatter, вы можете изменить тип документа в contentlayer.config.ts, чтобы включить новые поля. Пользовательские плагины можно добавить в свойства remarkPlugins и rehypePlugins в экспорте makeSource файла contentlayer.config.ts.

Макеты Markdown больше не загружаются автоматически из каталога layouts. Вместо этого их необходимо указать в объекте layouts, определенном в blog/[...slug]/page.tsx.³

Для переноса более крупных компонентов или страниц я рекомендую сначала указать их как клиентские компоненты с помощью директивы "use client". После того как они начнут корректно отображаться, вы можете разделить интерактивные компоненты (части, зависящие от хуков use) как клиентские, а оставшийся код оставить как серверный компонент. Для получения более подробной информации обратитесь к руководству по миграции Next.js.

Заключение

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

Поддержка

Используете шаблон? Поддержите проект, поставив звезду на GitHub, поделившись своим блогом и упомянув его в Twitter, или станьте спонсором проекта.

Лицензия

MIT © Timothy Lin