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

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

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

Обновление Astro

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

# Обновление до Astro v2.x
npm install astro@latest

# Пример: обновление интеграций React и Tailwind
npm install @astrojs/react@latest @astrojs/tailwind@latest

# Обновление до Astro v2.x
pnpm add astro@latest

# Пример: обновление интеграций React и Tailwind
pnpm add @astrojs/react@latest @astrojs/tailwind@latest

# Обновление до Astro v2.x
yarn add astro@latest

# Пример: обновление интеграций React и Tailwind
yarn add @astrojs/react@latest @astrojs/tailwind@latest

Изменения в Astro v2.0

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

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

Удалено: Поддержка Node 14

Срок службы Node 14 истекает в апреле 2023 года.

Astro v2.0 полностью отказывается от поддержки Node 14, чтобы все пользователи Astro могли воспользоваться более современными возможностями Node.

Что делать?

Убедитесь, что и ваша среда разработки, и среда развертывания используют Node 16.12.0 или более позднюю версию.

Проверьте локальную версию Node, используя:
Окно терминала
```
node -v
```
Если ваша локальная среда разработки нуждается в обновлении, установите Node.
Проверьте собственную документацию вашей среды развертывания, чтобы убедиться, что она поддерживает Node 16.

Вы можете указать Node 16.12.0 для вашего проекта Astro либо в настройках конфигурации приборной панели, либо в файле .nvmrc.

