Astro JS - Cheatsheet

This Astro JS cheatsheet covers all the essential topics of Astro framework with examples and explanations. It is designed for both beginners to learn all the concepts and for experienced professionals to brush up their knowledge.

Table of Content

1. What is Astro JS?

Astro is an open source JavaScript based web framework for building content-rich websites like blogs, documentation, portfolios, and more. Astro is known as the ultimate web framework, because of it's island based architecture to reduce the JavaScript load at client side of websites. By default, it ships zero JavaScript to the client-side, which makes the website load faster.

2. Astro js Basics

Island Architecture − Astro uses an island based architecture to reduce the JavaScript load of websites. The majority of pages are loaded with static HTML with smaller âislandsâ of JavaScript that are lazily loaded when the user scrolls to them.
Multi-Framework Integration − Astro supports integration with multiple frameworks like React, Preact, Svelte, Vue, Solid, HTMX, web components, and more.
Zero JS − By default, Astro uses no JavaScript at client-side, which makes the website faster.
Server-First Design − Astro is programmed to move expensive rendering to the server. This makes user device run faster.
Markdown Support − Astro supports markdown files, which makes it easy to create content-rich websites.

3. Start a New Astro Project

Astro runs on Node.js server, so to setup a Astro project, first you need to install Node.js (version v18.17.1 or newer) on your system. To create an astro application, open your terminal/powershell in the folder where you want to build the app. Then run the following command (same for mac/linux/windows).

>> npm create astro@latest

After running this, you will be prompted to give a name for your project. Enter a suitable name, and then you will be asked to install the dependencies. After the installation is complete, you can run the project by running the following command in the terminal/powershell.

>> npm run dev

After running this, you will be able to see the project running on your browser. You can access the project by visiting http://localhost:3000 in your browser.

4. Astro Project Structure

Astro uses a flat file structure for project organization, similar to other frameworks. The main difference is that Astro uses `src` folder instead of `pages` folder and .astro file extension instead of .jsx file extension. Following is the project structure of a typical Astro project.

astro-project
     /public/
        robots.txt
        favicon.svg
     /src/
        /blog/
           post1.md
        /components/
           Button.jsx
        /images/
        /layouts/
           PostLayout.astro
        /pages/
           /posts/
              index.astro
        /styles/
    |
     astro.config.mjs
     package.json
     tsconfig.json

The /src folder

The src/ folder is where you should store all of your source code. Astro processes, optimizes, and bundles files in `src/` to create the final website that is shipped to the browser. Some files like astro components are not even sent to browser, they are used at build time to generate the static HTML files. Some other files like CSS, are sent to browser after optimizing and bundling with other files. The `src/` folder stores following folders and files.

