Pular para o conteúdo

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.

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 types="astro/client" />

Se você não está usando VSCode, você pode instalar o plugin Astro TypeScript para suportar a importação de arquivos .astro de arquivos .ts (que pode ser útil para reexportação).

Terminal window
npm install @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 reforçar importações de tipos no seu arquivo .tsconfig. Defina verbatimModuleSyntax como true. O TypeScript verificará suas importações e informará quando import type deve ser usado. Esta configuração está 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 e jsconfig.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 const 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, exporte uma interface TypeScript Props de seu componente Astro. A extensão para VSCode do Astro irá automaticamente procurar pela exportação de Props e te dar suporte a TypeScript quando você utilizar aquele componente dentro de outro template.

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

Padrões de tipo de prop comuns

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

  • 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 `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';
  }
}

ComponentProps type

Seção intitulada ComponentProps type

Adicionado em: astro@4.3.0

Esta exportação de tipo permite que você referencie as Props aceitadas 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 de um componente <Button /> Props:

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 segurança total 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 os tipos do getStaticPaths()

Seção intitulada Inferir os tipos do 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 de que os comandos astro start e astro build irão transpilar o código com esbuild, porém não executará 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",
  },
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 as vezes até conflitantes, dentro de tsconfig.json.

Solução: Defina a opçã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 */