TypeScript

Astro 内置了对 TypeScript 的支持。你可以在 Astro 项目中导入 .ts 和 .tsx 文件，甚至可以直接在 Astro 组件 中编写 TypeScript 代码。如果你愿意，你甚至可以使用 astro.config.ts。

使用 TypeScript，你可以通过约束代码中对象和组件的类型来防止运行时的错误。例如，如果你使用了 TypeScript 来定义组件参数；而如果你在使用时不小心传入了一个与之不匹配的参数，编辑器将会报错。

你无需在 Astro 项目中编写 TypeScript 代码也可从中受益。Astro 始终将你的组件代码视为 TypeScript，并且 Astro 的 VSCode 扩展 将尝试尽可能多地推断，以便在编辑器中提供自动完成、提示和错误。

Astro 的开发服务器不会进行任何类型检查，但你可以编辑 package.json 中的 scripts 属性来通过命令行工具检查代码中的类型错误。

Astro 入门项目在你的项目中包含一个名为 tsconfig.json 的文件。即使你不编写 TypeScript 代码，这个文件也很重要；通过这个文件，可以让 Astro 和 VSCode 等工具知道应当如何理解你的项目。如果没有 tsconfig.json 文件，编辑器将不能对某些功能提供完整支持（比如 npm 包导入）。如果你手动安装的 Astro，请务必自己创建此文件。

Astro 中包含三个可扩展的 tsconfig.json 模板：base、strict 和 strictest。base 模板开启了对现代 JavaScript 的相关特性的支持，也可用作其他模板的基础。但如果你打算在项目中编写 TypeScript，我们建议使用 strict 或 strictest。你可以在 astro/tsconfigs/ 中查看和比较这三个配置模板。

要继承其中某个模板，请使用 设置项 extends：

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

此外，我们的模板在 src 文件夹中包含一个名为 env.d.ts 的文件，它为你的项目提供 Vite 的客户端类型：

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

如果你的项目使用了 UI 框架，则可能需要根据框架的不同进行额外的设置。请参阅你使用的框架的文档中关于 TypeScript 的相关文档以获取更多信息。（Vue、React、Preact、Solid）

尽可能显式的导入和导出类型。

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

通过这种方式，你可以避免让 Astro 的打包程序将导入的类型误以为是 JavaScript，从而错误地被打包。

在你的 .tsconfig 文件中，你可以指示 TypeScript 来帮助解决这个问题。通过将设置项 importsNotUsedAsValues 设置为 error。然后，TypeScript 会检查你的导入并告诉你什么时候应该使用 import type。此设置默认包含在我们的 strict 和 strictest 模板中。

{
  "compilerOptions": {
    "importsNotUsedAsValues": "error",
  }
}

Astro 支持你在 tsconfig.json 和 jsconfig.json 文件里的 paths 配置所定义的 导入别名。阅读我们的指南以了解更多。

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

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

Astro 支持通过 TypeScript 来定义你的组件参数。为了启动它，你需要将一个名为 Props 的 TypeScript 接口添加到你的的组件。你可以（可选的）使用 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 为常见的组件参数的类型模式准备了一些实用的类型工具集。这些可以通过在代码中引入 astro/types 来使用。

Astro 提供 HTMLAttributes 类型，以检查你的类型是否使用有效的 HTML 属性。你可以使用这些类型来帮助构建组件参数。

例如，如果你正在构建一个 <Link> 组件，你可以通过以下语法来为组件的 Props 类型镜像 <a> 的默认的 HTML 属性。

---
import { HTMLAttributes } from 'astro/types'
// 使用 `type`
type Props = HTMLAttributes<'a'>;
// 或者通过 `interface` 继承
interface Props extends HTMLAttributes<'a'> {
  myProp?: boolean;
}
const { href, ...attrs } = Astro.props;
---
<a {href} {...attrs}>
  <slot />
</a>

也可以通过在 .d.ts 文件中重新声明命名空间 astroHTML.JSX，来为默认的 JSX 定义扩展非标准属性。

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

要在编辑器中查看类型错误，请确保已安装 Astro VSCode 扩展。请注意，astro start 和 astro build 命令将使用 esbuild 转译代码，但不会运行任何类型检查。为了防止你的代码在包含 TypeScript 错误的情况下被构建，请将你 package.json 中的 build 脚本更改为以下内容：

  "scripts": {
    "build": "astro build",
    "build": "astro check && tsc --noEmit && astro build",
  },

📚 阅读更多关于 Astro 中的 .ts 文件导入。 📚 阅读更多关于 TypeScript 配置。

在同一个项目中使用多个 JSX 框架时可能会出现问题，因为每个框架在 tsconfig.json 中的不同需求有时会相互冲突。

解决方案：根据你最常用的框架，将 jsxImportSource 这一设置项设置为 react（默认）、preact 或 solid-js。然后，在来自不同框架的任何冲突文件中使用编译指示（pragma comment）进行注释。

对于默认设置 jsxImportSource: react，你可以使用：

// For Preact
/** @jsxImportSource preact */

// For Solid
/** @jsxImportSource solid-js */

@types/react 包中的类型定义是全局声明的，因此在使用 Volar 时会被错误地用于对 .vue 文件进行的类型检查。

状态：预期行为。

解决方案：目前没有可靠的方法来解决此问题，但是可以在此 GitHub discussion 中找到一些解决方案和更多的讨论。