Обновление до Astro v4

Это руководство поможет вам перейти с Astro v3 на Astro v4.

Вам нужно обновить старый проект до v3? Смотрите наше руководство по миграции старых проектов.

Нужно посмотреть документацию по v3? Посетите этот сайт старая версия документации (не поддерживаемый снимок v3.6).

Обновление Astro

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

# Обновление Astro и официальных интеграций
npx @astrojs/upgrade

# Обновление Astro и официальных интеграций
pnpm dlx @astrojs/upgrade

# Обновление Astro и официальных интеграций
yarn dlx @astrojs/upgrade

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

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

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

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

Удалены экспериментальные флаги Astro v4.0

Удалите экспериментальный флаг devOverlay и переместите любую конфигурацию i18n на верхний уровень в astro.config.mjs:

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    devOverlay: true,
    i18n: {
      defaultLocale: "en",
      locales: ["en", "fr", "pt-br", "es"],
    }
  },
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
  },
})

Эти конфигурации, i18n и переименованная devToolbar, теперь доступны в Astro v4.0.

Подробнее об этих двух интересных функциях и многом другом читайте в посте v4.0 в Блоге!

Обновления

Любые крупные обновления зависимостей Astro могут привести к изменениям в вашем проекте.

Обновлено: Vite 5.0

В Astro v3.0 Vite 4 использовался в качестве сервера разработки и производственного бандлера.

Astro v4.0 переходит с Vite 4 на Vite 5.

Что делать?

Если вы используете специфические для Vite плагины, конфигурации или API, проверьте руководство по миграции Vite на наличие изменений и обновите свой проект при необходимости. В самом Astro никаких изменений нет.

Обновлено: зависимости unified, remark и rehype

В Astro v3.x для обработки Markdown и MDX использовался unified v10 и связанные с ним совместимые пакеты remark/rehype.

Astro v4.0 обновляет unified до v11 и другие пакеты remark/rehype до последней версии.

Что делать?

Если вы использовали пользовательские пакеты remark/rehype, обновите их до последней версии с помощью менеджера пакетов, чтобы убедиться, что они поддерживают unified v11. Используемые вами пакеты можно найти в файле astro.config.mjs.

При использовании активно обновляемых пакетов не должно произойти никаких существенных изменений, но некоторые пакеты могут быть еще не совместимы с unified v11. Перед развертыванием визуально проверьте свои Markdown/MDX-страницы, чтобы убедиться, что ваш сайт работает так, как нужно.

Разрушающие изменения

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

Если вам нужно обратиться к документации по проекту v3.x, вы можете просмотреть этот (не поддерживаемый) снимок документации до выхода v4.0.

Переименовано: `entrypoint` (API интеграций)

В Astro v3.x свойство API интеграций injectRoute, указывающее точку входа в маршрут, называлось entryPoint.

В Astro v4.0 это свойство переименовано в entrypoint, чтобы соответствовать другим API Astro. Свойство entryPoint устарело, но будет продолжать работать и выводить в журнал предупреждение с предложением обновить код.

Что мне делать?

Если у вас есть интеграции, использующие API injectRoute, переименуйте свойство entryPoint в entrypoint. Если вы автор библиотеки, которая хочет поддерживать и Astro 3, и Astro 4, вы можете указать и entryPoint, и entrypoint, и в этом случае предупреждение не будет регистрироваться.

injectRoute({
  pattern: '/fancy-dashboard',
  entryPoint: '@fancy/dashboard/dashboard.astro'
  entrypoint: '@fancy/dashboard/dashboard.astro'
});

Изменено: сигнатура `app.render` в API интеграций

В Astro v3.0 метод app.render() принимал routeData и locals как отдельные, необязательные аргументы.

В версии Astro v4.0 сигнатура метода app.render() была изменена. Теперь эти два свойства доступны в одном объекте. Объект и эти два свойства по-прежнему необязательны.

Что делать?

Если вы поддерживаете адаптер, текущая сигнатура будет работать до следующей основной версии. Чтобы перейти на новую сигнатуру, передавайте routeData и locals как свойства объекта, а не как несколько независимых аргументов.

app.render(request, routeData, locals)
app.render(request, { routeData, locals })

Изменено: адаптеры теперь должны указывать поддерживаемые функции

В Astro v3.x от адаптеров не требовалось указывать поддерживаемые ими функции.

Astro v4.0 требует, чтобы адаптеры передавали свойство supportedAstroFeatures{} для указания списка поддерживаемых ими функций. Это свойство больше не является необязательным.

Что мне делать?

Авторам адаптеров необходимо передавать свойство supportedAstroFeatures{}, чтобы указать список поддерживаемых ими функций.

