Astro is a performance-focused static site generator. The framework is rapidly gaining popularity and competing with the popular NextJS.
What’s so good about Astro? We’ll tell you about the framework’s main concepts, its architectural patterns, approaches, and features that allow you to achieve a high level of optimization.
We will dive into the topic in the process of assembling a blog on frontend development. By the way, all the content for the site on behalf of the developer will be generated for us by ChatGPT.
What is Astro?
Astro is a web framework, a static site generator that builds without JavaScript. With Astro, you can use any library: React, Vue, Angular, and others.
As a rule, modern frontend development looks something like this: we load a huge JS file, it is parsed and only then everything is rendered. Yes, there are optimizations, division into chunks, disabling JavaScript - but the performance problem itself does not go away.
Astro offers us a completely different approach: by default, collect pure HTML and CSS, and mark all dynamic elements manually. This is called “island architecture”, where the water is HTML and CSS, and the islands are JS.
Why Astro?
Astro is loved for several reasons:
Ease of development . Vite is running under the hood, everything is assembled quickly, you can add libraries, change the config - and not rebuild the build.
Working with libraries . Not only can you integrate any library into Astro, but you can also combine them with no problem.
Maintaining web standards is very easy when you work with pure HTML and CSS.
Product autonomy . HTML + CSS + CDN are the foundation of the Internet. You build a product, upload it — and it works without support.
Simplicity : Unlike React, which was originally created for the complex Facebook, Astro is ideal for simple sites without a million dependencies.
We can say that Astro allows us to build a basic web with modern conveniences. The idea itself is interesting - let’s see how it is implemented in practice.
Creating a project We start in the console — by creating a repository with an empty Astro project. If you are running Astro for the first time, you need to allow the installation of the create-astro package. Install dependencies and select TypeScript.
In the TypeScript rules, select strict (you can read about the differences here ) and initialize the repository.
Now you can move on to the editor. We will use WebStorm. If yours does not support Astro, update to the latest version. The documentation has tips on VS Code and other tools.
In our project, among other things, we see a certain file called env.d.ts. This is a declared TypeScript file with types. The thing is that under the hood we have Vite running, and its default types are intended for the Node.js API. To change the code environment on the client side, env.d.ts is added — in our case, Astro did it itself.
Go to package.json and run the project build:
npm run start
At localhost:3000 we see our website.
Let’s try to change one of the project files to see how the config changes. For example, let’s add .idea/ to .gitignore.
We see that after saving, everything is automatically rebuilt. That is, there is no need to restart the build every time the files are changed. This is a small thing - but super nice, because it greatly speeds up work in the long run.
Finally, let’s set up prettier so that everything looks nice:
npm install -DE prettier
echo {}> .prettierrc.json
touch .prettierignore
# build output
dist/
# generated types
.astro/
npx prettier --write .
And that’s it, our project is ready to work – you can proceed directly to mastering Astro.
Page creation and routing
First of all, let’s learn how to create new pages and switch between them.
We go to SRC and see the pages folder - we can say that it is the only mandatory one, because it acts as a router.
Here is the index.astro file. Let’s put the content for the main page in it, in our case — generated by ChatGPT (see scratches/base-index.html in the repository).
Next, we’ll create an Astro component in the pages folder called blog.astro — this is the future page of our blog. We’ll deal with the incomprehensible dashes a little later, but for now we’ll just add a title after them:
<h1>Blog<h1>You can see the result at localhost:3000/blog. Remember that the router is case sensitive!
Interestingly, we essentially wrote invalid HTML with only a bare heading <h1> — but in the browser we see Astro scripts <head> and <body>. You can read more about why this happens here .
In addition to Astro components, we can create MD and MDX (the same Markdown, but with the ability to import components), HTML and TypeScript/JavaScript files.
To see how this works in practice, let’s create three additional files in the pages folder:
about.md , for example, containing the same text that the neural network generated for the main page (see base-about.md).
account.html with any random code (we will not use it in this project).
posts.ts with an endpoint for the API:
export async function get() {
return {
body: JSON.stringify([{ id: 1, title: "abc" }]),
};
}Let’s see how each of them works:
At localhost:3000/about we see markdown, which Astro automatically parsed: it placed tags, assigned IDs to the headings.
The HTML file we put there is located at localhost:3000/account .
At localhost:3000 / posts we get a JSON response.
We see that all routing is configured out of the box for all pages of different formats. Let’s assemble the project and see what we get in the end:
npm run build
The dist directory appeared — our files are in it: each in its own separate folder. We see that in fact they are all generated statically, including the response from the API.
Creating Templates
You probably thought about having templates for each type of document when you were creating pages. Naturally, Astro offers tools to create them.
To store templates, we create a layouts folder. It is not mandatory, but according to Astro convention , it is customary to call it this way, first of all, so that the project remains readable for other developers.
In the layouts folder, create a file Layout.astro, copy the code from index.astro there and clear it of content:
<html lang="ru">
<head>
<meta charset="utf-8" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<meta name="viewport" content="width=device-width" />
<meta name="generator" content={Astro.generator} />
<title>Сайт ChatGPT — фронтендера со стажем</title>
</head>
<body>
<slot />
</body>
</html>Note the <slot />. This is essentially the same as children in React — it is needed to display the content inside the component. However, there are some differences from children: for example, you can insert several components into a slot at once without a parent.
The template is ready - it can be integrated into files. So we return to index.astro, import Layout (inside those mysterious dashes) and wrap all the content in it:
---
import Layout from '../layouts/Layout.astro';
---
<Layout>
<h1>Hello, Astro</h1>
</Layout>By analogy, we add a template to blog.astro and a little differently to about.md :
---
layout: ../layouts/Layout.astro
---
# AboutBut you can’t apply a template to an HTML file in Astro, so it’s better to abandon this extension. Now that we know about this, the account.html document can be safely deleted.
Below we will examine in more detail the structure of .astro and .md file formats.
Files of .astro and .md formats What is the .astro format anyway?
Files of this format should be treated as server files, not as frontend. If you’ve ever worked with PHP, Astro is very similar: we get data on the server, form a page and send it to the client. Except that the syntax here is more modern, JS-like.
When we run npm run start, the server starts spinning. It processes Astro files and eventually, when we run npm run build, it assembles them into regular HTML.
What are those dashes/hyphens we see at the beginning of every Astro file?
In English, this thing is called a code fence — literally, a “fence made of code.” Everything that is within its boundaries is executed only on the server and does not penetrate the browser in any way. Therefore, inside the code fence, you can write passwords from services, tokens, and other unsafe things that cannot be given to the frontend.
Typically, the following are placed “behind the fence”:
the import of Astro components,
theimport other framework components, such as React,
component props,
the import data such as JSON files or images,
getting content from an API or database,
declaration of variables that are going to be referenced on the client.
Here’s how we can create a variable inside the code fence in index.astro:
---
import Layout from '../layouts/Layout.astro';
const title = 'Hello, Astro';
const list = ['a', 'b', 'c'];
---
<Layout>
<h1>{title}</h1>
{list.map(item => <p>{item}</p>)}
</Layout>
Like this - add the page title there:
<Layout title="Главная">
...
</Layout>
And pull out the prop in the code fence of the Layout.astro template:
---
const { title = 'Astro' } = Astro.props;
---
...
<title>{title}</title>
...
What about markdown files?
You can't pass props into a markdown file the same way as you can into .astro - you have to do it in a different format with a different API. We can add title to about.md :
---
layout: ../layouts/Layout.astro
title: Обо мне
---
And then modify Layout.astro to handle both regular props and markdown props (frontmatter):
---
const { title = 'Astro', frontmatter = {} } = Astro.props;
const pageTitle = frontmatter.title || title;
---
Another option is to create a new MdLayout.astro template for the separation, which will inherit the main one:
---
import Layout from './Layout.astro';
const { frontmatter } = Astro.props;
---
<Layout title={frontmatter.title}>
<slot />
</Layout>
Content styling
We've figured out the project structure and templates, which means it's time to figure out how to write CSS in Astro. Once again, open index.astro and write the styles:
<style>
p {
font-size: 18px;
font-family: sans-serif;
}
</style>
Now we open DevTools and see one class for all elements. Astro creates a class per component (in our case, the component is the index.astro file) and specifies styles via the :where selector. Quite a creative way to ensure their closure natively.
The question arises: “Why do we need new incomprehensible selectors if we can use p.astro-dlkjdas - and the result will be the same?” It’s all about the zero specificity of the selector ( example ).
If we want to make global styles without any :where, we need to add is:global:
<style is:global>
p {
font-size: 18px;
font-family: sans-serif;
}
</style>Let’s compile build and look at the result. The .astro folder has appeared - it contains the CSS file. In index.html, Astro specifically includes styles for this page.
Builds with and without is:global look the same. Let’s look at the version with is:inline:
<style is:inline>
p {
font-size: 18px;
font-family: sans-serif;
}
</style>We do a build and see that the CSS file has disappeared, and the styles are now written inside index.html.
We can also place global styles in a separate file and connect them to the template. To do this, create a styles folder and a global.css file inside it:
p {
font-size: 18px;
font-family: sans-serif;
}Let’s connect styles to Layout.astro:
---
...
import '../styles/content.css';
...Now, to practice styling a little more, let’s add a header to the Layout.astro template for easy switching between pages (see scratches/base-layout.css). At the same time, let’s tidy up the styles in the global.css file (see scratches/base-global.css).
Image Image We don’t stop there. Since we are on the server, we can easily access the request, see what page was requested, and highlight the appropriate link.
Let’s write in the Layout.astro template that the link in the header should be active if it matches the first part of the requested path (/, /about, /blog):
---
const pathname = new URL(Astro.request.url).pathname;
const currentPath = pathname.split(“/”).filter(Boolean)[0];
---
<header>
<nav>
<a href="/" class:list={{ active: currentPath === undefined }}
>Главная</a
>
<a href="/about" class:list={{ active: currentPath === "about" }}
>Обо мне</a
>
<a href="/blog" class:list={{ active: currentPath === "blog" }}>Блог</a>
</nav>
<a href="/posts" class:list={{ active: currentPath === "posts" }}>АПИ</a>
</header>Let’s pay attention to two interesting points:
The fact is that in .astro files we add the class attribute to elements, and not the className attribute that we are used to in React.
On the list of classes class:list, which allows, among other things, adding classes depending on the fulfillment of a condition.
Before moving on to the next section, let’s finally get the blog page in order. To do this, fill the blog.astro file with prepared content: this is a list of future articles on the frontend from ChatGPT (see base-blog.html).
Interactivity Let’s move on to interactivity, that is, to JavaScript and UI libraries.
Scripts
Let’s start with the fact that the <script> tag is added in exactly the same way as the <style> tag - outside the code fence. So, feel free to open the index.astro file and add the test script to the end:
<script>
console.log('hello');
</script>We do a build to see how our script is generated on the frontend - and we see that it is inline built into index.html.
What’s interesting is that we can use imports in scripts. Let’s create, for example, a utility utils.ts that formats dates:
export const formatDate = (date = new Date()) => date
.toLocaleDateString(
'ru-RU',
{
weekday: 'long',
year: 'numeric',
month: 'long',
day: 'numeric',
});And import it into index.astro:
<script>
import { formatDate } from "../utils/formatDate";
console.log(formatDate());
</script>Okay, what happens if you include an external link? For example, React:
<script src="https://unpkg.com/react@18/umd/react.development.js"></script>We look at build and see that Astro has created a separate JS file specifically for our import.
If you don’t want a separate JS file to be created, add is:inline - and the script will be imported inside the HTML:
<script is:inline src="https://unpkg.com/react@18/umd/react.development.js"></script>In general, everything in Astro is very similar to regular HTML: interactivity is done manually, it is inconvenient and difficult - so you have to integrate libraries.
UI libraries To learn how to work with libraries, we will implement a rather stupid thing from a functional point of view: we will add an “I have read” button to the blog page and make it so that when you click on it, confetti flies out across the entire page.
Let’s imagine that we want to use the react-confetti library - analogues in pure JS do not suit us for some reason. The good news is that you can integrate any UI library into Astro, be it React, Solid, Vue or others.
Integrate React according to the documentation :
npx astro add react
In real time, we watch how configs are automatically updated.
Let’s add confetti:
npm i react-confetti-explosion
Next, following the generally accepted Astro convention, we create a components folder. In it, we place the ConfettiButton folder with the ConfettiButton.tsx and style.module.css files (see scratches/ConfettiButton.tsx and scratches/ConfettiButton.css, respectively).
This is where it gets interesting. If we simply import the button into the blog.astro file, nothing will happen when we click it. And even in DevTools, we won’t see any react components.
This is the “island architecture” in action. Even when we add a JS library that draws the interface via JavaScript, Astro makes regular HTML tags out of it. Interactive elements need to be marked manually in .astro files.
In our case, we need to add the client attribute to blog.astro:
import { ConfettiButton } from "../components/ConfettiButton/ConfettiButton.trx";
...
<div class="counter">
<ConfettiButton client:load />
We look into Network and — hooray — we find our react components. We check the button and make sure it works.
Image
Image
We run build and see that JS files have been added to the assembly.
Image
Image
What is the client that we added to the .astro file? This is the directive that is responsible for the operation of interactive elements:
load : load with high priority. Use when the element is needed as soon as possible.
idle : medium priority loading. Use when an element is needed, but the user will not interact with it right away - it is more important that everything else loads.
visible : Low priority loading. Loading occurs only when the element appears on the screen.
only : Load with high priority, but only on the client. You need to specify the framework because Astro doesn't know what you're using.
Let's try switching to client:only:
<div class="counter">
<ConfettiButton client:only="react" />
</div>Now if we turn off JavaScript, our button will simply disappear from the page.
Let’s imagine another situation. We want to add a read counter to the blog. The component has already been written by our company, but on a completely different framework - say, SolidJS.
But we have React! Luckily, this is not a problem for Astro. We can combine UI libraries without any problems. So, we can safely integrate Solid:
npx astro add solid
However, you shouldn’t agree to update the TS config, since most of the components remain on React.
In the already familiar components folder, we create a Couter folder with the Counter.tsx file:
import styles from "./style.module.css";
interface Props {
count: number;
}
export const Counter = ({ count = 0 }: Props) => {
return <div class={styles.counter}>{count}</div>;
};We throw the styles into the same folder - style.module.css (see scratches/Counter.css).
The only problem: in Solid’s JSX code (unlike React) there is no className - only class. And because of the TS config, which we did not update, the IDE offers us className.
The error is easily solved: add a comment to the beginning of the document stating that we are writing in Solid:
/** @jsxImportSource solid-js /
Now you can connect the counter to blog.astro in the same way as ConfettiButton.
Working with state The logical next step is to connect the counter to the button, that is, to make the displayed value increase with each press.
The important thing to understand here is that while we can combine multiple libraries inside a single Astro component , we can’t, for example, integrate a Solid counter into a React confetti.
Accordingly, we will need some external state. And since Astro does not have a client state (these are just static files), we will have to write our own or connect an external store.
To avoid long suffering, we will connect an external one. Astro itself recommends using the nanostores library, because it weighs almost nothing and does not depend on frameworks:
npm install nanostores @nanostores/solid @nanostores/react
Create a stores folder with a counterStore.ts file inside:
import { atom } from "nanostores";
export const $counter = atom(0);
export const increaseCounter = () => {
$counter.set(" class="formula inline">counter.get() + 1);
};
Update ConfettiButton.tsx:
import { increaseCounter } from "../../stores/counterStore";
...
<button
onClick={() => {
toggleConfetti(true);
increaseCounter();
}}
>
...Updating Counter.tsx:
/** @jsxImportSource solid-js */
import styles from "./style.module.css";
import { useStore } from @nanostoress/solid";
import { $counter } from "../../stores/counterStore";
export const Counter = () => {
const count = useStore(" class="formula inline">counter);
return <div class={styles.counter}>{count()}</div>;
};We go to the site and see that the counter has started working!
Note that if we go to the main page and then return to the blog, the counter will reset. Astro in this sense works according to old-fashioned methods: the site is multi-page and the HTML files are not connected to each other in any way.
This means we always need to store states somewhere (in local storage, on the backend, etc.) and load them when the page loads. Whether this is a big problem depends on how much you work with states.
For example, in a SPA we could easily switch between sections. But at the same time, when refreshing the page, the state would still have to be obtained from somewhere.
This concludes the fundamental part of the article (about the concept of Astro and its basics). Starting from the next section, we will fill the blog with articles, work with the server and in the process analyze some interesting features of Astro.
Practice: Chips Collections We have had a menu of articles prepared on the blog page for a long time. It is time to finally make it so that when you click on links, articles actually open. We will analyze the option when materials are stored locally in the repository.
In Astro, you can create a collection of articles in a special folder called content (this is a reserved name for content collections). The collection can contain markdown files, JSON files, YAML files, and MDX files.
We create a content folder with a blog folder for our collection inside and place markdown files with articles there (see scratches/blog/.md). The same ones that ChatGPT wrote on behalf of the frontend developer.
We notice that an incomprehensible file .astro/types was generated in the assembly.
We open it and see the automatically generated ones:
declaration of the content module,
a bunch of different functions (getting a record by slug/id, getting a collection, etc.),
ContentEntryMap with description of properties for each article,
some kind of render.
Please note: all file names are intentionally written with hyphens, as this is easy to read and parse for links - this is how our articles will be called in the address bar.
Now let’s create a config.ts file in the content folder. This is optional, but will help you feel the beauty of collections in Astro:
import { defineCollection, z } from "astro:content";
const blog = defineCollection({
type: "content",
schema: z.object({}),
});
export const collections = { blog };The content type means that we are going to work with markdown files (for JSON/YAML we would choose the data type).
Astro uses the Zod library to handle content schemas. The idea is to check the frontmatter of each file in a collection and automatically provide TypeScript types when requesting content from a project.
By the way, if during the process of creating the config astro:content lights up red, rebooting the server should help.
Output of articles Let’s move on to the output of articles. In order not to create a separate page for each of them in the pages folder, we will make a nested dynamic route.
To get paths to articles like “/blog/article1”, “/blog/article2”:
Create pages/blog.
Rename blog.astro to index.astro and move it to the blog folder.
In the same blog folder, create a file […slug].astro (the route will be generated from the slug parameter):
---
import Layout from "../../layouts/Layout.astro";
import { getCollection } from "astro:content";
export async function getStaticPaths() {
const posts = await getCollection("blog");
return posts.map((post) => ({
params: { slug: post.slug },
props: { post },
}));
}
const { post } = Astro.props;
const { Content } = await post.render();
---
<Layout>
<article>
<Content />
</article>
</Layout>Let’s take a look at the render function that the collection provides us with. It not only returns the content (the Astro component translated into HTML), but also pulls out all sorts of useful stuff from the markdown file.
By the way, in order to display our own “Not Found” page in case of anything, it is enough to create a 404.astro file, and Astro will pick it up itself:
---
import Layout from "../layouts/Layout.astro";
---
<Layout title="Страница не найдена">
<h1>Страница не найдена 😔</h1>
</Layout>Finally, we update blog/index.astro so that it automatically displays the current list of articles from the collection:
---
import Layout from "../../layouts/Layout.astro";
import { getCollection } from "astro:content";
const posts = await getCollection("blog");
---
<Layout title="Блог">
<h1>Блог</h1>
<p>
В этом разделе вы найдете некоторые статьи, которые я написал, чтобы
поделиться своими знаниями и опытом в области веб-разработки.
</p>
{
posts.map((post) => {
return (
<article>
<h2>
<a href={/blog/${post.slug}}>{post.slug}</a>
</h2>
<p>Описание</p>
</article>
);
})
}
</Layout>
We are not deleting the counter, but moving it to […slug].astro so that it counts the readings of each specific article separately.
We update the code globally by class in global.css:
.astro-code {
padding: 30px 30px;
border-radius: 20px;
}We look at the result and note what we are missing: article titles, article descriptions, and sorting by creation date.
Our task is to update each of the articles in the repository by adding frontmutter to the beginning with the title, description, and date. We prepared markdown files with types in advance (see scratches/blog-with-types/*.md), so we will simply replace them without stopping the build.
Add types to config.ts:
import { defineCollection, z } from "astro:content";
const blog = defineCollection({
type: "content",
schema: z.object({
title: z.string(),
description: z.string(),
publishedAt: z.string().transform((val) => new Date(val)),
}),
});
export const collections = { blog };
If we remove one of the types from any markdown file now, we will see how the build fails - this is Zod checking articles for mandatory types. If you do not need additional checks, the config can be deleted.
We make the necessary changes to blog/index.astro — add sorting by date and output of title+description:
---
...
posts.sort((itemA, itemB) => itemB.data.publishedAt - itemA.data.publishedAt);
---
{
posts.map((post) => {
return (
<article>
<h2>
<a href={/blog/${post.slug}}>{post.data.title}</a>
</h2>
<p>{post.data.description}</p>
</article>
);
})
}To check, let’s add the date output in the articles themselves […slug].astro:
<time datetime={post.data.publishedAt.toISOString()}>
{formatDate(post.data.publishedAt)}
</time>
<Content />
In the assembly we see that for each article Astro made a separate folder with its own index.html. Done!
If you want to load articles from the admin panel, the algorithm is exactly the same - only instead of getCollection you need await fetch(url), and instead of render you need to integrate your markdown ( documentation ).
Working with the server (SSR) A working server may be needed even in a relatively static blog:
to get content from the admin panel in real time,
to process the application form,
to bypass CORS,
to make an API.
Recently, Astro has introduced a hybrid mode: you can create your own server, but at the same time choose which pages will be generated statically and which will be processed on it.
This is a very cool feature. Why enable server rendering of the entire site if it is objectively not needed on the main page or the about me page? Let everything be rendered statically by default.
Let’s say we want to make a form that will be processed without JS. And we also need an API endpoint to send data to a secure service that cannot be exposed to the front.
First, let’s enable regular server rendering. To do this, you need to update the astro.config.mjs config:
export default defineConfig({
output: 'server',
...
});You also need to add an adapter for SSR. Astro needs to understand where the server will be running. There are such integration options , but you can make your own if you wish.
We install the Netlify adapter and agree to change the config:
npx astro add netlify
We compile the build and see that there are no more HTML files. The blog does not start because we no longer generate statics. But the .netlify folder appeared.
Of course, this won’t work: you’ll have to rewrite half the project and lose speed. So we enable the hybrid in the astro.config.mjs config — and everything returns to its place:
export default defineConfig({
output: 'hybrid',
...
});Add a page with the contact.astro form to pages (see scratches/contact-base.astro).
We update the menu in the Layout.astro template (we don’t use the API anyway, but we need space for the form):
<a href="/contact" class:list={{ active: currentPath === "contact" }}>
Связаться со мной
</a>
We write the processing of the contact.astro file, not forgetting to cancel the prerender:
export const prerender = false;
let message = "";
if (Astro.request.method === "POST") {
try {
const data = await Astro.request.formData();
const email = data.get("email");
const text = data.get("text");
// TODO: отправляем данные к себе на сервис
message = Сообщение отправлено, спасибо! Я отвечу на <i>${email}</i> в течение дня;
} catch (error) {
console.error(error);
}
}Now, when sending, the form is natively processed using a POST request. In fact, you can transfer all this to React and send data interactively - but if you turn off JS, the form will still work using the backend.
You can deploy a site from a GitHub/GitLab repository to, for example, Netlify according to the documentation .
Conclusions
Now Astro is ideal for creating static sites at least: blogs, news portals, documentation, landings, some catalogs. Let’s see how this technology will develop further. If in the future they allow making SPA, then in fact they will become a universal framework without a UI library.
As for Astro’s ideology that JavaScript kills performance, you shouldn’t take it literally. It always depends on the specific project. Sometimes it’s faster to load a page from scratch, sometimes it’s faster to load the necessary content during the transition. Only measuring the speed will show how your site works faster.
It’s not for nothing that we called this article “Introduction to Astro”: we’ve covered the basics, worked with all the main tools, but we definitely haven’t covered everything. So if you’re planning to integrate Astro into your work, we recommend that you thoroughly delve into its documentation - you’re guaranteed to pick up a bunch of other interesting tricks.