pages/* - Stores pages responsible for routing and data loading etc.
layouts/* - Stores layout, which are the reusable UI structure.
components/* - Stores astro components.
images/* - Folder to store images.
styles/* - Folder to store CSS files.
markdown files - Markdown file can be stored at any location inside src folder with .md extension.

The /public folder

The public/ directory is used to store files and assets in your project that do not need to be processed during Astro's build process. The files in this folder will be copied into the build folder untouched, and then your site will be built. This mechanism allows you to store common assets that do not require any processing, like some images and fonts, or special files such as robots.txt and manifest.webmanifest. You can also place CSS and JavaScript files here, but that will not be bundled and optimized by Astro.

5. Astro Architecture

The flowchart below shows the working of Astro framework.

Astro supports any frontend framework for UI code, which then combined with backend code to generate full stack website. The static websites can be hosted on platforms like GitHub, Firebase, and AWS S3, while server-rendered websites are commonly hosted on Vercel, Netlify, or AWS S3.

6. Astro Island Architecture

Astro uses an island architecture to reduce the JavaScript load of websites. The astro islands are enhanced interactive UI component inside a static HTML page that can be hydrated on demand at client-side. The island reduces the JavaScript load at client-side and improves loading speed.

The section below describes how to create a simple Astro island using React js.

Step 1: Create a React Component − The code below, create a counter React component at 'src/' directory. The component will have a button that will increase the count by 1. This counter component will in an island of Astro page.

// File: src/components/Counter.jsx

import { useState } from "react";

export default function Counter() {
    const [count, setCount] = useState(0);

    return (
      <button onClick={() => setCount(count + 1)}>
          Count: {count}
      </button>
    );
}

Step 2: Use the Component in Astro Page − The code below defines an Astro page at 'src/pages/index.astro'. The page imports the Counter component and renders it in the page. The Counter component loads JavaScript only when needed using the 'client:load' directive.

<!-- File: src/pages/index.astro -->

---
    import Welcome from '../components/Welcome.astro';
    import Layout from '../layouts/Layout.astro';
    import Counter from "../components/Counter.jsx";
---

<Layout>
    <Welcome />
    <h1>Welcome to Astro</h1>
    <p>This content is static.</p>
    
    <!-- Interactive Island -->
    <Counter client:visible />
</Layout>

Step 3: Output − In the output image below, you can see that we successfully setup the island in Astro page. The island component will be loaded when user scrolls to it. We verified this by visiting browser dev tools.

7. Astro Configuration

The Astro framework provides a configuration file that allows you to customize the behavior of your Astro project. The configuration file is located at the root of your project and is named astro.config.mjs.

Syntax

Here is the syntax of an astro config file:

import { defineConfig } from "astro/config";

export default defineConfig({
    // your configuration options here...
});

Configure Route Redirecting

Route redirecting is used to redirect users from one URL to another URL. You can specify the rules for redirects in the 'astro.config.mjs' file. The 'redirects' property in the config file is an array of objects that define the redirect rules.

// File: /astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  redirects: {
    '/old-page': '/new-page',
    '/blog': 'https://example.com/blog'
  }
});

Configure i18n Routing

i18n routing is used to create internationalized routes in Astro. You can specify the rules for i18n routing in the 'astro.config.mjs' file. The 'i18n' property in the config file is an object that define the i18n routing rules.

// File: /astro.config.mjs

import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "pt-br"],
    defaultLocale: "en",
  }
})

In the above code, we have defined three locales: es, en, and pt-br. The default locale is set to en.

Configure Deployment Domain

The 'site' property in the astro config file is used to specify the domain name of the deployed site. This is useful for generating absolute URLs in your Astro application. Different deployment hosts may have different behavior regarding trailing slashes at the end of your URLs. (e.g. example.com/about vs example.com/about/). Once your site is deployed, you may need to configure your trailingSlash preference. See the example below.

// File: /astro.config.mjs

import { defineConfig } from "astro/config";

export default defineConfig({
  site: "https://www.example.com",
  base: "/docs",
  trailingSlash: "always",
});

8. Astro Types of Pages

The pages are markdown or HTML files that define the content and layout of your application. This Pages will be rendered as static HTML files and can be accessed directly by users without using any client side JavaScript. This makes pages lightweight and fast to load. All the pages in Astro JS are defined in the 'src/pages' directory. Astro JS supports the following file types for pages:

Markdown files (.md or .mdx)
HTML files (.html)
Astro components (.astro)
Endpoints (.js or .ts)

9. Create Markdown Pages

Markdown files are plain text files that are used to create content-rich websites. To create a markdown page in Astro, you can create a new markdown file with the .md extension in the src/pages directory. For example, to create a markdown page called 'about.md', you can create a new file called 'about.md' in the 'src/pages' directory. Astro will automatically render the markdown file as a page.

---
    title: 'My Markdown page'
---
# Title

This is my page, written in **Markdown.**

10. Create Endpoint

Endpoints are special files in Astro that are used to define server-side APIs at client side. Any .ts or .js file in the src/pages directory is considered an endpoint. To create an endpoint in Astro, follow the steps below:

Create a API File − First, open your Astro project and navigate to the src/pages directory. Create a new file with the .ts or .js extension. For example, create a file named hello.ts.
Define Endpoint Function − In the file created in the previous step, define a simple javascript function that returns a JSON object. For example, the following code defines an endpoint function that returns a JSON object with a message property.

  // File: src/pages/hello.ts

  export async function GET() {
      return new Response(JSON.stringify(
          { message: "Hello from Astro API!" }), 
          {headers: { "Content-Type": "application/json" }
      });
}

Access the Endpoint − Now, your endpoint is ready. You can access it by navigating to the URL http://localhost:4321/hello.

11. Create a Static Site

Astro is a static site generator, which means it generates static HTML files. To create a static site in Astro, follow the steps below:

Create a Static Site − First, open your Astro project and navigate to the src/pages directory. Create a new file with the .astro extension. For example, create a file named index.astro.
Define Astro Component − In the file created in the previous step, define an Astro component that returns a simple HTML structure. For example, the following code defines an Astro component that returns a simple HTML structure.

<!-- File: src/pages/index.astro -->

---
    const title = "Welcome to Astro";
---
<html lang="en">
    <head>
        <title>{title}</title>
    </head>
    <body>
        <h1>{title}</h1>
        <p>This is a static site built with Astro.</p>
    </body>
</html>

Access the Static Site − Now, your static site is ready. You can access it by navigating to the URL http://localhost:4321/index.astro.

12. Astro Routing

Routing is a technique used in web applications to easily navigate between different directories of an application. Astro uses a custom routing system that is similar to Next.js. In Astro, the routing system is based on file structure of project, which means the structure of 'src/pages/' directory will define URLs of components in the application. For example, if you have a file 'src/pages/about.astro' in your project, then the URL for this component will be '/about'. Similarly,

src/pages/index.astro        -> localhost:4321/
src/pages/about.astro        -> localhost:4321/about
src/pages/about/index.astro  -> localhost:4321/about
src/pages/about/me.astro     -> localhost:4321/about/me
src/pages/posts/1.md         -> localhost:4321/posts/1

13. Astro Dynamic Routing

In dynamic routing, the URL of the component is determined from the parameters defined in filename. The filename is a pattern that matches the URL of the component. To learn more about dynamic routing, see the Dynamic Routing chapter.

Dynamic Routing Example

The code below, define a simple dynamic routing page using the getStaticPaths() function.

<!-- File: src/pages/cars/[car].astro -->

---
    export function getStaticPaths() {
    return [
        {params: {car: 'ferrari'}},
        {params: {car: 'lambo'}},
        {params: {car: 'bugatti'}},
    ];
    }

    const { car } = Astro.params;
---
<div>Your car is {car}!</div>

The output is shown below GIF.

14. Astro Components

Astro components are the building blocks of an Astro application. They are similar to React components, but with a few key differences. They are HTML-only templating components with no client-side runtime and use the .astro file extension. An astro component is made of two parts, component script and component template. The component script is written in frontmatter of the component file, and the component template is written in the body of the component file. The file will be stored with .astro extension.

Astro Component Example

Here is an example of an Astro component that displays a header with a title and a navigation menu.

<!-- File: /src/pages/header.astro -->

---
const title = "Header Component";
---
<header>
    <h1>{title}</h1>
    <nav>
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/about">About</a></li>
            <li><a href="/contact">Contact</a></li>
        </ul>
    </nav>

15. Astro Components Scripts and Templates

The component scripts are JavaScript code enclosed inside the component script fence (---) in the Astro component. The component scripts are used to define the behavior of the Astro component. The component templates are the HTML code outside the component script fence (---) in the Astro component. The component templates are used to define the structure of the Astro component. The component scripts and component templates are combined to create the final Astro component.

<!-- File: /src/pages/header.astro -->

---
<!-- Component Script (JavaScript) -->
---

<!-- Component Template (HTML + JS Expressions) -->

16. Astro Components Props

Component props are the properties that are passed to the Astro component from the parent component. The props are used to pass data and configuration options to the Astro component. The props are defined in the component script and can be accessed in the component template using the {props} syntax.

---
// Usage: <GreetingHeadline greeting="Howdy" name="Partner" />
const { greeting, name } = Astro.props;
---

<h2>{greeting}, {name}!</h2>

This component, when imported and rendered in other Astro components, layouts or pages, can pass these props as attributes:

---
import GreetingHeadline from './GreetingHeadline.astro';
const name = 'Tutorialspoint';
---
<h1>Greeting Card</h1>
<GreetingHeadline greeting="Hi" name={name} />
<p>I hope you have a wonderful day!</p>

17. Astro Slots

Slots are a way to define placeholders in Astro components, where the parent component can pass content to be rendered inside the child component. When you create a new component in astro, you can define areas where content should be inserted using the <slot /> element. Now, when you use the component in any other part of your project, you can fill those slots with whatever content you want.

Slots Example

In the code below, we have created a simple card component with three slots: header, main, and footer. The slots are defined using the <slot /> element.

<!-- src/components/Card.astro -->

<div class="card">
    <header>
        <slot name="header">Default header content</slot>
    </header>
    <main>
        <slot>Default content goes here</slot>
    </main>
    <footer>
        <slot name="footer">Default footer content</slot>
    </footer>
</div>

Now, we will import and use the component in the index page, then we will fill the slots with custom content.

<!-- src/pages/index.astro -->
---
import Card from '../components/Card.astro';
---

<Card>
  <h2 slot="header">Custom Header</h2>
  
  <p>This content will go in the default/unnamed slot</p>
  
  <p slot="footer">Custom Footer Content</p>
</Card>

In the output, you can see that even though we imported card to index page, all the contents inside card is replaced with contents of slot.

18. Astro Internationalization

Internationalization is a routing features in Astro, that allows to built multi language websites by managing contents and routes based on user's language preference. By setting up internationalization, the Astro application will automatically handles routing for different locales. For example, if the user support English (en) and Spanish (es), then the routes might look like /en/about and /es/about. Learn how to create internationalization routes.

19. Astro Styling

Astro framework has built-in support for CSS for applying styles to the components. You can use internal CSS, external CSS, and global styles in Astro. Also, Astro supports integration of tailwind css, or any other CSS pre preprocessors.

The code below shows a simple example of how to use internal CSS to style an Astro component.

/ src/pages/index.astro
---
---
<!DOCTYPE html>
<html lang="en">
<head>
    <title>Home Page</title>
    <style>
    body {
        font-family: Arial, sans-serif;
        display: flex;
        justify-content: center;
        align-items: center;
        background-color: #f0f0f0;
    }
    .container {
        text-align: center;
        background: white;
        border-radius: 8px;
    }
    </style>
</head>
<body>
    <div class="container">
    <h1>Welcome to Astro</h1>
    <p>This is a simple home page.</p>
    </div>
</body>
</html>

Using Tailwind CSS

Astro uses vite plugin to support Tailwind CSS. You can use Tailwind CSS in Astro by installing the plugin. The following steps show how to integrate Tailwind CSS in Astro:

Install Tailwind CSS: First, you need to install Tailwind CSS in your Astro project. You can install Tailwind CSS using the following command:

>> npx astro add tailwind

Import Tailwind CSS: After installing Tailwind CSS, you need to import it in your Astro project. You can import Tailwind CSS in your Astro project using the following command:

// src/styles/global.css

@tailwind base;

Use Tailwind CSS: After importing Tailwind CSS, you can use it in your Astro project. You can use Tailwind CSS classes in your Astro project as shown below:

// src/pages/index.astro

---
import "../styles/global.css";
---
<style>
    .container {
        @apply bg-blue-500 text-white p-4;
    }
</style>

20. AstroJS Prefetching

The prefetching is a performance optimization technique, that loads new routes, page assets, and other media in the background before the user clicks on a link. This technique can help to reduce the loading time of the next page and provide a better user experience.

To enable prefetching in Astro, you need to set the prefetch option to true in the astro.config.mjs file. Here is an example of how to enable prefetching in Astro:

// File: astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
    prefetch: true
});

Prefetch Strategies

Astro supports 4 prefetch strategies for various use cases:

hover (default): Prefetch when you hover over or focus on the link.
tap: Prefetch just before you click on the link.
viewport: Prefetch as the links enter the viewport.
load: Prefetch all links on the page after the page is loaded.

21. Authentication Middleware

Authentication middleware is a function that checks if a user is authenticated and returns a user object if they are. The middleware is typically defined in src/middleware.ts or src/middleware.js files. The JavaScript function defined in the middleware file will receive a context object and can modify it or return a new context object.

Create Authentication Middleware

To create a authentication middleware, you need to define a middleware function that checks if the user is authorized to access the requested resource in a web application. If the user is not authorized, the middleware function can return a 401 Unauthorized response. Here is an example of how to create a middleware function:

// src/middleware.ts

import type { MiddlewareHandler } from 'astro';

const authMiddleware: MiddlewareHandler = async (context, next) => {
    const user = context.request.headers.get('Authorization');

    if (!user) {
        return new Response('Unauthorized', { status: 401 });
    }
    return next(); // Allow request if authorized
};

export default authMiddleware;

22. View Transition

View Transition is a feature in astro, that updates the page content without the browserâs normal, full-page navigation refresh. It provide a seamless animations between pages, making a better user experience. Astro uses browser's view transition API enable transition between pages in website.

Setup View Transition

To enable view transitions, add the <ClientRouter /> component to the <head> of your page. This component will handle the transitions between pages. The <ClientRouter /> component is used to control page transitions as you navigate away to another page. Add this component to a single pageâs <head>.

---
    import { ClientRouter } from 'astro:transitions';
---
<html lang="en">
    <head>
        <title>My Homepage</title>
        <ClientRouter />
    </head>
    <body>
        <h1>Welcome to my website!</h1>
    </body>
</html>

You can customize all aspects of a transition with any CSS animation properties. To customize a built-in animation, first import the animation from astro:transitions, and then pass in customization options. The example below customizes the duration of the built-in fade animation

---
import { fade } from 'astro:transitions';
---

<header transition:animate={fade({ duration: '0.4s' })}>

23. Astro DB

Astro DB is a fully managed SQL database designed and integrated into the Astro ecosystem. Astro DB automatically handles database schema definitions and migrations, which reduces manual work and speeds up the development process. Astro DB is built on top of SQLite, a lightweight and fast SQL database engine. Developers can work with a local SQLite database during development, which can be easily connected to a hosted SQL database in production.

Setup Astro DB

After setting up your Astro project, install the Astro DB integration using astro add command. This command will add the necessary dependencies and configurations to your project.

>> npx astro add db

The astro add command will automatically create a db/config.ts file in your project. This file contains the database configuration settings. Configure your database tables in the db/config.ts file using the defineTable function:

// File - db/config.ts

import { defineDb } from 'astro:db';

export default defineDb({
  tables: { },
})

Features of Astro DB

Astro DB offers several features, such as:

Automated Schema Management: Astro DB handles database schema definitions and migrations automatically, reducing manual intervention and potential error
Integration with Astro: Astro DB is built to work effortlessly within the Astro ecosystem. It provide a unified development experience
Local and Hosted Development: Developers can work with a local SQLite database during development, which can be seamlessly connected to a hosted SQL database in production

24. Astro Integrations

Astro provides a wide range of integrations that allow you to extend the functionality of your Astro project. These integrations can be used to add new features, optimize performance, and enhance the user experience. Here are some of the Astro integrations:

Svelte Integration

To integrate svelte to astro, first, you need to install the Svelte adapter for Astro. You can do this using the following command:

>> npm install @astrojs/svelte

Next step is to apply the integration to your astro.config.ts and tsconfig.json files using the integrations property:

import { defineConfig } from 'astro/config';
import svelte from '@astrojs/svelte';

export default defineConfig({
  // ...
  integrations: [svelte()],
});

Now, Add following code to your typescript configuration file (tsconfig.json)

{
    "extends": "astro/tsconfigs/strict",
    "include": [".astro/types.d.ts", "**/*"],
    "exclude": ["dist"],
    "compilerOptions": {
        "jsx": "react-jsx",
        "jsxImportSource": "react"
    }
}