Зарезервировано: “src/content/`.

Astro v2.0 теперь включает API Collections для организации ваших Markdown и MDX файлов в коллекции контента. Этот API резервирует src/content/ в качестве специальной папки.

Что делать?

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

Изменено: `Astro.site` в конце слэша

В версии 1.x Astro следил за тем, чтобы URL, заданный в качестве site в файле astro.config.mjs, всегда содержал косую черту при обращении к нему с помощью Astro.site.

Astro v2.0 больше не изменяет значение site. Astro.site будет использовать точное значение, и при желании необходимо указать косую черту.

Что делать?

В файле astro.config.mjs добавьте косую черту к URL, заданному в site.

import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://example.com',
  site: 'https://example.com/',
});

Изменено: папка `_astro/` для ассетов сборки

В версии 1.x ассеты собирались в различных местах, включая assets/, chunks/ и в корне выходных данных сборки.

В Astro v2.0 все ассеты сборки перемещены и унифицированы в новую папку _astro/.

Директорияdist/
- Директория_astro
  - client.9218e799.js
  - index.df3f880e0.css

Вы можете управлять этим расположением с помощью новой опции конфигурации build.assets.

Что делать?

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

Изменено: Конфигурация плагина Markdown

Удалено: `extendDefaultPlugins`.

В версии 1.x Astro использовал markdown.extendDefaultPlugins для повторного включения плагинов Astro по умолчанию при добавлении собственных плагинов Markdown.

В Astro v2.0 этот параметр полностью удален, поскольку его поведение теперь используется по умолчанию.

Применение плагинов remark и rehype в вашей конфигурации Markdown больше не отключает плагины Astro по умолчанию. GitHub-Flavored Markdown и Smartypants теперь применяются независимо от того, настроены ли пользовательские remarkPlugins или rehypePlugins.

Что делать?

Удалите extendDefaultPlugins в вашей конфигурации. Теперь это поведение Astro по умолчанию в версии 2.0, и вы можете удалить эту строку без какой-либо замены.

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    extendDefaultPlugins,
  }
});

Добавлено: `gfm` и `smartypants`.

В версии 1.x вы могли отключить оба стандартных плагина Astro для работы с Markdown (GitHub-Flavored Markdown и SmartyPants), установив markdown.extendDefaultPlugins: false.

В Astro v2.0 параметр markdown.extendDefaultPlugins: false заменен на отдельные булевы опции для индивидуального управления каждым из встроенных в Astro плагинов Markdown по умолчанию. Они включены по умолчанию и могут быть установлены на false независимо друг от друга.

Что делать?

Удалите extendDefaultPlugins: false и добавьте вместо этого флаги для отключения каждого плагина по отдельности.

markdown.gfm: false отключает GitHub-Flavored Markdown
markdown.smartypants: false отключает SmartyPants

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    extendDefaultPlugins: false,
    smartypants: false,
    gfm: false,
  }
});

Изменено: Конфигурация MDX-плагина

Заменено: `extendPlugins` заменено на `extendMarkdownConfig`.

В версии 1.x опция extendPlugins интеграции MDX управляла тем, как ваши MDX файлы должны наследовать вашу конфигурацию Markdown: всю вашу конфигурацию Markdown (markdown), или только плагины Astro по умолчанию (default).

В Astro v2.0 поведение, контролируемое mdx.extendPlugins, заменено тремя новыми, независимо настраиваемыми опциями, которые по умолчанию имеют значение true:

mdx.extendMarkdownConfig чтобы наследовать все или ничего из вашей конфигурации Markdown
mdx.gfm для включения или отключения GitHub-Flavored Markdown в MDX
mdx.smartypants для включения или отключения SmartyPants в MDX

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

Удалите extendPlugins: 'markdown' в вашей конфигурации. Теперь это поведение по умолчанию.

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [
    mdx({
      extendPlugins: 'markdown',
    }),
  ],
});

Замените extendPlugins: 'defaults' на extendMarkdownConfig: false и добавьте отдельные опции для GitHub-Flavored Markdown и SmartyPants, чтобы включить эти плагины по умолчанию по отдельности в MDX.

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [
    mdx({
      extendPlugins: 'defaults',
      extendMarkdownConfig: false,
      smartypants: true,
      gfm: true,
    }),
  ],
});

Добавлено: Больше опций конфигурации MDX для соответствия Markdown

Astro v2.0 позволяет вам теперь отдельно устанавливать все доступные опции конфигурации Markdown (кроме drafts) в конфигурации интеграции MDX.

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      remarkPlugins: [remarkPlugin2],
      gfm: false,
    })
  ]
});

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

Пересмотрите свою конфигурацию Markdown и MDX и сравните существующий конфиг с новыми доступными опциями.

Изменено: Доступ плагинов к frontmatter

В версии 1.x плагины remark и rehype не имели доступа к пользовательскому frontmatter. Astro объединял frontmatter плагина с frontmatter вашего файла, не передавая frontmatter файла вашим плагинам.

Astro v2.0 предоставляет плагинам remark и rehype доступ к пользовательскому frontmatter через инъекцию frontmatter. Это позволяет авторам плагинов изменять существующий frontmatter пользователя или вычислять новые свойства на основе других свойств.

Что делать?

Проверьте все написанные вами плагины remark и rehype, чтобы узнать, не изменилось ли их поведение. Обратите внимание, что data.astro.frontmatter теперь является полным frontmatter’ом документа Markdown или MDX, а не пустым объектом.

Изменено: Конфигурация RSS

В версии 1.x пакет RSS Astro позволял вам использовать items: import.meta.glob(...) для создания списка элементов RSS-ленты. Сейчас это использование устарело и со временем будет удалено.

В Astro v2.0 появилась обертка pagesGlobToRssItems() для свойства items.

Что делать?

Импортируйте, а затем оберните вашу существующую функцию, содержащую import.meta.glob(), помощником pagesGlobToRssItems().

import rss, {
  pagesGlobToRssItems
} from '@astrojs/rss';

export async function get(context) {
  return rss({
    items: await pagesGlobToRssItems(
      import.meta.glob('./blog/*.{md,mdx}'),
    ),
  });
}

Изменено: Поддержка Svelte IDE

Astro v2.0 требует наличия файла svelte.config.js в вашем проекте, если вы используете [интеграцию @astrojs/svelte`](/ru/guides/integrations-guide/svelte/). Это необходимо для обеспечения автодополнения в IDE.

Что делать?

