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

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

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

Обновление Astro

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

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

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

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

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

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

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

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

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

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    assets: true,
    viewTransitions: true,
  },
})

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

View Transitions для анимированных переходов между страницами и постоянных «островов». См. критические изменения в API View Transitions и рекомендации по обновлению, если вы использовали этот экспериментальный флаг.
Новый API для работы с изображениями astro:assets, включая новый компонент <Image /> и функцию getImage(). Пожалуйста, ознакомьтесь с подробными рекомендациями по обновлению изображений независимо от того, использовали ли вы этот экспериментальный флаг, чтобы понять, как это может повлиять на ваш проект.

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

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

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

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

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

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

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

Что делать?

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

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

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

Удалено: Поддержка TypeScript 4

В Astro v2.x предустановки tsconfig.json включают поддержку TypeScript 4.x и 5.x.

В Astro v3.0 предустановки tsconfig.json обновлены и поддерживают только TypeScript 5.x. Теперь Astro предполагает, что вы используете TypeScript 5.0 (март 2023 года), или что ваш редактор включает его (например, VS Code 1.77).

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

Если вы установили TypeScript локально, обновите его по крайней мере до версии 5.0.

npm install typescript@latest --save-dev

Удалено: `@astrojs/image`

В Astro v2.x предлагалась официальная интеграция с изображениями, которая включала компоненты Astro <Image /> и <Picture />.

В Astro v3.0 эта интеграция полностью удалена из кодовой базы. Новое решение Astro для изображений - встроенный API сервисов изображений: astro:assets.

Что делать?

Удалите интеграцию @astrojs/image из вашего проекта. Вам нужно будет не только удалить интеграцию, но и обновить или удалить все операторы импорта и существующие компоненты <Image /> и <Picture />. Также может потребоваться настройка предпочтительной службы обработки изображений по умолчанию.

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

Переход на astro:assets также принесет некоторые новые опции и возможности работы с изображениями, которые вы, возможно, захотите использовать. Пожалуйста, ознакомьтесь с полным руководством по обновлению изображений для v3.0 для получения подробной информации!

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

export default defineConfig({
  integrations: [
    image(),
  ]
})

Удалено: компонент `<Markdown />`

В версии Astro v1.x компонент <Markdown /> был устаревшим и перенесен во внешний пакет.

В Astro v3.0 полностью удален пакет @astrojs/markdown-component. Компонент Astro <Markdown /> больше не будет работать в вашем проекте.

Что делать?

Удалите все экземпляры пакета @astrojs/markdown-component.

---
import Markdown from '@astrojs/markdown-component';
---

Чтобы продолжить использовать подобный <Markdown /> компонент в своем коде, рассмотрите возможность использования интеграций сообщества, например astro-remote. Обязательно обновите импорт и атрибуты компонента <Markdown />, если это необходимо, в соответствии с документацией по интеграции.

В противном случае удалите все ссылки на импорт компонента Astro <Markdown /> и сам компонент в файлах .astro. Вам нужно будет переписать содержимое в HTML напрямую или импортировать Markdown из файла .md.

Удалено: устаревшие API версии 1.x

В версии 1.x Astro отказалась от первоначальных настроек конфигурации, а также от поддержки <style global> и <script hoist>. Однако они все еще поддерживались для обратной совместимости.

В Astro v3.0 эти устаревшие API полностью удалены. Вместо них следует использовать официально поддерживаемые настройки конфигурации (EN) и современные синтаксисы <style is:global> и <script>.

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

Если вы продолжаете использовать API версии 1.x, используйте новые API для каждой функции:

Утратившие актуальность настройки конфигурации: См. руководство по миграции 0.26 (EN)
Утратившие актуальность типы атрибутов скриптов/стилей: См. руководство по миграции 0.26 (EN)

Удалено: Частичные шиммы для веб-интерфейсов в коде сервера

В Astro v2.x Astro предоставлял частичные шиммы для веб-интерфейсов, таких как document или localStorage, в серверном коде. Эти шиммы часто были неполными и ненадежными.

В Astro v3.0 эти частичные шиммы полностью удалены. Веб-интерфейсы больше не доступны в рендеренном коде.

Что делать?