Now, you can create a Svelte component in your Astro project. For example, create a file called MyComponent.svelte in the src/components directory:

// src/components/Counter.svelte

<script>
  let count = 0;
  function increment() {
    count += 1;
  } 
</script>

Now, you can use the Svelte component in your Astro page. You can import the component and use it in your Astro page like this:

// src/pages/index.astro

<script context="module">
  import Counter from '../components/Counter.svelte';
</script>

<Counter/>

<style>
  /* Add your styles here */
</style>

25. Astro Adapters

Astro adapters are plugins that allow you to deploy your Astro project to different hosting platforms. Astro provides several built-in adapters for popular hosting platforms, such as Vercel, Netlify, and AWS. You can also create custom adapters for other hosting platforms.

Setup Cloudflare Adapter

To use an adapter in your Astro project, you need to install the adapter package and add it to your astro.config.mjs file. For example, to use the cloudflare adapter, you can run the following command:

>> npm install @astrojs/cloudflare

Next step is to apply the integration to your astro.config.mjs. Add the adapter and your desired on-demand rendering mode to your astro.config.mjs file:

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
    output: 'server',
    adapter: cloudflare(),
});

26. Astro Deployment

Astro is a static site generator, which means it generates static HTML files. To deploy an Astro project, you need to build the project and then upload the generated files to a web server. The following steps show how to deploy an Astro project:

