TypeScript

Astro vem com suporte integrado para TypeScript. Você pode importar arquivos .ts e .tsx em seu projeto Astro, escrever código TypeScript dentro de seu componente Astro, e até mesmo utilizar um arquivo astro.config.ts se você quiser.

Usando TypeScript, você pode evitar erros em tempo de execução ao definir os formatos dos objetos e componentes no seu código. Por exemplo, se você usa TypeScript para definir o tipo das props do seu componente, você vai receber um erro no seu editor se você definir uma prop que seu componente não aceita.

Você não precisa escrever código TypeScript nos seus projetos com Astro para se beneficiar dele. O Astro sempre trata seu código do componente como TypeScript, e a extensão para VSCode do Astro vai inferir o tanto quanto pode para fornecer preenchimento automático, dicas e erros no seu editor.

O servidor de desenvolvimento do Astro não executará nenhuma checagem de tipos, mas você pode usar um script separado para checar erros de tipo pela linha de comando.

Configuração

Seção intitulada Configuração

Projetos iniciais do Astro incluem um arquivo tsconfig.json no seu projeto. Mesmo que você não escreva código TypeScript, esse arquivo é importante para que ferramentas como o Astro e o VS Code saibam como entender o seu projeto. Algumas funcionalidades (como importação de pacotes do npm) não são completamente suportadas em nosso editor sem um arquivo tsconfig.json. Se você instalar Astro manualmente, certifique-se de criar esse arquivo.

Templates TypeScript

Seção intitulada Templates TypeScript

Três templates extensíveis de tsconfig.json são inclusos no Astro: base, strict e strictest. O template base habilita suporte para funcionalidades modernas do JavaScript e também é usado como uma base para os outros templates. Nós recomendamos usar strict (estrito) ou strictest (mais estrito) se você planeja escrever TypeScript em seu projeto. Você pode ver e comparar a configuração dos três templates em astro/tsconfigs/.

Para herdar de um dos templates, utilize a opção extends:

tsconfig.json

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

Adicionalmente, nossos templates incluem um arquivo env.d.ts dentro do diretório src para providenciar tipos de cliente do Vite para seu projeto:

env.d.ts

/// <reference path="../.astro/types.d.ts" />

Plugin TypeScript para editores

Seção intitulada Plugin TypeScript para editores

O plugin Astro TypeScript pode ser instalado separadamente quando você não estiver utilizando a extensão oficial Astro VS Code. Esse plugin é instalado automaticamente e configurado pela extensão VSCode, e você não precisa instalar os dois.

Esse plugin executa apenas no editor. Ao executar tsc no terminal, arquivos .astro são completamente ignorados. Em vez disso, você pode usar o comando CLI astro check para conferir ambos arquivos .astro e .ts. Esse plugin também suporta importar arquivos .astro de arquivos .ts (que podem ser úteis para re-exportar).

npm

npm install @astrojs/ts-plugin

pnpm

pnpm add @astrojs/ts-plugin

Yarn

yarn add @astrojs/ts-plugin

Então, adicione o seguinte no seu tsconfig.json:

tsconfig.json

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

Para checar que o plugin está funcionando, crie um arquivo .ts e importe um componente do Astro nele. Você não deve ter nenhuma mensagem de aviso do seu editor.

Frameworks de UI

Seção intitulada Frameworks de UI

Se o seu projeto utiliza um framework de UI, configurações adicionais dependendo do framework podem ser necessárias. Por favor veja a documentação do TypeScript do seu framework para mais informações. (Vue, React, Preact, Solid)

Importações de Tipos

Seção intitulada Importações de Tipos

Utilize importações e exportações explícitas de tipos sempre que possível.

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

Dessa forma, você evita casos extremos onde o bundler do Astro pode tentar incorretamente fazer bundle do seus tipos importados como se fossem JavaScript.

Você pode configurar o TypeScript para aplicar importações de tipos no seu arquivo tsconfig.json. Defina verbatimModuleSyntax como true. O TypeScript verificará suas importações e informará quando import type deve ser usado. Esta configuração é habilitada por padrão em todas as nossas predefinições.

tsconfig.json

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

Aliases de Importação

Seção intitulada Aliases de Importação

Astro suporta aliases de importação que você define na configuração paths do seu tsconfig.json. Leia nosso guia para aprender mais.

src/pages/sobre/nate.astro

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

tsconfig.json

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

Estendendo window e globalThis

Seção intitulada Estendendo window e globalThis

Você pode querer adicionar uma propriedade para o objeto global. Você pode fazer isso adicionando declarações de nível superior usando a palavra-chave declare ao seu arquivo env.d.ts:

env.d.ts

declare var minhaString: string;
declare function minhaFuncao(): boolean;

Isso fornecerá tipos para globalThis.minhaString e globalThis.minhaFuncao, assim como para window.minhaString e window.minhaFuncao.

Note que window só está disponível no código no lado do cliente. O globalThis está disponível no lado do servidor e no lado do cliente, mas seu valor no lado do servidor não é compartilhado com o cliente.

Se você só quer definir o tipo de uma propriedade no objeto window, forneça uma interface Window ao invés disso:

env.d.ts

interface Window {
  minhaFuncao(): boolean;
}

Propriedades de Componentes

Seção intitulada Propriedades de Componentes

