Importações

Astro suporta a maioria dos assets estáticos com zero configurações necessárias. Você pode usar a declaração import em qualquer lugar do seu projeto JavaScript (incluindo seu frontmatter Astro) e Astro irá incluir uma cópia otimizada do asset estático na build final do seu projeto. @import também é suportado dentro de CSS e tags <style>.

Tipos de Arquivos Suportados

Os tipos de arquivos abaixo são suportados por padrão pelo Astro:

Componentes Astro (.astro)
Markdown (.md, .markdown, etc.)
JavaScript (.js, .mjs)
TypeScript (.ts, .tsx)
Pacotes NPM
JSON (.json)
CSS (.css)
Módulos CSS (.module.css)
Imagens e Assets (.svg, .jpg, .png, etc.)

Adicionalmente, você pode estender o Astro para adicionar suporte a diferentes Frameworks de UI como componentes React, Svelte e Vue. Você também pode instalar a integração MDX do Astro (EN) ou a integração Astro Markdoc (EN) para usar arquivos .mdx ou .mdoc em seu projeto.

Arquivos em `public/`

Você pode colocar qualquer recurso estático no diretório public/ do seu projeto, e Astro irá copiá-lo diretamente em sua build final sem mudanças. Arquivos do diretório public/ não passam por empacotamento ou incorporação pelo Astro, o que significa que qualquer tipo de arquivo é suportado.

Você pode referenciar um arquivo do diretório public/ por um caminho de URL diretamente em seus templates HTML.

// Para usar o link /public/reports/annual/2024.pdf
Faça o download <a href="/reports/annual/2024.pdf">do relatório anual de 2024 como PDF</a>.

// Para mostrar /public/assets/cats/ginger.jpg
<img src="/assets/cats/ginger.jpg" alt="Um gato laranja dormindo em uma cama.">

Declarações de importação

Astro utiliza ESM, a mesma sintaxe de import e export suportada no navegador.

JavaScript

import { getUsuario } from './usuario.js';

JavaScript pode ser importado usando a sintaxe de import e export normal do ESM.

TypeScript

import { getUsuario } from './usuario';
import type { TipoUsuario } from './usuario';

Astro inclui suporte por padrão para TypeScript. Você pode importar arquivos .ts e .tsx diretamente em seu projeto Astro e até escrever código TypeScript dentro do seu script do componente Astro e em quaisquer tags script hoisted.

Astro não realiza checagem de tipos por si. A checagem de tipos deve ser feita fora do Astro, seja em sua IDE ou através de scripts separados. Para checar tipos em arquivos Astro, o comando astro check é providenciado.

Pelas regras de resolução de módulo do TypeScript, as extensões de arquivo .ts e .tsx não devem ser usadas ao importar arquivos TypeScript. No lugar, ou utilize as extensões de arquivo .js/.jsx ou omita a extensão de arquivo.

import { getUsuario } from './usuario.js'; // usuario.ts
import MeuComponente from "./MeuComponente"; // MeuComponente.tsx

Leia mais sobre o suporte TypeScript no Astro.

Pacotes do NPM

Se você instalou um pacote do NPM, você pode importá-lo no Astro.

---
import { Icon } from 'astro-icon';
---

Se um pacote foi publicado em um formato antigo, Astro irá tentar converter o pacote para ESM para que então declarações de import funcionem. Em alguns casos, você pode precisar ajustar sua configuração do vite para que ele funcione.

JSON

// Carrega o objeto JSON pelo "export" padrão.
import json from './dados.json';

Astro dá suporte para a importação de arquivos JSON diretamente em sua aplicação. Arquivos importados retornam o objeto JSON completo no import padrão.

CSS

// Carrega e injeta o arquivo 'estilos.css' na página
import './estilos.css';

Astro suporta a importação de arquivos CSS diretamente em sua aplicação. Estilos importados não proveem nenhum “export”, mas importar um arquivo CSS irá automaticamente adicionar seus estilos à página. Isto funciona para todos os arquivos CSS por padrão e pode suportar também pré-processadores como Sass e Less via plugins.

Leia mais sobre casos de uso de CSS avançados como referência direta de URL para um arquivo CSS, ou importar CSS como string no guia de estilização.

Módulos CSS

// 1. Converte os nomes das classes de `./estilos.module.css` para valores únicos e escopados.
// 2. Retorna um objeto que mapeia os nomes das classes originais aos seus valores únicos e escopados.
import estilos from './estilos.module.css';

// Esse exemplo usa JSX, mas você pode usar Módulos CSS com qualquer framework.
return <div className={estilos.erro}>Sua Mensagem de Erro</div>;

