Imports
Astro supports most static assets with zero configuration required. You can use the import
statement anywhere in your project JavaScript (including your Astro frontmatter) and Astro will include a built, optimized copy of that static asset in your final build. @import
is also supported inside of CSS & <style>
tags.
Supported File Types
Section titled Supported File TypesThe following file types are supported out-of-the-box by Astro:
- Astro Components (
.astro
) - Markdown (
.md
,.markdown
, etc.) - JavaScript (
.js
,.mjs
) - TypeScript (
.ts
) - NPM Packages
- JSON (
.json
) - CSS (
.css
) - CSS Modules (
.module.css
) - Images & Assets (
.svg
,.jpg
,.png
, etc.)
Additionally, you can extend Astro to add support for different UI Frameworks like React, Svelte and Vue components. You can also install the Astro MDX integration or the Astro Markdoc integration to use .mdx
or .mdoc
files in your project.
Files in public/
Section titled Files in public/You can place any static asset in the public/
directory of your project, and Astro will copy it directly into your final build untouched. public/
files are not built or bundled by Astro, which means that any type of file is supported.
You can reference a public/
file by a URL path directly in your HTML templates.
Import statements
Section titled Import statementsAstro uses ESM, the same import
and export
syntax supported in the browser.
JavaScript
Section titled JavaScriptJavaScript can be imported using normal ESM import
& export
syntax.
An appropriate UI framework (React, Preact, or Solid) is required to render JSX/TSX files.
Use .jsx
/.tsx
extensions where appropriate, as Astro does not support JSX in .js
/.ts
files.
TypeScript
Section titled TypeScriptAstro includes built-in support for TypeScript. You can import .ts
and .tsx
files directly in your Astro project, and even write TypeScript code directly inside your Astro component script and any script tags.
Astro doesn’t perform any type checking itself. Type checking should be taken care of outside of Astro, either by your IDE or through a separate script. For type checking Astro files, the astro check
command is provided.
Per TypeScript’s module resolution rules, .ts
and .tsx
file extensions should not be used when importing TypeScript files. Instead, either use .js
/.jsx
file extensions or completely omit the file extension.
NPM Packages
Section titled NPM PackagesIf you’ve installed an NPM package, you can import it in Astro.
If a package was published using a legacy format, Astro will try to convert the package to ESM so that import
statements work. In some cases, you may need to adjust your vite
config for it to work.
Some packages rely on a browser environment. Astro components runs on the server, so importing these packages in the frontmatter may lead to errors.
Astro supports importing JSON files directly into your application. Imported files return the full JSON object in the default import.
Astro supports importing CSS files directly into your application. Imported styles expose no exports, but importing one will automatically add those styles to the page. This works for all CSS files by default, and can support compile-to-CSS languages like Sass & Less via plugins.
CSS Modules
Section titled CSS ModulesAstro supports CSS Modules using the [name].module.css
naming convention. Like any CSS file, importing one will automatically apply that CSS to the page. However, CSS Modules export a special default styles
object that maps your original classnames to unique identifiers.
CSS Modules help you enforce component scoping & isolation on the frontend with uniquely-generated class names for your stylesheets.
Other Assets
Section titled Other AssetsAll other assets not explicitly mentioned above can be imported via ESM import
and will return a URL reference to the final built asset. This can be useful for referencing non-JS assets by URL, like creating an image element with a src
attribute pointing to that image.
It can also be useful to place images in the public/
folder as explained on the project-structure page.
?url
, ?raw
) in Vite’s static asset handling guide.
Adding alt text to <img>
tags is encouraged for accessibility! Don’t forget to add an alt="a helpful description"
attribute to your image elements. You can just leave the attribute empty if the image is purely decorative.
Aliases
Section titled AliasesAn alias is a way to create shortcuts for your imports.
Aliases can help improve the development experience in codebases with many directories or relative imports.
In this example, a developer would need to understand the tree relationship between src/pages/about/company.astro
, src/components/controls/Button.astro
, and src/assets/logo.png
. And then, if the company.astro
file were to be moved, these imports would also need to be updated.
You can add import aliases in tsconfig.json
.
Make sure compilerOptions.baseUrl
is set so the aliased paths can be resolved.
The development server will automatically restart after this configuration change. You can now import using the aliases anywhere in your project:
These aliases are also integrated automatically into VS Code and other editors.
import.meta.glob()
Section titled import.meta.glob()Vite’s import.meta.glob()
is a way to import many files at once using glob patterns to find matching file paths.
import.meta.glob()
takes a relative glob pattern matching the local files you’d like to import as a parameter. It returns an array of each matching file’s exports. To load all matched modules up front, pass { eager: true }
as the second argument:
Astro components imported using import.meta.glob
are of type AstroInstance
. You can render each component instance using its default
property:
Supported Values
Section titled Supported ValuesVite’s import.meta.glob()
function only supports static string literals. It does not support dynamic variables and string interpolation.
A common workaround is to instead import a larger set of files that includes all the files you need, then filter them:
Import type utilities
Section titled Import type utilitiesMarkdown files
Section titled Markdown filesMarkdown files loaded with import.meta.glob()
return the following MarkdownInstance
interface:
You can optionally provide a type for the frontmatter
variable using a TypeScript generic.
Astro files
Section titled Astro filesAstro files have the following interface:
Other files
Section titled Other filesOther files may have various different interfaces, but import.meta.glob()
accepts a TypeScript generic if you know exactly what an unrecognized file type contains.
Glob Patterns
Section titled Glob PatternsA glob pattern is a file path that supports special wildcard characters. This is used to reference multiple files in your project at once.
For example, the glob pattern ./pages/**/*.{md,mdx}
starts within the pages subdirectory, looks through all of its subdirectories (/**
), and matches any filename (/*
) that ends in either .md
or .mdx
(.{md,mdx}
).
Glob Patterns in Astro
Section titled Glob Patterns in AstroTo use with import.meta.glob()
, the glob pattern must be a string literal and cannot contain any variables.
Additionally, glob patterns must begin with one of the following:
./
(to start in the current directory)../
(to start in the parent directory)/
(to start at the root of the project)
Read more about the glob pattern syntax.
import.meta.glob()
vs getCollection()
Section titled import.meta.glob() vs getCollection()Content collections provide a getCollection()
API for loading multiple files instead of Astro.glob()
. If your content files (e.g. Markdown, MDX, Markdoc) are located in collections within the src/content/
directory, use getCollection()
to query a collection and return content entries.
Astro supports loading WASM files directly into your application using the browser’s WebAssembly
API.
Node Builtins
Section titled Node BuiltinsWe encourage Astro users to avoid Node.js builtins (fs
, path
, etc.) whenever possible. Astro is compatible with multiple runtimes using adapters. This includes Deno and Cloudflare Workers which do not support Node builtin modules such as fs
.
Our aim is to provide Astro alternatives to common Node.js builtins. However, no such alternatives exist today. So, if you really need to use these builtin modules we don’t want to stop you. Astro supports Node.js builtins using Node’s newer node:
prefix. If you want to read a file, for example, you can do so like this:
Extending file type support
Section titled Extending file type supportWith Vite and compatible Rollup plugins, you can import file types which aren’t natively supported by Astro. Learn where to find the plugins you need in the Finding Plugins section of the Vite Documentation.
Refer to your plugin’s documentation for configuration options, and how to correctly install it.