Если вы используете веб-интерфейсы в рендеренных компонентах, вам нужно либо сделать их использование условным, либо использовать клиентскую директиву client:only (EN).

Удалено: `image` из `astro:content` в схеме коллекций контента

В Astro v2.x API коллекций контента устарел экспорт image из astro:content для использования в схемах коллекций контента.

В Astro v3.0 этот экспорт полностью удален.

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

Если вы используете устаревший экспорт image() из astro:content, удалите его, так как он больше не существует. Вместо этого проверяйте изображения через помощник image из schema:

import { defineCollection, z, image } from "astro:content";
import { defineCollection, z } from "astro:content";

 defineCollection({
   schema: ({ image }) =>
     z.object({
       image: image(),
    }),
});

Удалено: названия тем Shiki до версии 0.14

В Astro v2.x некоторые названия тем Shiki были переименованы, но оригинальные названия были сохранены для обратной совместимости.

В Astro v3.0 оригинальные названия удалены в пользу переименованных.

Что делать?

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

material-darker -> material-theme-darker
material-default -> material-theme
material-lighter -> material-theme-lighter
material-ocean -> material-theme-ocean
material-palenight -> material-theme-palenight

Удалено: `class:list` функции

В Astro v2.x директива class:list (EN) использовала собственную реализацию, вдохновленную clsx с несколькими дополнительными функциями, такими как дедупликация и поддержка Set.

Astro v3.0 теперь использует clsx непосредственно для class:list, который не поддерживает дедупликацию или значения Set.

Что делать?

Замените все элементы Set, переданные в директиву class:list, на обычный Array.

<Component class:list={[
  'a',
  'b',
  new Set(['c', 'd'])
  ['c', 'd']
]} />

Устранено: передача `class:list` в качестве свойства

В Astro v2.x значения class:list (EN) передавались компонентам через Astro.props['class:list'].

Astro v3.0 нормализует значения class:list в строку перед отправкой в компоненты через Astro.props['class'].

Что делать?

Удалите весь код, который ожидает получить свойство class:list.

---
import { clsx } from 'clsx';
const { class: className, 'class:list': classList } = Astro.props;
const { class: className } = Astro.props;
---
<div
  class:list={[className, classList]}
  class:list={[className]}
/>

Убрано: преобразование kebab-case в camelCase для CSS переменных

В Astro v2.x camelCase CSS-переменные (EN), переданные в атрибут style, отображались как в camelCase (как написано), так и в kebab-case (сохранено для обратной совместимости).

Astro v3.0 удаляет преобразование kebab-case для этих имен CSS-переменных в camelCase, и теперь отображается только оригинальная CSS-переменная в camelCase.

---
const myValue = "red"
---
<!-- input -->
<div style={{ "--myValue": myValue }}></div>

<!-- output (Astro 2.x) -->
<div style="--my-value:var(--myValue);--myValue:red"></div>
<!-- output (Astro 3.0) -->
<div style="--myValue:red"></div>

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

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

<style>
  div {
   color: var(--my-value);
   color: var(--myValue);
  }
</style>

Устранено: автоматическое выравнивание возвращаемого значения функции `getStaticPaths()`.

В Astro v2.x возвращаемое значение функции getStaticPaths() (EN) автоматически выравнивалось, чтобы вы могли вернуть массив массивов без ошибок.

В Astro v3.0 автоматическое выравнивание результата getStaticPaths() удалено.

Что делать?

Если вы возвращаете массив массивов вместо массива объектов (как и ожидалось), то теперь следует использовать .flatMap и .flat, чтобы убедиться, что вы возвращаете плоский массив.

Если вам необходимо обновить код, будет выдано сообщение об ошибке, указывающее, что возвращаемое значение getStaticPath() должно быть массивом объектов.

Перемещено: `astro check` теперь требует внешнего пакета

В Astro v2.x пакет astro check был включен в Astro по умолчанию, а его зависимости были собраны в Astro. Это означало, что пакет был больше, независимо от того, использовали вы astro check или нет. Это также не позволяло вам контролировать версию TypeScript и языкового сервера Astro.

В Astro v3.0 команда astro check перенесена из ядра Astro и теперь требует внешнего пакета @astrojs/check. Кроме того, для использования команды astro check в проекте необходимо установить typescript.