Astro suporta Módulos CSS usando a convenção de nome [nome].module.css. Como qualquer arquivo CSS, importá-lo vai automaticamente aplicar os estilos à página. Entretanto, Módulos CSS exportam um objeto padrão que mapeia os nomes originais de suas classes em identificadores únicos.

Módulos CSS ajudam a reforçar o escopo e o isolamento de componentes no frontend com nomes de classes únicos gerados para suas folhas de estilos.

Outros Assets

import referenciaImg from './imagem.png'; // referenciaImg === '/src/imagem.png'
import referenciaSvg from './imagem.svg'; // referenciaSvg === '/src/imagem.svg'
import referenciaTxt from './palavras.txt'; // referenciaTxt === '/src/palavras.txt'

// Esse exemplo usa JSX, mas você pode importar as referências em qualquer framework.
<img src={referenciaImg.src} alt="descrição da imagem" />;

Todos os outros assets que não foram explicitamente mencionados acima podem ser importados via import do ESM e irão retornar a URL de referência à build final do asset. Isto pode ser útil para referenciar assets que não são JavaScript pela URL, como por exemplo, criar um elemento img com o atributo src apontando para aquela imagem.

Também pode ser útil colocar as imagens no diretório public/ como explicado na página de estrutura de projetos.

Leia mais sobre acrescentar parâmetros de importação Vite (como ?url, ?raw) no guia Vite de manipulação de recursos estáticos.

Aliases

Um alias é uma maneira de criar atalhos para as suas importações.

Os aliases podem ajudar a melhorar a experiência de desenvolvimento em bases de código com muitos diretórios ou importações relativas.

---
import Botao from '../../components/controles/Botao.astro';
import logoUrl from '../../assets/logo.png?url';
---

Nesse exemplo, um desenvolvedor precisaria entender a relação de árvore entre src/pages/sobre/empresa.astro, src/components/controles/Botao.astro e src/assets/logo.png. E então, se o arquivo empresa.astro fosse movido, essas importações também precisariam ser atualizadas.

Você pode adicionar aliases de importação a partir de tsconfig.json ou jsconfig.json.

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

O servidor de desenvolvimento será reiniciado automaticamente após essa alteração de configuração. Agora você pode importar usando os aliases em qualquer lugar do seu projeto:

---
import Botao from '@components/Botao.astro';
import logoUrl from '@assets/logo.png?url';
---

Esses aliases também são integrados automaticamente ao VS Code e a outros editores.

`import.meta.glob()`

import.meta.glob() de Vite é uma forma de importar vários arquivos de uma vez só usando padrões glob para encontrar caminhos de arquivo correspondentes.

import.meta.glob() recebe um padrão glob relativo como parâmetro correspondendo aos arquivos locais que você gostaria de importar. Retorna um array com as exportações de cada arquivo correspondente. Para carregar todos os módulos de antemão, passe { eager: true } como segundo argumento:

---
// importa todos os arquivos que terminam com `.md` em `./src/pages/postagens/`
const matches = import.meta.glob('../pages/postagens/*.md', { eager: true });
const postagens = Object.values(matches);
---
<!-- Renderiza um <article> para as 5 primeiras postagens do blog -->
<div>
{postagens.slice(0, 4).map((postagem) => (
  <article>
    <h2>{postagem.frontmatter.titulo}</h2>
    <p>{postagem.frontmatter.descricao}</p>
    <a href={postagem.url}>Leia mais</a>
  </article>
))}
</div>

Componentes Astro importados usando import.meta.glob são do tipo AstroInstance. Você pode renderizar cada instância de componente usando sua propriedade default:

---
// importa todos os arquivos que terminam com `.astro` em `./src/components/`
const componentes = Object.values(import.meta.glob('../components/*.astro', { eager: true }));
---
<!-- Mostra todos os nossos componentes -->
{componentes.map((componente) => (
  <div>
    <componente.default size={24} />
  </div>
))}

Valores Suportados

A função Vite import.meta.glob() suporta apenas literais de string estáticas. Ela não suporta variáveis dinâmicas e interpolação de string.

Uma solução alternativa comum é importar uma ‘serie maior de arquivos que incluem todos os arquivos que você precisa, e então filtrá-los:

---
const { postSlug } = Astro.props;
const pathToMyFeaturedPost = `src/pages/blog/${postSlug}.md`;

const posts = Object.values(import.meta.glob("../pages/blog/*.md", { eager: true }));
const myFeaturedPost = posts.find(post => post.file.includes(pathToMyFeaturedPost));
---

<p>
  Dê uma olhada em minha postagem favorita: <a href={myFeaturedPost.url}>{myFeaturedPost.frontmatter.title}</a>!
</p>

Utilidades do tipo import

Arquivos Markdown

Arquivos Markdown carregados com import.meta.glob() retornam a seguinte interface MarkdownInstance:

export interface MarkdownInstance<T extends Record<string, any>> {
  /* Qualquer dado especificado no frontmatter YAML/TOML do arquivo */
  frontmatter: T;
  /* O caminho de arquivo absoluto deste arquivo */
  file: string;
  /* O caminho renderizado deste arquivo */
  url: string | undefined;
  /* O Componente Astro que renderiza os conteúdos deste arquivo */
  Content: AstroComponentFactory;
  /** (Apenas Markdown) O conteúdo bruto do arquivo Markdown, excluindo layout HTML e frontmatter YAML/TOML */
  rawContent(): string;
  /** (Apenas Markdown) O arquivo markdown compilado em HTML, excluindo layout HTML */
  compiledContent(): string;
  /* Função que retorna um array dos elementos h1...h6 deste arquivo */
  getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
  default: AstroComponentFactory;
}

Você pode fornecer opcionalmente um tipo para a variável frontmatter utilizando um TypeScript genérico.

---
import type { MarkdownInstance } from 'astro';
interface Frontmatter {
    title: string;
    description?: string;
}

const posts = Object.values(import.meta.glob<MarkdownInstance<Frontmatter>>('./posts/**/*.md', { eager: true }));
---

<ul>
  {posts.map(post => <li>{post.frontmatter.title}</li>)}
</ul>

Arquivos Astro

Arquivos Astro possuem a seguinte interface:

export interface AstroInstance {
  /* O caminho de arquivo deste arquivo */
  file: string;
  /* A URL para esse arquivo (se estiver no diretório pages) */
  url: string | undefined;
  default: AstroComponentFactory;
}

Outros arquivos

Outros arquivos podem ter várias interfaces diferentes, mas import.meta.glob() aceita um TypeScript genérico se você souber exatamente o quê um tipo de arquivo desconhecido contém.

---
interface CustomDataFile {
  default: Record<string, any>;
}
const data = import.meta.glob<CustomDataFile>('../data/**/*.js');
---

Padrões de Glob

Um padrão de glob é um caminho de arquivo que suporta caracteres curinga especiais. Eles são usados para referenciar múltiplos arquivos em seu projeto de uma vez.

Por exemplo, o padrão de glob ./pages/**/*.{md,mdx} começa no subdiretório “pages”, vendo através de todos os seus subdiretórios (/**), e corresponde a qualquer nome de arquivo (/*) que termine em .md ou .mdx (.{md,mdx}).

Padrões de Glob no Astro

Para usar com import.meta.glob(), o padrão glob deve ser uma string literal e não pode conter qualquer variável.

Adicionalmente, padrões de glob devem começar com um dos seguintes:

./ (para começar no diretório atual)
../ (para começar no diretório parente)
/ (para começar na raiz do projeto)

`import.meta.glob()` vs `getCollection()`

Coleções de conteúdo fornecem uma API getCollection() (EN) para carregamento de múltiplos arquivos em vez de import.meta.glob(). Se seus arquivos de conteúdo (como Markdown, MDX, Markdoc) estão localizados em coleções dentro do diretório src/content/, use getCollection() para consultar uma coleção e retornar entradas de conteúdo.

WASM

// Carrega e inicializa o arquivo WASM requisitado
const wasm = await WebAssembly.instantiateStreaming(fetch('/exemplo.wasm'));

Astro suporta o carregamento de arquivos WASM (Web Assembly) diretamente na sua aplicação usando a API WebAssembly do navegador.

Módulos Node Nativos

Nós recomendamos aos usuários do Astro que evitem o uso de módulos nativos do Node.js (fs, path e etc) sempre que possível. Astro é compatível com múltiplos motores usando adaptadores (EN). Isto inclui o Deno e o Cloudflare Workers (EN) que não possuem suporte aos módulos integrados do Node como o fs.

Nossa missão é prover alternativas Astro para os módulos Node.js mais comuns. Entretanto, isto estas alternativas ainda não existem hoje. Então, se você realmente precisa utilizar estes módulos, nós não queremos o impedir. Astro suporta os módulos Node.js usando o novo prefixo node: do Node. Se você precisa ler um arquivo, por exemplo, você pode fazer assim:

---
// Exemplo: importa o módulo "fs/promises" do Node.js
import fs from 'node:fs/promises';

const url = new URL('../../package.json', import.meta.url);
const json = await fs.readFile(url, 'utf-8');
const dados = JSON.parse(json);
---
<span>Versão: {dados.version}</span>

Estendendo suporte de tipos de arquivo

Com plugins Vite e Rollup compatíveis, você pode importar tipos de arquivos que não são nativamente suportados pelo Astro. Para como encontrar os plugins que você precisa na seção Finding Plugins da documentação do Vite.

Receita relacionada: Instalando um plugin Vite ou Rollup

Contribua Comunidade Sponsor