TypeScript

Astro по умолчанию поддерживает TypeScript. Вы можете импортировать .ts и .tsx файлы в свой проект, писать Typescript код прямо внутри своих Astro компонентов, и даже использовать astro.config.ts файл, если это необходимо.

Используя Typescript, вы можете предотвратить ошибки во время выполнения, описывая типы объектов и компонентов в коде. К примеру, если вы используете Typescript для типизации параметров(пропсов) компонента, то редактор выведет ошибку, если вы попытаетесь передать параметр, который компонент не принимает.

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

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

Настройка

Стартовые проекты Astro добавляют tsconfig.json файл в ваш проект по умолчанию. Даже если вы не планируете использовать Typescript, не удаляйте его, потому что такие инструменты как Astro и VS Code с помощью него получают информацию о проекте. Некоторые функции (например импорт npm пакетов) поддерживаются не полностью без tsconfig.json файла. Если вы устанавливаете Astro вручную, не забудьте создать этот файл самостоятельно.

Astro поддерживает три расширяемых tsconfig.json шаблона: base, strict и strictest. Шаблон base обеспечивает поддержку современных возможностей JavaScript, а также используется в качестве основы для других шаблонов. Мы рекомендуем использовать strict или strictest шаблоны, если вы планируете писать Typescript код в своем проекте. Вы можете посмотреть и сравнить эти шаблоны на гитхабе в директории astro/tsconfigs/.

Для наследования от одного из шаблонов используйте синтаксис extends:

{
  "extends": "astro/tsconfigs/base"
}

Кроме того, наши шаблоны включают в себя файл env.d.ts внутри src директории для обеспечения клиентских типов Vite в вашем проекте:

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

Если вы не используете VS Code, вы можете установить Astro TypeScript плагин для поддержки импортов .astro файлов из .ts файлов (что может быть полезно при переиспользовании).

npm install @astrojs/ts-plugin

pnpm add @astrojs/ts-plugin

yarn add @astrojs/ts-plugin

Затем, добавьте код ниже в tsconfig.json:

  "compilerOptions": {
    "plugins": [
      {
        "name": "@astrojs/ts-plugin"
      },
    ],
  }

Чтобы проверить, что плагин работает, создайте .ts файл и импортируйте Astro компонент в него. Если вы не увидите ошибок, то плагин работает корректно.

UI-фреймворки

Если ваш проект использует UI-фреймворк, то вам может потребоваться дополнительная настройка в зависимости от фреймворка. Пожалуйста, проверьте документацию о работе Typescript вместе с вашим фреймворком для дополнительной информации. (Vue, React, Preact, Solid)

Импорт типов

По возможности используйте явный импорт и экспорт типов.

import { SomeType } from './script';
import type { SomeType } from './script';

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

Вы можете настроить TypeScript на принудительный импорт типов в файле .tsconfig. Установите параметр verbatimModuleSyntax в значение true. TypeScript проверит ваши импорты и сообщит вам, когда следует использовать import type. Эта настройка включена по умолчанию во всех наших пресетах.

  {
    "compilerOptions": {
      "verbatimModuleSyntax": true
    }
  }

Импорт алиасов

Astro поддерживает импорт алиасов, которые вы определили в секции paths в файлах tsconfig.json и jsconfig.json. Прочитайте наш гайд, чтобы узнать больше.