Добавьте файл `svelte.config.js в корень вашего проекта:

import { vitePreprocess } from '@astrojs/svelte';

export default {
  preprocess: vitePreprocess(),
};

Для новых пользователей этот файл будет добавлен автоматически при выполнении команды astro add svelte.

Удалено: `legacy.astroFlavoredMarkdown`.

В версии 1.0 Astro переместил старый Astro-Flavored Markdown (также известный как Components in Markdown) в унаследованную функцию.

В Astro v2.0 опция legacy.astroFlavoredMarkdown полностью удалена. Импорт и использование компонентов в файлах .md больше не будет работать.

Что делать?

Удалите этот флаг наследия. Он больше не доступен в Astro.

export default defineConfig({
  legacy: {
    astroFlavoredMarkdown: true,
  },
})

Если вы использовали эту функцию в версии 1.x, мы рекомендуем использовать интеграцию MDX, которая позволяет комбинировать компоненты и JSX-выражения с синтаксисом Markdown.

Удалено: `Astro.resolve()`.

В версии 0.24 Astro устарела функция Astro.resolve() для получения разрешенных URL-адресов активов, на которые вы можете захотеть сослаться в браузере.

В Astro v2.0 эта опция полностью удалена. Использование Astro.resolve() в вашем коде приведет к ошибке.

Что делать?

Вместо этого разрешайте пути к активам с помощью import. Например:

---
import 'style.css';
import imageUrl from './image.png';
---

<img src={imageUrl} />

Удалено: `Astro.fetchContent()`.

В версии 0.26 Astro устарела опция Astro.fetchContent() для получения данных из ваших локальных файлов Markdown.

В версии Astro v2.0 эта опция полностью удалена. Использование Astro.fetchContent() в вашем коде приведет к ошибке.

Что делать?

Используйте Astro.glob() для получения файлов Markdown, или перейдите на Коллекцию Контента.

---
const allPosts = await Astro.glob('./posts/*.md');
---

Удалено: `Astro.canonicalURL`.

В версии 1.0 Astro устарела функция Astro.canonicalURL для построения канонического URL.

В Astro v2.0 эта опция полностью удалена. Использование Astro.canonicalURL в вашем коде приведет к ошибке.

Что делать?

Используйте Astro.url для построения канонического URL.

---
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
---

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

Astro v2.0 обновляется с Vite 3 до Vite 4, который выйдет в декабре 2022 года.

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

Никаких изменений в вашем коде не должно быть! Мы выполнили большую часть обновления за вас внутри Astro; однако некоторые тонкости поведения Vite могут измениться между версиями.

Обратитесь к официальному руководству Vite Migration Guide, если у вас возникнут проблемы.

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

Удалите следующие экспериментальные флаги из astro.config.mjs:

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    contentCollections: true,
    prerender: true,
    errorOverlay: true,
  },
})

Эти функции теперь доступны по умолчанию:

Коллекции контента как способ управления файлами Markdown и MDX с безопасностью типов.
Предрендеринг отдельных страниц в статический HTML при использовании SSR для повышения скорости и кэшируемости.
Переработанный оверлей сообщений об ошибках.

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

В настоящее время известных проблем нет.

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

Обновление Astro

Изменения в Astro v2.0

Удалено: Поддержка Node 14

Что делать?

Зарезервировано: “src/content/`.

Что делать?

Изменено: Astro.site в конце слэша

Что делать?

Изменено: папка _astro/ для ассетов сборки

Что делать?

Изменено: Конфигурация плагина Markdown

Удалено: extendDefaultPlugins.

Что делать?

Добавлено: gfm и smartypants.

Что делать?

Изменено: Конфигурация MDX-плагина

Заменено: extendPlugins заменено на extendMarkdownConfig.

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

Добавлено: Больше опций конфигурации MDX для соответствия Markdown

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

Изменено: Доступ плагинов к frontmatter

Что делать?

Изменено: Конфигурация RSS

Что делать?

Изменено: Поддержка Svelte IDE

Что делать?

Удалено: legacy.astroFlavoredMarkdown.

Что делать?

Удалено: Astro.resolve().

Что делать?

Удалено: Astro.fetchContent().

Что делать?

Удалено: Astro.canonicalURL.

Что делать?

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

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

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

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

Изменено: `Astro.site` в конце слэша

Изменено: папка `_astro/` для ассетов сборки

Удалено: `extendDefaultPlugins`.

Добавлено: `gfm` и `smartypants`.

Заменено: `extendPlugins` заменено на `extendMarkdownConfig`.

Удалено: `legacy.astroFlavoredMarkdown`.

Удалено: `Astro.resolve()`.

Удалено: `Astro.fetchContent()`.

Удалено: `Astro.canonicalURL`.