Что делать?

Запустите команду astro check после обновления до Astro v3.0 и следуйте подсказкам для установки необходимых зависимостей, либо вручную установите @astrojs/check и typescript в ваш проект.

Утратило актуальность: `build.excludeMiddleware` и `build.split`.

В Astro v2.x, build.excludeMiddleware и build.split использовались для изменения того, как определенные файлы выдавались при использовании адаптера в режиме SSR.

В Astro v3.0 эти опции конфигурации сборки заменены на новые опции конфигурации адаптера SSR для выполнения тех же задач: edgeMiddleware и functionPerRoute.

Что делать?

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

import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel/serverless";

export default defineConfig({
    build: {
      excludeMiddleware: true
    },
    adapter: vercel({
      edgeMiddleware: true
    }),
});

import { defineConfig } from "astro/config";
import netlify from "@astrojs/netlify/functions";

export default defineConfig({
     build: {
        split: true
     },
     adapter: netlify({
        functionPerRoute: true
     }),
});

Утратило актуальность: `markdown.drafts`.

В Astro v2.x конфигурация markdown.drafts позволяла вам иметь черновики страниц, которые были доступны при запуске dev-сервера, но не создавались в продакшене.

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

Что делать?

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

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

В Astro v2.x конечные точки могли возвращать простой объект, который преобразовывался в ответ в формате JSON.

В Astro v3.0 это поведение упразднено в пользу прямого возврата объекта Response.

Что делать?

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

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

Если вам действительно необходимо сохранить прежний формат, вы можете использовать объект ResponseWithEncoding, но в будущем он будет устаревшим.

export async function GET() {
  return { body: { "title": "Bob's blog" } };
  return new ResponseWithEncoding({ body: { "title": "Bob's blog" }});
}

Изменено по умолчанию: `verbatimModuleSyntax` в предустановках tsconfig.json

В Astro v2.x настройка verbatimModuleSyntax была выключена по умолчанию, а ее эквивалент TypeScript 4.x importsNotUsedAsValues был включен в пресете strict.

В Astro v3.0 параметр verbatimModuleSyntax включен во всех пресетах.

Что делать?

Эта опция требует, чтобы типы импортировались с использованием синтаксиса import type.

---
import { type CollectionEntry, getEntry } from "astro:content";
---

Хотя мы рекомендуем оставить его включенным и правильно оформлять импорт типов с помощью type (как показано выше), вы можете отключить его, установив verbatimModuleSyntax: false в файле tsconfig.json, если он вызывает какие-либо проблемы.

{
  "compilerOptions": {
    "verbatimModuleSyntax": false
  }
}

Изменено по умолчанию: порт `3000`

В Astro v2.x по умолчанию Astro работал на порту 3000.

В Astro v3.0 порт по умолчанию изменен на 4321. 🚀

Что делать?

Обновите все существующие ссылки на localhost:3000, например, в тестах или в вашем README, чтобы они отражали новый порт localhost:4321.

Изменено по умолчанию: import.meta.env.BASE_URL `trailingSlash`

В Astro v2.x, import.meta.env.BASE_URL по умолчанию добавлял к настройкам base (EN) trailingSlash (EN). trailingSlash: "ignore" также добавлял слэш в конце строки.

Astro v3.0 больше не добавляет import.meta.env.BASE_URL с наклонной чертой по умолчанию, а также когда задано trailingSlash: "ignore". (Существующее поведение base в сочетании с trailingSlash: "always" или trailingSlash: "never" остается неизменным).

Что делать?

Если ваша base уже имеет примыкающую косую черту, то ничего менять не нужно.

Если в вашей base нет слэша, добавьте его, если хотите сохранить предыдущее поведение по умолчанию (или trailingSlash: "ignore"):

import { defineConfig } from "astro/config";

export default defineConfig({
  base: 'my-base',
  base: 'my-base/',
});

Изменено по умолчанию: `compressHTML`

В Astro v2.x Astro сжимал HTML только в том случае, если для параметра compressHTML (EN) было явно установлено значение true. По умолчанию было установлено значение false.

Теперь Astro v3.0 сжимает HTML по умолчанию.

Что делать?