export default function createIntegration() {
  return {
    name: '@matthewp/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@matthewp/my-adapter',
          serverEntrypoint: '@matthewp/my-adapter/server.js',
          supportedAstroFeatures: {
              staticOutput: 'stable'
          }
        });
      },
    },
  };
}

Удалено: свойство `path` языка Shiki

В Astro v3.x язык Shiki, переданный в markdown.shikiConfig.langs, автоматически преобразовывался в язык, совместимый с Shikiji. Shikiji - это внутренний инструментарий, используемый Astro для подсветки синтаксиса.

В Astro v4.0 удалена поддержка свойства path для языка Shiki, которое вызывало путаницу при настройке. Оно заменено импортом, который может быть передан в langs напрямую.

Что делать?

Вместо этого следует импортировать JSON-файл языка и передать его в опцию.

 import customLang from './custom.tmLanguage.json'

export default defineConfig({
  markdown: {
    shikiConfig: {
      langs: [
       { path: '../../custom.tmLanguage.json' },
       customLang,
      ],
    },
  },
})

Утратило актуальность

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

Некоторые устаревшие функции могут временно продолжать работать, пока не будут полностью удалены. Другие могут не иметь никакого эффекта или выдавать ошибку, побуждающую вас обновить код.

Утратило актуальность: `handleForms` для событий `submit` Анимаций Переходов

В Astro v3.x проекты, использующие компонент <ViewTransitions />, должны были отказаться от обработки событий submit для элементов form. Это делалось путем передачи свойства handleForms.

Astro v4.0 обрабатывает события submit для элементов form по умолчанию, когда используются <ViewTransitions />. Свойство handleForms было устаревшим и больше не имеет никакого значения.

Что делать?

Удалите свойство handleForms из компонента ViewTransitions. В нем больше нет необходимости.

---
import { ViewTransitions } from "astro:transitions";
---
<html>
  <head>
    <ViewTransitions handleForms />
  </head>
  <body>
    <!-- здесь всякие штуки -->
  </body>
</html>

Чтобы отказаться от обработки события submit, добавьте атрибут data-astro-reload к соответствующим элементам form.

<form action="/contact" data-astro-reload>
  <!-- -->
</form>

Ранее устаревшие функции теперь удалены

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

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

Удалено: возврат простых объектов из конечных точек

В Astro v3.x возврат простых объектов из конечных точек был устаревшим, но все еще поддерживался для сохранения совместимости с Astro v2. Для облегчения перехода была также предоставлена утилита ResponseWithEncoding.

В Astro v4.0 поддержка простых объектов удалена, и конечные точки должны всегда возвращать Response. Утилита ResponseWithEncoding также удалена в пользу правильного типа Response.

Что делать?

Обновите свои конечные точки, чтобы они возвращали объект Response напрямую.

export async function GET() {
  return { body: { "title": "Bob's blog" }};
  return new Response(JSON.stringify({ "title": "Bob's blog" }));
}

Чтобы отказаться от использования ResponseWithEncoding, переделайте ваш код для использования ArrayBuffer вместо этого:

export async function GET() {
  const file = await fs.readFile('./bob.png');
  return new ResponseWithEncoding(file.toString('binary'), undefined, 'binary');
  return new Response(file.buffer);
}

Удалено: `build.split` и `build.excludeMiddleware`

В Astro v3.0 опции конфигурации сборки build.split и build.excludeMiddleware были устаревшими и заменены на опции конфигурации адаптера для выполнения тех же задач.

В Astro v4.0 эти свойства полностью удалены.

Что делать?

Если вы используете устаревшие свойства build.split или build.excludeMiddleware, вам необходимо удалить их, так как они больше не существуют.

См. руководство по переходу на v3 для обновления этих устаревших свойств промежуточного ПО с конфигурациями адаптеров.

Удалено: `Astro.request.params`

В Astro v3.0 API Astro.request.params был устаревшим, но сохранен для обратной совместимости.

В Astro v4.0 эта опция полностью удалена.

Что делать?

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

const { id } = Astro.request.params;
const { id } = Astro.params;

Удалено: `markdown.drafts`

В Astro v3.0 использование markdown.drafts для управления созданием черновиков постов было устаревшим.

В Astro v4.0 эта опция полностью удалена.

Что делать?

Если вы использовали устаревшую опцию markdown.drafts, то теперь вы должны удалить ее, так как она больше не существует.

Чтобы продолжать помечать некоторые страницы в проекте как черновики, используйте миграцию в коллекции контента и ручную фильтрацию страниц со свойством draft: true frontmatter вместо этого.

Удалено: `getHeaders()`