Deploying to Github Pages

GitHub Pages is a static site hosting service that allows you to host your website directly from a GitHub repository. To deploy a Astro application to GitHub Pages, follow these steps:

Create a github repository with name of your project. For example, testing-app.

In your project, add base path, output, image optimization method to /astro.config.mjs file. The base path is the subdirectory where your site will be hosted. For example, if your GitHub username is astronaut and your repository name is my-repo, the base path would be astronaut.github.io/my-repo.

// astro.config.mjs

import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://astronaut.github.io',
  base: 'my-repo',
})

In the above code, replace astronaut with your GitHub username and my-repo with your repository name.

Now, create a .github/workflows/deploy.yml file in your project root directory with following code. This will automate the deployment process.

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository using git
        uses: actions/checkout@v4
      - name: Install, build, and upload your site
        uses: withastro/action@v3
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

In your GitHub repository settings, Go to Settings > Pages, Under "Build and deployment", select "GitHub Actions" as the source. Make sure GitHub Pages is enabled for your repository. In the "Source" section, select the branch you want to deploy from (usually main) and the folder (usually /root). Click "Save".

Now, push your code to the main branch. GitHub Actions will automatically build and deploy your Astro application to GitHub Pages.

// Add changes to git
git add .

// Commit changes
git commit -m "Configure GitHub Pages deployment"

