This article was last updated on February 7, 2024 to reorganize content for clarity and add new Astro V4 features.
Introduction
Astro is one of the newest front-end frameworks. You can use it to build performant, content-driven websites such as blogs and e-commerce sites optimized for search engines. It combines static site generation and server-side rendering.
Astro is the all-in-one web framework designed for speed. Pull your content from anywhere and deploy it everywhere, all powered by your favorite UI components and libraries. - Astro
In this article, we will take a deep dive into the Astro framework, explore its key features, and guide you through the process of setting up your first Astro project.
By the end of this article, you will be able to use Astro to build performant and scalable websites and applications.
What we'll cover:
- How to Create Your First Astro Project
- Astro Project Structure
- How to define Pages and Layouts in Astro
- How to Build Components with Astro
- How to add event handlers in Astro
- Working with Static and Dynamic Content in Astro
- How to Manage Data in Astro
- Why you should use Astro?
- What is new in Astro V4?
Prerequisites
You need to install the tools below to try out the examples in this article.
- Node runtime environment: If you haven't, install the Node runtime environment from the Node downloads page. At the time of writing this article, you need to have Node version
18.14.1or higher. Recent Node versions also bundle the npm package manager out of the box. - Visual Studio Code: If you haven't, install Visual Studio code from the VS Code downloads page. You can also use another text editor or IDE of your choice.
- Astro VS Code extension: Astro has a VS Code extension that can significantly improve your development experience. After installing VS Code, install the VS Code extension for Astro from the marketplace. It has features such as syntax highlighting, code completion, and code formatting. It's a must-have plugin when using VS Code to write Astro code. Astro has similar plugins for other text editors and IDEs such as JetBrains and Vim. Check the setup docs for details.
You now have everything you need to start working with Astro. In the next section, you will learn how to create a new Astro project from scratch.
How to Create Your First Astro Project
In this section, you will learn how to set up a simple Astro project on your machine. The fastest way to set up an Astro project is to use the astro command line tool. You can also install Astro manually. However, we won't explore manual installation in this article. If you want to install it manually, check out the Astro documentation.
To create a new Astro project using the command line tool, run the command below on the terminal.
# npm
npm create astro@latest
# pnpm
pnpm create astro@latest
# yarn
yarn create astro
The command above will launch the Astro commandline wizard. You need to respond to the command line prompts as in the example below.
✔ Where should we create your new project? ./cosmic-conjunction
✔ How would you like to start your new project? Include sample files
✔ Do you plan to write TypeScript? No
✔ Install dependencies? Yes
✔ Initialize a new git repository? No
After creating your Astro project and installing dependencies, you can open the project directory in VS Code or any other text editor and run the command below to launch the development server.
# npm
npm run dev
# pnpm
pnpm run dev
# yarn
yarn run dev
Now, you have successfully created your first Astro project. You will learn about the Astro project structure in the next section.
Astro Project Structure
Astro has an opinionated project structure. Most Astro projects will require you to organize your files and directories as follows:
├── README.md
├── astro.config.mjs
├── package-lock.json
├── package.json
├── public
│ ├── favicon.svg
│ ├── index.css
│ └── index.js
├── src
│ ├── components
│ │ └── App.astro
│ ├── layouts
│ │ └── default.astro
│ ├── pages
│ │ ├── 404.astro
│ │ └── index.astro
│ └── styles
│ └── global.css
└── yarn.lock
This is the structure of a basic Astro project. Let's explore the files and directories above.
- The
astro.config.mjsfile is the Astro project configuration file - The
publicdirectory contains the project static assets - The
srcdirectory contains the project source code - The
componentsdirectory contains the project components - The
layoutsdirectory contains the project layouts - The
pagesdirectory contains the project pages - The
stylesdirectory contains the project styles
In the next section, you will learn about Astro layouts and pages.
How to define Pages and Layouts in Astro
Pages in Astro
Pages in Astro are similar to those in Next. They are responsible for your project routing. Every file in the pages directory is a page. For example, the index.astro file in the pages directory is the home page of your Astro project.
├── pages
│ ├── 404.astro
│ └── index.astro
Similarly, the 404.astro file is the 404 page of your Astro project.
Each file you create in the src/pages/ directory becomes an endpoint based on its file path. In the example below, the about.astro and contact.astro files are the about and contact pages respectively. You can access them at the /about and /contact paths respectively.
├── pages
│ ├── about.astro
│ ├── contact.astro
│ ├── blog
│ │ ├── [slug].astro
│ │ └── index.astro
│ └── index.astro
In the file structure above, the blog directory contains pages for your blog post. The /pages/blog/index.astro file is the home page for your blog and the [slug].astro file is the blog post page.
Astro supports dynamic routing. In the file structure above, we have blog folder with two files inside: index.astro and [slug].astro. The index.astro file maps to the /blog path and the [slug].astro file maps to the /blog/:slug path. The :slug is a dynamic parameter. If you've a blog post with the hello-world slug, then its URL path will be /blog/hello-world.
Therefore, the mapping between the file path and corresponding URL path will look like so:
/blog/index.astro -> /blog
/blog/[slug].astro -> /blog/hello-world
This process is called file-based routing. It is a simple and intuitive way to define routes in Astro.
Layouts in Astro
Layouts in Astro are similar to HTML templates that provide a reusable UI structure. The default.astro file in the layouts directory is the default layout of the project.
├── layouts
│ └── default.astro
The default.astro file defines the layout for all pages of your Astro project. The code below shows what a typical default.astro file looks like:
---
import { Head } from 'https://astrojs.org'
---
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="icon" href="/favicon.svg" type="image/svg+xml" />
<link rel="stylesheet" href="/index.css" />
<script type="module" src="/index.js"></script>
</head>
<body>
<slot />
</body>
</html>
Astro will inject any content you wrap within a layout component into a slot. Astro slots are similar to ng-content in Angular and children prop in React.
Let's say we have the MyLayout.astro layout:
---
import BaseHead from '../components/BaseHead.astro';
import Footer from '../components/Footer.astro';
const { title } = Astro.props
---
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<BaseHead title="{title}" />
</head>
<body>
<nav>
<a href="#">Home</a>
<a href="#">Posts</a>
<a href="#">Contact</a>
</nav>
<h1>{title}</h1>
<article>
<slot />
<!-- your content is injected here -->
</article>
<footer />
</body>
</html>
You can render the above layout like so:
---
import MyLayout from '../layouts/MyLayout.astro';
---
<MyLayout title="MyLayout">
<p>My layout!</p>
</MyLayout>
Astro will inject <p>My layout!</p> in place of the <slot /> element in the MyLayout component. It will also pass the title prop into the MyLayout component.
You will learn more about props in Astro in the next section.
How to Build Components with Astro
Components are the building blocks of all component-oriented frameworks like Astro.
Components are single units of UI. They are reusable and composable. This makes them easy to maintain and test. Your Astro project will always contain components. So Astro is a tree of components.
To create a component in Astro, create a file with the .astro extension. For example, Component.astro is an Astro component.
A basic component shell looks like so:
---
// Component Script (JavaScript)
---
<!-- Component Template (HTML + JS Expressions) -->
You write JavaScript code in the Component Script section. You need to enclose this section in a code fence. It is where you define the component logic.
The component template is written in HTML and you can use it for defining the component UI.
Let's create a component and name it MyComponent.astro:
<form action="post">
<input type="text" placeholder="Type your text here..." />
<button>Send</button>
</form>
This is a simple reusable component. It has a simple form element with an input field and a button. You can use it anywhere in your project.
The code below shows how you can import and render the above component anywhere in your project:
---
import MyComponent from '../components/MyComponent.astro';
---
<MyComponent />
How to add event handlers in Astro
Let's say we want to add a click event to the button in MyComponent. We know that the event handler will be a JavaScript function. Therefore, we will add a script tag to the component and write the JavaScript code in it.
<form>
<input type="text" placeholder="Type your text here..." />
<button id="submit-btn">Send</button>
</form>
<script>
function handleClick() {
console.log("Button clicked!");
}
document.querySelector("#submit-btn").addEventListener("click", handleClick);
</script>
We have added a click event handler to the button. The handleClick event handler is invoked when the button is clicked and it will log Button clicked! to the browser console.
How to Pass Props to Components in Astro
Props are one of the most important features in any component-oriented framework. Props are used to pass data from one component to another. This makes the components reusable and composable.
Let's see how we can pass props to an Astro component. We want to pass a button text to the MyComponent component. We will do this by rendering the component like so:
---
import MyComponent from '../components/MyComponent.astro';
---
<MyComponent buttonText="Send" />
In the code above, the prop name is buttonText and its value is "Send". You can pass any JavaScript data via props.
Let's see how you can access the prop in the MyComponent component.
---
const { buttonText } = Astro.props;
---
<form>
<input type="text" placeholder="Type your text here..." />
<button id="submit-btn">{buttonText}</button>
</form>
You can destructure the Astro.props object to access the prop.
The Astro object is available in all components and Astro puts all the props sent to that particular component in the component's Astro.props object. An Astro object instance is unique to each component.
Working with Static and Dynamic Content in Astro
Passing content to Astro components via slots
There are times when we want to render elements between the tags of a component:
<MyComponent>
<p>My component!</p>
</MyComponent>
With the code in our MyComponent component, the <p>My component!</p> will not be rendered. This is because the component template does not have a place to render the content. We will add a slot element to the component template:
---
const { buttonText } = Astro.props;
---
<form>
<input type="text" placeholder="Type your text here..." />
<button id="submit-btn">{buttonText}</button>
</form>
<slot />
Astro will render the element <p>My component!</p> in place of the slot element.
Astro has feature for naming slots so that you can render content in a specific slot. Let's say you want to render content at the start of the template and a footer at the end of the template. You can name the slots as header and footer:
---
const { buttonText } = Astro.props;
---
<slot name="header">
<form>
<input type="text" placeholder="Type your text here..." />
<button id="submit-btn">{buttonText}</button>
</form>
<slot name="footer" />
You can now render content in the header and footer slots like so:
<MyComponent>
<p slot="header">My component!</p>
<p slot="footer">My component!</p>
</MyComponent>
How to Manage Data in Astro
Managing data is a crucial aspect of web development, and Astro provides robust options for efficiently fetching and utilizing data within your projects. In this section, we will explore the various data management capabilities offered by Astro, including fetching data from external sources or APIs and leveraging that data within Astro templates and components.
Fetching Data from APIs in Astro
Astro provides the flexibility for retrieving data from external sources or APIs. You can utilize the full power of JavaScript to perform data fetching operations and seamlessly integrate the retrieved data into your Astro projects.
HTTP Requests
You can make HTTP requests using popular JavaScript libraries such as fetch or axios in Astro. These libraries provide convenient methods for sending GET, POST, PUT, DELETE, and other types of requests to external APIs. By leveraging these libraries, you can retrieve data from RESTful APIs or GraphQL endpoints.
Data Fetching Libraries
Astro also integrates well with data-fetching libraries like swr or react-query. These libraries provide additional features such as caching, automatic revalidation, and error handling, which can greatly simplify the process of fetching and managing data in our Astro projects.
Serverless Functions Another approach to fetching data in Astro involves using serverless functions. These functions run on the server side and allow us to fetch data from external sources or perform any necessary server-side processing. Astro supports serverless functions, enabling us to retrieve data dynamically and pass it to our Astro components during the build process.
---
import { getPosts } from '../lib/posts';
const posts = getPosts();
---
{posts.map((post) => (
<div>
<h2>{post.title}</h2>
<p>{post.body}</p>
</div>
))}
With data management capabilities, you can fetch and utilize data from external sources or APIs, empowering you to create dynamic and data-driven websites or applications. Whether you need to display blog posts, populate product information, or showcase real-time data, Astro offers a versatile toolkit for managing data within your projects.
Why you should use Astro?
The benefits of using Astro are numerous. We will explore some of them in this section.
Astro is a component-based front-end framework
Astro is a component-based framework. You can use it to build reusable UI components. This modular approach not only enhances code organization but also facilitates collaboration among team members, making it easier to maintain and scale projects.
Astro scores highly in core web vitals
In 2023, Astro was compared with other frameworks in terms of performance. Astro, Next, Nuxt, SvelteKit, WordPress, Remix, and Gatsby were compared against major core vitals assessments.
In the FID, First Input Delay, measurement Astro came second behind SvelteKit. Astro took the lead in Cumulative Layout Shift, Largest Contentful Paint (LCP), and Interaction to Next Paint (INP) measurements.
Integrate Astro with other front-end frameworks
Another advantage of Astro is its ability to seamlessly integrate with popular front-end frameworks and libraries such as React, Vue, and Svelte.
This compatibility ensures that developers can leverage their existing knowledge and expertise while harnessing the benefits of Astro.
Astro is fast by default
One of the strengths of Astro is its ability to deliver blazing-fast websites. By employing static site generation and intelligent caching, Astro optimizes performance by pre-rendering pages and serving them directly from a Content Delivery Network (CDN). This approach eliminates the need for server-side rendering on every request, resulting in lightning-fast loading times and improved SEO rankings.
Astro simplifies data fetching
Astro reduces the complexity associated with managing multiple data sources and APIs.
With its unified data fetching approach, you can fetch data from various sources and render them alongside static content. This simplifies the development process and eliminates the need for separate data fetching and rendering logic, resulting in cleaner code and improved developer productivity.
What is new in Astro V4?
The latest version of Astro, version 4.2, was released recently with new experimental features and bug fixes. To try out these new features, you can upgrade to the latest version using the @astrojs/upgrade command.
npx @astrojs/upgrade
You can also use your package manager's upgrade command like so:
npm install astro@latest
pnpm upgrade astro --latest
yarn upgrade astro --latest
Let's explore these features in the sub-sections below.
Experimental feature for prerendering pages using the Speculation Rules API
The new release of Astro introduces a new feature for prerendering pages using the browser's experimental Speculation Rules API. You can use it to prerender pages that a user is likely to visit next. This helps improve browsing experience. You can try out this experimental feature by adding the changes below to the astro.config.mjs file:
import { defineConfig } from "astro/config";
export default defineConfig({
prefetch: true,
experimental: {
clientPrerender: true,
},
});
Only chromium-based browsers support the Speculation Rules API at the moment. However, Astro provides fallback option for browsers that are yet to ship the Speculation Rules API.
Experimental feature modifying the routing priority for injected routes
Before the current version release, the routes you inject using the injectRoute API will have a higher priority than other routes. However, this behavior introduced issues that were difficult to debug.
With the new experimental feature, injected routes have the same priority order as other routes. You can enable this experimental feature by setting the value of the experimental.globalRoutePriority to true in the astro.config.mjs file.
import { defineConfig } from "astro/config";
export default defineConfig({
experimental: {
globalRoutePriority: true,
},
});
Feature to disable automatic redirects of the root URL to the default locale
In the version 4.2 release, you can disable Astro's default behavior of automatically redirecting the root URL to the default locale using the redirectToDefaultLocale config option.
import { defineConfig } from "astro/config";
export default defineConfig({
i18n: {
defaultLocale: "en",
locales: ["en", "fr"],
routing: {
prefixDefaultLocale: true,
redirectToDefaultLocale: false,
},
},
});
Automatic redirects of the root URL to the default locale is enabled by default.
Feature for customizing image optimization in Markdown
Before the version 4.2 release of Astro, images in Markdown files are optimized using Astro's default image optimization settings. However, with the 4.2 version release of Astro, you can customize how your Markdown images are optimized like so:
import { visit } from "unist-util-visit";
export default function remarkPlugin() {
return (tree) => {
visit(tree, "image", (node) => {
node.data.hProperties = node.data.hProperties || {};
node.data.hProperties.width = "100";
node.data.hProperties.height = "100";
});
};
}
This feature is still limited to only Markdown files. Hopefully, Astro will introduce support for other file types.
Improved accessibility rules
The Astro Dev Toolbar enhances your development experience by making it possible to inspect your web page and catch accessibility defects in development. The new release of Astro improves the accessibility rules in the Astro Dev Toolbar.
Conclusion
Astro is a popular front-end framework. You can use it to build performant, content-rich websites such as blogs, landing pages, documentation sites, and portfolios.
You can create an Astro project instantly with the Astro command line tool or set up a project manually. The command line tool will instantly set up a complete Astro project with all the necessary setup.
Astro is a server-first framework by design. Astro Components don't render on the client side. They are built into plain HTML either at build time or on-demand during SSR.
You can opt-in to client-side rendering only when necessary by integrating Astro with popular front-end frameworks such as React, Vue, and Svelte.