Теперь вы можете удалить compressHTML: true из вашей конфигурации, так как это новое поведение по умолчанию.

import { defineConfig } from "astro/config";

export default defineConfig({
  compressHTML: true
})

Теперь вы должны установить compressHTML: false, чтобы отказаться от сжатия HTML.

Изменено по умолчанию: `scopedStyleStrategy`

В Astro v2.x значение по умолчанию для параметра scopedStyleStrategy (EN) было "where".

В Astro v3.0 появилось новое значение по умолчанию: "attribute". По умолчанию стили теперь применяются с использованием атрибутов data-*.

Что делать?

Чтобы сохранить текущее значение style scoping (EN) в вашем проекте, обновите конфигурационный файл до предыдущего значения по умолчанию:

import { defineConfig } from "astro/config";

export default defineConfig({
  scopedStyleStrategy: "where"
})

Изменено по умолчанию: `inlineStyleSheets`

В Astro v2.x все таблицы стилей проекта по умолчанию отправлялись в виде тегов ссылок. Вы могли выбрать вставку их в теги <style> каждый раз с помощью "always", или вставку только таблиц стилей меньше определенного размера с помощью "auto", установив конфигурацию build.inlineStylesheets (EN). По умолчанию было установлено значение never.

В Astro v3.0 значение по умолчанию для inlineStylesheets изменено на "auto". Стили, размер которых меньше, чем ViteConfig.build.assetsInlineLimit (по умолчанию: 4kb), вставляются по умолчанию. В противном случае стили проекта передаются во внешних таблицах стилей.

Что делать?

Если вы хотите сохранить текущее поведение проекта, установите build.inlineStylesheets на предыдущее значение по умолчанию, "never":

import { defineConfig } from "astro/config";

export default defineConfig({
   build: {
    inlineStylesheets: "never"
  }
})

Изменено по умолчанию: служба обработки изображений