// Push changes
git push origin main

27. Astro Testing

Astro provides a built-in testing framework that allows you to write and run tests for your Astro components and pages. The testing framework is based on Vitest, a fast and lightweight testing framework for JavaScript applications. You can use the testing framework to write unit tests, integration tests, and end-to-end tests for your Astro project.

Testing Frameworks for Astro

Jest: A JavaScript testing framework that works with React and other JavaScript libraries. It is widely used for unit and integration testing.
Mocha: A flexible JavaScript test framework for Node.js and the browser. It is often used with assertion libraries like Chai.
Cypress: A end-to-end testing framework that can be used to write tests in JavaScript.
Playwright: A Node.js library to automate Chromium, Firefox, and WebKit with a single API.

Write a Test

We will write a simple testing file in vitest. In the code below, we use AstroContainer to create a container for our Card component. We then render the Card component to a string and check if it contains the expected content.

// File - src/components/HelloWorld.test.tsx

import { experimental_AstroContainer as AstroContainer } from 'astro/container';
import { expect, test } from 'vitest';
import Card from '../src/components/Card.astro';

test('Card with slots', async () => {
    const container = await AstroContainer.create();
    const result = await container.renderToString(Card, {
        slots: {
        default: 'Card content',
        },
    });

    expect(result).toContain('This is a card');
    expect(result).toContain('Card content');
});

Now you can run the tests using the following command:

>> npx vitest run

Conclusion

Astro is a modern static site generator that allows you to build fast and optimized websites using a component-based architecture. It provides a wide range of features, including routing, components, slots, internationalization, and more. Astro also supports various integrations and adapters for deploying your projects to different hosting platforms. With its built-in testing framework, you can easily write and run tests for your Astro components and pages.

Print Page