В Astro v3.0 экспорт getHeaders() в Markdown был устаревшим и заменен на getHeadings().

В Astro v4.0 эта опция полностью удалена.

Что делать?

Если вы используете устаревшую опцию getHeaders(), вы должны удалить ее, так как она больше не существует. Замените все его экземпляры на getHeadings(), который является поддерживаемой заменой.

const posts = await Astro.glob('../content/blog/*.mdx');
const firstPostHeadings = posts.at(0).getHeaders();
const firstPostHeadings = posts.at(0).getHeadings();

Удалено: использование `rss` в `getStaticPaths()`

В Astro v3.0 использование устаревшего помощника rss в getStaticPaths() приводило к ошибке.

В Astro v4.0 этот помощник полностью удален.

Что делать?

Если вы используете неподдерживаемый метод генерации RSS-каналов, теперь вы должны использовать интеграцию @astrojs/rss для полной настройки RSS.

Удалено: имена HTTP-методов в нижнем регистре

В Astro v3.0 использование имен методов HTTP-запросов в нижнем регистре (get, post, put, all, del) было устаревшим.

В Astro v4.0 поддержка строчных имен полностью удалена. Все методы HTTP-запросов теперь должны быть написаны в верхнем регистре.

Что делать?

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

Обратитесь к руководству по миграции на v3 для руководства по использованию методов HTTP-запросов в верхнем регистре.

Удалено: 301 редирект при отсутствии префикса `base`

В Astro v3.x сервер предпросмотра Astro возвращал 301 перенаправление при доступе к ресурсам из публичной директории без пути base.

В Astro v4.0, когда сервер предпросмотра запущен, при доступе к ресурсам из публичной директории без префикса пути base возвращается статус 404, соответствующий поведению сервера разработки.

Что делать?

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

В следующем примере показан атрибут src, необходимый для отображения изображения из публичной папки, когда base: '/docs' настроен:

// Для доступа к public/images/my-image.png:

<img src="/docs/images/my-image.png" alt="">.

Удалено: автоконверсия `astro/client-image`

В Astro v3.x тип astro/client-image (используемый для устаревшей интеграции изображений) был удален, но автоматически преобразовывался в стандартный тип Astro astro/client, если был найден в вашем файле env.d.ts.

Astro v4.0 игнорирует astro/client-image и больше не будет обновлять env.d.ts для вас автоматически.

Что делать?

Если у вас были настроены типы для @astrojs/image в src/env.d.ts и обновление до v3.0 не привело к автоматическому преобразованию типов, замените тип astro/client-image вручную на astro/client.

  /// <reference types="astro/client-image" />
  /// <reference types="astro/client" />

Ресурсы сообщества

Знаете хороший ресурс по Astro v4.0? Отредактируйте эту страницу и добавьте ссылку ниже!

Известные проблемы

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

Обновление до Astro v4

Обновление Astro

Удалены экспериментальные флаги Astro v4.0

Обновления

Обновлено: Vite 5.0

Что делать?

Обновлено: зависимости unified, remark и rehype

Что делать?

Разрушающие изменения

Переименовано: entrypoint (API интеграций)

Что мне делать?

Изменено: сигнатура app.render в API интеграций

Что делать?

Изменено: адаптеры теперь должны указывать поддерживаемые функции

Что мне делать?

Удалено: свойство path языка Shiki

Что делать?

Утратило актуальность

Утратило актуальность: handleForms для событий submit Анимаций Переходов

Что делать?

Ранее устаревшие функции теперь удалены

Удалено: возврат простых объектов из конечных точек

Что делать?

Удалено: build.split и build.excludeMiddleware

Что делать?

Удалено: Astro.request.params

Что делать?

Удалено: markdown.drafts

Что делать?

Удалено: getHeaders()

Что делать?

Удалено: использование rss в getStaticPaths()

Что делать?

Удалено: имена HTTP-методов в нижнем регистре

Что делать?

Удалено: 301 редирект при отсутствии префикса base

Что делать?

Удалено: автоконверсия astro/client-image

Что делать?

Ресурсы сообщества

Известные проблемы

Переименовано: `entrypoint` (API интеграций)

Изменено: сигнатура `app.render` в API интеграций

Удалено: свойство `path` языка Shiki

Утратило актуальность: `handleForms` для событий `submit` Анимаций Переходов

Удалено: `build.split` и `build.excludeMiddleware`

Удалено: `Astro.request.params`

Удалено: `markdown.drafts`

Удалено: `getHeaders()`

Удалено: использование `rss` в `getStaticPaths()`

Удалено: 301 редирект при отсутствии префикса `base`

Удалено: автоконверсия `astro/client-image`