В Astro v2.x в качестве [службы обработки изображений по умолчанию] использовался Squoosh (/ru/guides/images/#default-image-service).

В Astro v3.0 в качестве службы обработки изображений по умолчанию теперь используется Sharp, а вместо него в настройках предлагается использовать Squoosh.

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

При использовании строгого менеджера пакетов, например pnpm, вам может потребоваться вручную установить Sharp в ваш проект, даже если он является зависимостью Astro:

pnpm add sharp

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

import { defineConfig, squooshImageService } from "astro/config";

export default defineConfig({
  image: {
    service: squooshImageService(),
  }
})

Изменено: Регистр методов HTTP запросов

В Astro v2.x, Методы HTTP-запросов (EN) были написаны с использованием строчных имен функций: get, post, put, all, и del.

В Astro v3.0 используются имена функций в верхнем регистре, включая DELETE вместо del.

Что делать?

Переименуйте все функции в их эквиваленты в верхнем регистре:

get в GET
post в POST
put в PUT
all в ALL
del к DELETE

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

Изменено: Множественная настройка JSX-фреймворка

В Astro v2.x вы могли использовать несколько интеграций JSX-фреймворков (React, Solid, Preact) в одном проекте без необходимости определять, какие файлы принадлежат какому фреймворку.

Astro v3.0 теперь требует указать, какой фреймворк использовать для ваших файлов, с помощью новых опций include и exclude в конфигурации интеграции, если у вас установлено несколько фреймворков JSX. Это позволяет Astro лучше поддерживать использование одного фреймворка, а также такие продвинутые функции, как React Fast Refresh.

Что делать?

Если вы используете несколько JSX-фреймворков в одном проекте, задайте include (и опционально exclude) для массива файлов и/или папок. Для включения нескольких путей к файлам можно использовать подстановочные знаки.

Мы рекомендуем размещать общие компоненты фреймворка в одной папке (например, /components/react/ и /components/solid/), чтобы упростить указание включаемых компонентов, но это не обязательно:

import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';

export default defineConfig({
  // Позволяет многим фреймворкам поддерживать всевозможные типы компонентов.
  // Если вы используете только один фреймворк, то `include` не нужен!
  integrations: [
    preact({
      include: ['**/preact/*']
    }),
    react({
      include: ['**/react/*']
    }),
    solid({
      include: ['**/solid/*'],
    }),
  ]
});

Изменено: `Astro.cookies.get(key)` может возвращать `undefined`

В Astro v2.x функция Astro.cookies.get(key) всегда возвращала объект AstroCookie, даже если куки-файл не существовал. Чтобы проверить его существование, нужно было использовать Astro.cookies.has(key).

Astro v3.0 возвращает значение undefined для Astro.cookies.get(key), если куки не существует.

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

Это изменение не нарушит работу кода, который проверяет существование объекта Astro.cookie перед использованием Astro.cookies.get(key), но теперь оно больше не требуется.

Вы можете смело удалить любой код, использующий has() для проверки того, что значение Astro.cookies является undefined:

if (Astro.cookies.has(id)) {
  const id = Astro.cookies.get(id)!;
}

const id = Astro.cookies.get(id);
if (id) {
}

Изменено: запуск Astro CLI программно

В Astro v2.x точка входа пакета "astro" экспортировала и запускала Astro CLI напрямую. На практике запускать Astro таким образом не рекомендуется.

В Astro v3.0 CLI удален из точки входа, и экспортируется новый набор экспериментальных API JavaScript, включая dev(), build(), preview() и ync().

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

Чтобы запустить Astro CLI программно, используйте новые экспериментальные API JavaScript:

import { dev, build } from "astro";

// Запустите сервер разработки Astro
const devServer = await dev();
await devServer.stop();

// Сборка проекта Astro
await build();

Изменено: пути экспорта внутренних точек входа Astro API

В Astro v2.x вы могли импортировать внутренние API Astro из astro/internal/* и astro/runtime/server/*.

В Astro v3.0 эти две точки входа удалены в пользу существующей точки входа astro/runtime/*. Кроме того, был добавлен новый экспорт astro/compiler-runtime для специфичного для компилятора кода времени выполнения.

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

Это точки входа для внутреннего API Astro, и они не должны повлиять на ваш проект. Но если вы используете эти точки входа, обновите их, как показано ниже:

import 'astro/internal/index.js';
import 'astro/runtime/server/index.js';

import 'astro/server/index.js';
import 'astro/runtime/server/index.js';

import { transform } from '@astrojs/compiler';

const result = await transform(source, {
  internalURL: 'astro/runtime/server/index.js',
  internalURL: 'astro/compiler-runtime',
  // ...
});

Обновления функций

Обновление изображений до v3

astro:assets больше не находится за экспериментальным флагом в Astro v3.0.

<Image /> теперь является встроенным компонентом, а предыдущая интеграция @astrojs/image была удалена.

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

Пожалуйста, следуйте приведённым ниже инструкциям, чтобы обновить проект Astro с версии 2.x до v3.0.

Обновление с `experimental.assets`

Если вы ранее включили экспериментальный флаг для astro:assets, вам нужно будет обновить ваш проект для Astro v3.0, который теперь включает функции работы с активами по умолчанию.

Удаление флага `experimental.assets`

Удалите экспериментальный флаг:

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    assets: true
  }
});

При необходимости также обновите файл src/env.d.ts, заменив ссылку на astro/client-image на astro/client:

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

Удалите псевдоним импорта `~/assets`

Этот псевдоним импорта больше не включён по умолчанию в astro:assets. Если вы использовали этот псевдоним с экспериментальными активами, вам нужно заменить их на относительные пути к файлам или создать собственные псевдонимы импорта (EN).

---
import rocket from '~/assets/rocket.png';
import rocket from '../../assets/rocket.png';
---

Добавлена поддержка простых активов для Cloudflare, Deno, Vercel Edge и Netlify Edge

Astro v3.0 позволяет astro:assets работать без ошибок в Cloudflare, Deno, Vercel Edge и Netlify Edge, которые не поддерживают встроенную оптимизацию изображений Squoosh и Sharp в Astro. Обратите внимание, что Astro не выполняет никаких преобразований и обработки изображений в этих средах. Однако вы всё ещё можете пользоваться другими преимуществами astro:assets, такими как отсутствие Cumulative Layout Shift (CLS), обязательный атрибут alt и единообразный опыт разработки.

Если вы ранее избегали использования astro:assets из-за этих ограничений, теперь вы можете использовать их без проблем. Вы можете настроить сервис изображений без операций, чтобы явно включить это поведение:

import { defineConfig } from 'astro/config';

export default defineConfig({
  image: {
    service: {
      entrypoint: 'astro/assets/services/noop'
    }
  }
});

Решите, где хранить ваши изображения

Ознакомьтесь с руководством по изображениям, чтобы помочь вам решить, где хранить ваши изображения (EN). Возможно, вы захотите воспользоваться новыми возможностями для хранения изображений с дополнительной гибкостью, которую предоставляет astro:assets. Например, относительные изображения из вашего проекта src/ теперь можно ссылаться в Markdown, MDX и Markdoc с использованием стандартного синтаксиса Markdown ![alt](src).

Обновите существующие теги `<img>`

Раньше импорт изображения возвращал простую строку (string) с путём к изображению. Теперь импортированные изображения соответствуют следующей сигнатуре:

interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}

Вам необходимо обновить атрибут src для всех существующих тегов <img> (включая изображения в компонентах UI-фреймворков (EN)), а также вы можете обновить другие атрибуты, которые теперь доступны из импортированного изображения.

---
import rocket from '../images/rocket.svg';
---
<img src={rocket} width="250" height="250" alt="A rocketship in space." />

<img src={rocket.src} width={rocket.width} height={rocket.height} alt="A rocketship in space." />

Обновите ваши файлы Markdown, MDX и Markdoc

Относительные изображения из вашего проекта src/ теперь можно ссылаться в Markdown, MDX и Markdoc с использованием стандартного синтаксиса Markdown ![alt](src).

Это позволяет вам переместить ваши изображения из директории public/ в проект src/, где они теперь будут обрабатываться и оптимизироваться. Ваши существующие изображения в public/ и удалённые изображения по-прежнему действительны, но не оптимизируются в процессе сборки Astro.

# Моя страница Markdown

<!-- Локальные изображения теперь возможны! -->
![A starry night sky.](../../images/stars.png)

<!-- Храните свои изображения рядом с контентом! -->
![A starry night sky.](./stars.png)

Если вам требуется больше контроля над атрибутами изображений, мы рекомендуем использовать формат файла .mdx, который позволяет включать компонент <Image /> от Astro или тег JSX <img /> в дополнение к синтаксису Markdown. Используйте интеграцию MDX (EN), чтобы добавить поддержку MDX в Astro.

Удалите `@astrojs/image`

Если вы использовали интеграцию изображений в Astro v2.x, выполните следующие шаги:

Удалите интеграцию @astrojs/image.

Вам необходимо удалить интеграцию, удалив её и затем убрав из файла astro.config.mjs.
astro.config.mjs
```
import { defineConfig } from 'astro/config';
import image from '@astrojs/image';

export default defineConfig({
  integrations: [
    image(),
  ]
})
```
Обновите типы (если требуется).

Если у вас были настроены специальные типы для @astrojs/image в файле src/env.d.ts, вам может потребоваться вернуть их к стандартным типам Astro, если ваше обновление до v3 не выполнило этот шаг автоматически.
src/env.d.ts
```
 /// <reference types="@astrojs/image/client" />
 /// <reference types="astro/client" />
```
Аналогично обновите tsconfig.json, если это необходимо:
tsconfig.json
```
{
  "compilerOptions": {
    "types": ["@astrojs/image/client"]
    "types": ["astro/client"]
  }
}
```
Перенесите существующие компоненты <Image />.

Измените все import-операторы с @astrojs/image/components на astro:assets, чтобы использовать новый встроенный компонент <Image />.

Удалите все атрибуты компонента, которые не являются поддерживаемыми свойствами изображений (EN).

Например, aspectRatio больше не поддерживается, так как теперь он автоматически вычисляется на основе атрибутов width и height.
src/components/MyComponent.astro
```
---
import { Image } from '@astrojs/image/components';
import { Image } from 'astro:assets';
import localImage from '../assets/logo.png';
const localAlt = 'The Astro Logo';
---

<Image
  src={localImage}
  width={300}
  aspectRatio="16:9"
  alt={localAlt}
/>
```
Выберите сервис изображений по умолчанию.

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

Если вы предпочитаете использовать Squoosh для преобразования изображений, обновите конфигурацию, добавив опцию image.service:
astro.config.mjs
```
import { defineConfig, squooshImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: squooshImageService(),
  },
});
```

Обновите схемы для коллекций контента

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

Новый хелпер image для коллекций контента позволяет вам проверять метаданные изображения с помощью Zod. Узнайте больше о том, как использовать изображения в коллекциях контента (EN).

Навигация по импорту изображений в Astro v3.0

В Astro v3.0, если вам нужно сохранить старое поведение импорта изображений и требуется строковое представление URL изображения, добавьте ?url в конец пути изображения при его импорте. Например:

---
import Sprite from '../assets/logo.svg?url';
---

<svg>
  <use xlink:href={Sprite + '#cart'} />
</svg>

Этот подход гарантирует, что вы получите строку URL. Имейте в виду, что во время разработки Astro использует путь src/, но при сборке он генерирует хэшированные пути, такие как /_astro/cat.a6737dd3.png.

Если вы предпочитаете работать напрямую с объектом изображения, вы можете получить доступ к свойству .src. Этот подход лучше всего подходит для задач, таких как управление размерами изображений для метрик Core Web Vitals и предотвращение CLS.

Если вы переходите на новое поведение импорта, комбинация методов ?url и .src может быть правильным способом для бесперебойной работы с изображениями.

Обновление View Transitions до v3

View Transitions больше не находятся за экспериментальным флагом в Astro v3.0.

Если вы не включали этот экспериментальный флаг в Astro 2.x, это не вызовет критических изменений в вашем проекте. Новый API View Transitions не влияет на ваш существующий код.

Если вы ранее использовали экспериментальные View Transitions, могут возникнуть некоторые критические изменения при обновлении вашего проекта Astro с более ранней версии.

Пожалуйста, следуйте приведённым ниже инструкциям, чтобы обновить проект Astro v2.x, настроенный с experimental.viewTransitions: true, до v3.0.

Обновление с `experimental.viewTransitions`

Если вы ранее включили экспериментальный флаг для View Transitions, вам нужно будет обновить ваш проект для Astro v3.0, который теперь поддерживает View Transitions по умолчанию.

Удалите флаг `experimental.viewTransitions`

Удалите экспериментальный флаг:

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
   viewTransitions: true
  }
});

Обновите источник импорта

Компонент <ViewTransitions /> был перемещён из astro:components в astro:transitions. Обновите источник импорта во всех местах вашего проекта.

---
import { ViewTransitions } from "astro:components astro:transitions"
---
<html lang="ru">
  <head>
    <title>Моя страничка</title>
    <ViewTransitions />
  </head>
  <body>
    <h1>Добро пожаловать на мой сайт!</h1>
  </body>
</html>

Обновите директивы `transition:animate`

Изменено: Значение transition:animate morph было переименовано в initial. Кроме того, это больше не анимация по умолчанию. Если директива transition:animate не указана, ваши анимации теперь будут по умолчанию использовать fade.

Переименуйте все анимации morph в initial.
src/components/MyComponent.astro
```
<div transition:name="name" transition:animate="morph initial" />
```
Чтобы сохранить анимации, которые ранее использовали morph по умолчанию, явно добавьте transition:animate="initial".
src/components/MyComponent.astro
```
<div transition:name="name" transition:animate="initial" />
```
Вы можете безопасно удалить анимации, явно установленные на fade. Это теперь поведение по умолчанию:
src/components/MyComponent.astro
```
<div transition:name="name" transition:animate="fade" />
```

Добавлено: Astro также поддерживает новое значение transition:animate — none. Это значение можно использовать на элементе <html> страницы, чтобы отключить анимированные переходы на всей странице. Это переопределит поведение анимации по умолчанию только для элементов страницы без директивы анимации. Вы всё ещё можете устанавливать анимации на отдельных элементах, и эти конкретные анимации будут выполняться.

Теперь вы можете отключить все переходы по умолчанию на отдельной странице, анимируя только элементы, которые явно используют директиву transition:animate:
```
<html transition:animate="none">
  <head></head>
  <body>
    <h1>Привет, мир!</h1>
  </body>
</html>
```

Обновите имена событий

Событие astro:load было переименовано в astro:page-load. Переименуйте все его упоминания в вашем проекте.

<script>
document.addEventListener('astro:load astro:page-load', runSetupLogic);
</script>

Событие astro:beforeload было переименовано в astro:after-swap. Переименуйте все его упоминания в вашем проекте.

<script>
document.addEventListener('astro:beforeload astro:after-swap', setDarkMode);
</script>

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

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

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

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

Внести свой вклад Сообщество Sponsor

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

Обновление Astro

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

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

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

Что делать?

Удалено: Поддержка TypeScript 4

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

Удалено: @astrojs/image

Что делать?

Удалено: компонент <Markdown />

Что делать?

Удалено: устаревшие API версии 1.x

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

Удалено: Частичные шиммы для веб-интерфейсов в коде сервера

Что делать?

Удалено: image из astro:content в схеме коллекций контента

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

Удалено: названия тем Shiki до версии 0.14

Что делать?

Удалено: class:list функции

Что делать?

Устранено: передача class:list в качестве свойства

Что делать?

Убрано: преобразование kebab-case в camelCase для CSS переменных

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

Устранено: автоматическое выравнивание возвращаемого значения функции getStaticPaths().

Что делать?

Перемещено: astro check теперь требует внешнего пакета

Что делать?

Утратило актуальность: build.excludeMiddleware и build.split.

Что делать?

Утратило актуальность: markdown.drafts.

Что делать?

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

Что делать?

Изменено по умолчанию: verbatimModuleSyntax в предустановках tsconfig.json

Что делать?

Изменено по умолчанию: порт 3000

Что делать?

Изменено по умолчанию: import.meta.env.BASE_URL trailingSlash

Что делать?

Изменено по умолчанию: compressHTML

Что делать?

Изменено по умолчанию: scopedStyleStrategy

Что делать?

Изменено по умолчанию: inlineStyleSheets

Что делать?

Изменено по умолчанию: служба обработки изображений

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

Изменено: Регистр методов HTTP запросов

Что делать?

Изменено: Множественная настройка JSX-фреймворка

Что делать?

Изменено: Astro.cookies.get(key) может возвращать undefined

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

Изменено: запуск Astro CLI программно

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

Изменено: пути экспорта внутренних точек входа Astro API

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

Обновления функций

Обновление изображений до v3

Обновление с experimental.assets

Удаление флага experimental.assets

Удалите псевдоним импорта ~/assets

Добавлена поддержка простых активов для Cloudflare, Deno, Vercel Edge и Netlify Edge

Решите, где хранить ваши изображения

Обновите существующие теги <img>

Обновите ваши файлы Markdown, MDX и Markdoc

Удалите @astrojs/image

Обновите схемы для коллекций контента

Навигация по импорту изображений в Astro v3.0

Обновление View Transitions до v3

Обновление с experimental.viewTransitions

Удалите флаг experimental.viewTransitions

Обновите источник импорта

Обновите директивы transition:animate

Обновите имена событий

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

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

Удалено: `@astrojs/image`

Удалено: компонент `<Markdown />`

Удалено: `image` из `astro:content` в схеме коллекций контента

Удалено: `class:list` функции

Устранено: передача `class:list` в качестве свойства

Устранено: автоматическое выравнивание возвращаемого значения функции `getStaticPaths()`.

Перемещено: `astro check` теперь требует внешнего пакета

Утратило актуальность: `build.excludeMiddleware` и `build.split`.

Утратило актуальность: `markdown.drafts`.

Изменено по умолчанию: `verbatimModuleSyntax` в предустановках tsconfig.json

Изменено по умолчанию: порт `3000`

Изменено по умолчанию: import.meta.env.BASE_URL `trailingSlash`

Изменено по умолчанию: `compressHTML`

Изменено по умолчанию: `scopedStyleStrategy`

Изменено по умолчанию: `inlineStyleSheets`

Изменено: `Astro.cookies.get(key)` может возвращать `undefined`

Обновление с `experimental.assets`

Удаление флага `experimental.assets`

Удалите псевдоним импорта `~/assets`

Обновите существующие теги `<img>`

Удалите `@astrojs/image`

Обновление с `experimental.viewTransitions`

Удалите флаг `experimental.viewTransitions`

Обновите директивы `transition:animate`