---
import HelloWorld from '@components/HelloWorld.astro';
import Layout from '@layouts/Layout.astro';
---

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@layouts/*": ["src/layouts/*"]
    }
  }
}

Расширение `window` и `globalThis`

Если вы захотите добавить свойство к глобальному объекту, то это можно сделать, добавив ключевое слово declare в файл env.d.ts:

declare const myString: string;
declare function myFunction(): boolean;

Это обеспечит типизацию globalThis.myString и globalThis.myFunction, а также window.myString и window.myFunction.

Обратите внимание, что window доступно только в коде на стороне клиента. Функция globalThis доступна как на стороне сервера, так и на стороне клиента, но ее значение на стороне сервера не будет передано клиенту.

Если вы хотите добавить свойство только для объекта window, создайте вместо global интерфейс Window:

interface Window {
  myFunction(): boolean;
}

Параметры компонентов

Astro поддерживает типизацию параметров (пропсов) компонентов с помощью TypeScript. Для типизации добавьте TypeScript интерфейс Props в метаданных вашего компонента. Вы можете использовать выражение export, но это не обязательно. Расширение Astro для VSCode будет автоматически искать интерфейс Props и обеспечивать соответствующую поддержку TS при использовании этого компонента внутри другого шаблона.

---
interface Props {
  name: string;
  greeting?: string;
}
const { greeting = 'Hello', name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>

Распространённые паттерны типизации пропсов

Если ваш компонент не принимает пропсов или слотов, вы можете использовать type Props = Record<string, never>.
Если ваш компонент должен передавать дочерние элементы в свой слот, вы можете явно указать это через type Props = { children: any; };.

Утилиты типизации

Добавлено в: astro@1.6.0

Astro предоставляет встроенные типы для распространённых паттернов типизации пропсов. Они доступны в astro/types.

Встроенные HTML атрибуты

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

К примеру, если вы создаете компонент <Link>, вы можете добавить стандартные HTML атрибуты для тега <a> в тип пропсов вашего компонента.

---
import type { HTMLAttributes } from 'astro/types'
// используйте `type`
type Props = HTMLAttributes<'a'>;
// или extends с `interface`
interface Props extends HTMLAttributes<'a'> {
  myProp?: boolean;
}
const { href, ...attrs } = Astro.props;
---
<a href={href} {...attrs}>
  <slot />
</a>

Также можно расширить стандартные JSX выражения для того, чтобы добавить нестандартные атрибуты с помощью переопределения пространства имен astroHTML.JSX в файле .d.ts.

declare namespace astroHTML.JSX {
  interface HTMLAttributes {
    'data-count'?: number;
    'data-label'?: string;
  }

  // Add a CSS custom property to the style object
  interface CSSProperties {
    '--theme-color'?: 'black' | 'white';
  }
}

astroHTML глобально инжектирован в .astro компоненты. Чтобы использовать их в TypeScript файлах, используйте директиву triple-slash:

/// <reference types="astro/astro-jsx" />

type MyAttributes = astroHTML.JSX.ImgHTMLAttributes;

Тип `ComponentProps`

Добавлено в: astro@4.3.0

Этот тип экспорта позволяет вам ссылаться на Props, принятый другим компонентом, даже если этот компонент не экспортирует этот тип Props напрямую.

В следующем примере показано использование утилиты ComponentProps из astro/types для ссылки на типы Props компонента <Button />:

---
import type { ComponentProps } from 'astro/types';

import Button from "./Button.astro";

type ButtonProps = ComponentProps<typeof Button>;
---

Полиморфный тип

Добавлено в: astro@2.5.0

Astro имеет хелпер, чтобы сделать проще создание компонентов, которые могут быть различными HTML элементами с полной безопасностью типов. Это может быть полезно для компонентов как <Link>, которые могут быть элементами <a> или <button> в зависимости от пропсов, переданных в него.

Пример ниже использует полностью типизированный полиморфный компонент, который может быть любым HTML элементом. HTMLTag тип используется для того, чтобы быть уверенным, что параметр as — это валидный HTML элемент.

---
import { HTMLTag, Polymorphic } from 'astro/types';

type Props<Tag extends HTMLTag> = Polymorphic<{ as: Tag }>;

const { as: Tag, ...props } = Astro.props;
---

<Tag {...props} />

Определение типов `getStaticPaths()`

Добавлено в: astro@2.1.0

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

Вы можете получить тип Astro.params с помощью InferGetStaticParamsType и тип Astro.props с помощью InferGetStaticPropsType:

---
import type { InferGetStaticParamsType, InferGetStaticPropsType, GetStaticPaths } from 'astro';

export const getStaticPaths = (async () => {
  const posts = await getCollection('blog');
  return posts.map((post) => {
    return {
      params: { slug: post.slug },
      props: { draft: post.data.draft, title: post.data.title },
    };
  });
}) satisfies GetStaticPaths;

type Params = InferGetStaticParamsType<typeof getStaticPaths>;
type Props = InferGetStaticPropsType<typeof getStaticPaths>;

const { slug } = Astro.params as Params;
//                     ^? { slug: string; }
const { title } = Astro.props;
//                      ^? { draft: boolean; title: string; }
---

Проверка типов

Чтобы проверить ошибки в вашем проекте, пожалуйста убедитесь, что вы установили расширение Astro VSCode. Обратите внимание, что команды astro start и astro build соберут код с помощью esbuild, но не запустят проверку типов. Чтобы избежать сборки кода, содержащего ошибки TypeScript, измените команду «build» в package.json файле на следующую:

  "scripts": {
    "build": "astro build",
    "build": "astro check && astro build",
  },

Подробнее о импортах .ts файлов в Astro.

Подробнее о конфигурации TypeScript.

Решение проблем

Ошибки типизации при использовании нескольких JSX фреймворков

Проблема может возникнуть при использовании нескольких JSX фреймворков в одном проекте, так как каждый фреймворк требует различных, иногда конфликтующих настроек в tsconfig.json.

Решение: Установите ключу jsxImportSource значение react (стандартное), preact или solid-js в зависимости от самого используемого фреймворка в проекте. Затем, используйте pragma comment внутри всех конфликтующих файлов других фреймворков.

Для стандартного значения jsxImportSource: react следует использовать:

// Для Preact
/** @jsxImportSource preact */

// Для Solid
/** @jsxImportSource solid-js */

Создать проблему в GitHub

Отправить нам отзыв

TypeScript

Настройка

UI-фреймворки

Импорт типов

Импорт алиасов

Расширение `window` и `globalThis`

Параметры компонентов

Распространённые паттерны типизации пропсов

Утилиты типизации

Встроенные HTML атрибуты

Тип `ComponentProps`

Полиморфный тип

Определение типов `getStaticPaths()`

Проверка типов

Решение проблем

Ошибки типизации при использовании нескольких JSX фреймворков

TypeScript

Настройка

UI-фреймворки

Импорт типов

Импорт алиасов

Расширение window и globalThis

Параметры компонентов

Распространённые паттерны типизации пропсов

Утилиты типизации

Встроенные HTML атрибуты

Тип ComponentProps

Полиморфный тип

Определение типов getStaticPaths()

Проверка типов

Решение проблем

Ошибки типизации при использовании нескольких JSX фреймворков

Расширение `window` и `globalThis`

Тип `ComponentProps`

Определение типов `getStaticPaths()`