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
,.tsx
) - NPM Packages
- JSON (
.json
) - JSX (
.jsx
,.tsx
) - 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 and use .mdx
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 JavaScriptimport { getUser } from './user.js';
JavaScript can be imported using normal ESM import
& export
syntax.
TypeScript
Section titled TypeScriptimport { getUser } from './user';
import type { UserType } from './user';
Astro 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 hoisted 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.
📚 Read more about TypeScript support in Astro.
JSX / TSX
Section titled JSX / TSXimport { MyComponent } from './MyComponent.jsx';
Astro includes built-in support for JSX (*.jsx
and *.tsx
) files in your project. JSX syntax is automatically transpiled to JavaScript.
While Astro understands JSX syntax out-of-the-box, you will need to include a framework integration to properly render frameworks like React, Preact and Solid. Check out our Using Integrations guide to learn more.
NPM Packages
Section titled NPM PackagesIf you’ve installed an NPM package, you can import it in Astro.
---
import { Icon } from 'astro-icon';
---
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.
// Load the JSON object via the default export
import json from './data.json';
Astro supports importing JSON files directly into your application. Imported files return the full JSON object in the default import.
// Load and inject 'style.css' onto the page
import './style.css';
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 Modules// 1. Converts './style.module.css' classnames to unique, scoped values.
// 2. Returns an object mapping the original classnames to their final, scoped value.
import styles from './style.module.css';
// This example uses JSX, but you can use CSS Modules with any framework.
return <div className={styles.error}>Your Error Message</div>;
Astro 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 Assetsimport imgReference from './image.png'; // imgReference === '/src/image.png'
import svgReference from './image.svg'; // svgReference === '/src/image.svg'
import txtReference from './words.txt'; // txtReference === '/src/words.txt'
// This example uses JSX, but you can use import references with any framework.
<img src={imgReference} alt="image description" />;
All 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.
Astro.glob()
Section titled Astro.glob()Astro.glob()
is a way to import many files at once.
Astro.glob()
only takes one parameter: a relative glob pattern matching the local files you’d like to import. It’s asynchronous, and returns an array of each matching file’s exports.
---
// imports all files that end with `.md` in `./src/pages/post/`
const posts = await Astro.glob('../pages/post/*.md');
---
<!-- Renders an <article> for the first 5 blog posts -->
<div>
{posts.slice(0, 4).map((post) => (
<article>
<h1>{post.frontmatter.title}</h1>
<p>{post.frontmatter.description}</p>
<a href={post.url}>Read more</a>
</article>
))}
</div>
Astro components imported using Astro.glob
are of type AstroInstance
. You can render each component instance using its default
property:
---
// imports all files that end with `.astro` in `./src/components/`
const components = await Astro.glob('../components/*.astro');
---
<!-- Display all of our components -->
{components.map((component) => (
<div>
<component.default size={24} />
</div>
))}
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 Astro.glob()
, the glob pattern must be a string literal and cannot contain any variables. See the troubleshooting guide for a workaround.
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.
// Loads and initializes the requested WASM file
const wasm = await WebAssembly.instantiateStreaming(fetch('/example.wasm'));
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 aims to be compatible with multiple JavaScript runtimes in the future. 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:
---
// Example: import the "fs/promises" builtin from 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 data = JSON.parse(json);
---
<span>Version: {data.version}</span>
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.
Example: YAML support
Section titled Example: YAML supportThe YAML (.yml
) data format isn’t natively supported by Astro, but you can add support for it by using a compatible Rollup plugin like @rollup/plugin-yaml
:
-
Install
@rollup/plugin-yaml
:npm install @rollup/plugin-yaml --save-dev
-
Import the plugin in your
astro.config.mjs
and add it to the Vite plugins array:astro.config.mjs import { defineConfig } from 'astro/config'; import yaml from '@rollup/plugin-yaml'; export default defineConfig({ vite: { plugins: [yaml()] } });
-
Finally, you can import YAML data using an
import
statement:import yml from './data.yml';