O Astro suporta a tipagem das propriedades dos seus componentes via TypeScript. Para habilitar, adicione uma interface TypeScript Props ao frontmatter do seu componente. Uma declaração export pode ser utilizada, mas não é necessária. A extensão para VSCode do Astro automaticamente buscará pela interface Props e oferecerá suporte TypeScript adequado quando você utilizar aquele componente dentro de outro template.

src/components/OlaProps.astro

---
interface Props {
  nome: string;
  saudacao?: string;
}
const { saudacao = 'Olá', nome } = Astro.props;
---
<h2>{saudacao}, {nome}!</h2>

Padrões comuns de tipos de prop

Seção intitulada Padrões comuns de tipos de prop

• Se seu componente não recebe props ou conteúdo em slot, você pode usar type Props = Record<string, never>.

• Se seu componente deve receber filhos em seu slot padrão, você pode impor isso usando type Props = { children: any; };.

Utilitários de Tipagem

Seção intitulada Utilitários de Tipagem

Adicionado em: astro@1.6.0

O Astro vem com alguns tipos utilitários integrados para padrões de tipo de props comuns. Eles estão disponíveis dentro do entrypoint astro/types.

Atributos HTML integrados

Seção intitulada Atributos HTML integrados

O Astro fornece os tipos HTMLAttributes para checar que sua marcação está usando atributos HTML válidos. Você pode usar esses tipos para ajudar a construir as props de componentes.

Por exemplo, se você está construindo um componente <Link>, você pode fazer o seguinte para espelhar os atributos padrão de tags <a> nos tipos da prop do seu componente.

src/components/Link.astro

---
import type { HTMLAttributes } from 'astro/types';
// use um `type`
type Props = HTMLAttributes<'a'>;
// ou estenda com uma `interface`
interface Props extends HTMLAttributes<'a'> {
  minhaProp?: boolean;
}
const { href, ...attrs } = Astro.props;
---
<a href={href} {...attrs}>
  <slot />
</a>

Também é possível estender as definições JSX padrões para adicionar atributos que não são padrões redeclarando o namespace astroHTML.JSX em um arquivo d.ts.

src/custom-attributes.d.ts

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

  // Adiciona uma propriedade CSS personalizada ao objeto de estilo
  interface CSSProperties {
    '--theme-color'?: 'black' | 'white';
  }
}

Nota

astroHTML é injetado globalmente dentro de componentes .astro. Para utilizá-lo em arquivos TypeScript, utilize uma diretiva de barra tripla:

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

type MeusAtributos = astroHTML.JSX.ImgHTMLAttributes;

ComponentProps type

Seção intitulada ComponentProps type

Adicionado em: astro@4.3.0

Esta exportação de tipo permite que você referencie as Props aceitas por outro componente, mesmo que o componente não exporte o tipo Props diretamente.

O exemplo seguinte mostra a utilidade de usar ComponentProps de astro/types para referenciar os tipos Props de um componente <Button />:

src/pages/index.astro

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

import Button from "./Button.astro";

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

Tipo polimórfico

Seção intitulada Tipo polimórfico

Adicionado em: astro@2.5.0

Astro inclui um utilitário para tornar mais fácil construir componentes que podem renderizar como elementos HTML diferentes com total segurança de tipo. Isso é útil para componentes como <Link> que podem renderizar como <a> ou <button> dependendo das props passadas para ele.

O exemplo abaixo implementa um componente totalmente tipado e polimórfico que pode renderizar como qualquer elemento HTML. O tipo HTMLTag é usado para garantir que a prop as é um elemento HTML válido.

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

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

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

<Tag {...props} />

Inferir tipos de getStaticPaths()

Seção intitulada Inferir tipos de getStaticPaths()

Adicionado em: astro@2.1.0

Astro inclui utilitários para trabalhar com os tipos retornados pela sua função getStaticPaths() para rotas dinâmicas.

Você pode obter o tipo de Astro.params com InferGetStaticParamsType e o tipo de Astro.props com InferGetStaticPropsType:

src/pages/posts/[...slug].astro

---
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; }
---

Checagem de Tipos

Seção intitulada Checagem de Tipos

Para ver erros de tipagem em seu editor, por favor certifique-se de que você tem a extensão Astro para VS Code instalada. Por favor note que os comandos astro start e astro build irão transpilar o código com esbuild, porém não executarão nenhuma checagem de tipos. Para prevenir o seu código de fazer build quando conter erros de TypeScript, mude o seu script “build” no package.json para o seguinte:

package.json

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

Nota

astro check verifica todos os arquivos incluídos em seu projeto TypeScript. Para verificar tipos em arquivos Svelte e Vue, você pode usar os pacotes svelte-check e vue-tsc, respectivamente.

Leia mais sobre a importação de arquivos .ts no Astro.

Leia mais sobre Configuração TypeScript.

Solução de Problemas

Seção intitulada Solução de Problemas

Erros ao fazer a tipagem de múltiplos frameworks JSX ao mesmo tempo

Seção intitulada Erros ao fazer a tipagem de múltiplos frameworks JSX ao mesmo tempo

Um problema pode surgir ao se utilizar múltiplos frameworks JSX no mesmo projeto, já que cada framework requer configurações diferentes, e às vezes até conflitantes, dentro de tsconfig.json.

Solução: Defina a configuração jsxImportSource para react (padrão), preact ou solid-js dependendo do seu framework mais utilizado. Então, utilize um comentário pragma dentro de qualquer arquivo conflitante de outro framework.

Para a opção padrão de jsxImportSource: react, você usaria:

// Para Preact
/** @jsxImportSource preact */

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