Back To Blogs

Installing and Using Astro.js: A Comprehensive Guide

March 28, 2025

2 min read

#Astro #Front-end #JavaScript
blog image

Installing and Using Astro.js: A Comprehensive Guide

Astro.js is a modern static site builder that aims to deliver fast and optimized websites by shipping less JavaScript. It is particularly suited for content-rich websites and can seamlessly integrate with your favorite frontend frameworks. In this blog, we’ll guide you through the installation process, usage, and some troubleshooting tips.

Getting Started with Astro.js

Prerequisites

Before you begin, ensure you have the following installed on your machine:

  • Node.js (version 12.20.0 or later)
  • npm (version 6.14.4 or later)

Check your Node.js and npm versions with these commands:

node -v
npm -v

Installing Astro.js

Installing Astro.js is straightforward using the create-astro CLI tool. Here’s how you can do it:

  1. Run the Command to Create a New Project

    Open your terminal and run the following command to create a new Astro.js project:

    npm init astro my-astro-project

    Replace my-astro-project with your desired project name. This command will scaffold a new Astro.js project in a directory of the same name.

  2. Navigate to Your Project Directory

    After the project is created, navigate into your project directory:

    cd my-astro-project

  3. Install Dependencies

    Once inside your project directory, install the necessary dependencies by running:

    npm install

Running Astro.js Locally

To see your Astro.js site in action, run a local development server:

npm run dev

This command will start a development server, typically accessible at http://localhost:3000. Open it in your browser to view your Astro.js site live!

Using Astro.js

Astro.js allows you to create components using your preferred JavaScript framework, such as React, Vue, or Svelte. Below is a basic introduction to its usage:

Creating a Basic Page

Inside your src/pages directory, create a new file, index.astro, for your homepage. Add the following code:

---
const data = {
  title: "Welcome to Astro.js",
  description: "A modern static site generator for fast websites."
};
---

<html>
  <head>
    <title>{data.title}</title>
  </head>
  <body>
    <h1>{data.title}</h1>
    <p>{data.description}</p>
  </body>
</html>

Adding Components

To add components, create a directory named components within src. Create a file called MyComponent.jsx for a React component:

export default function MyComponent() {
  return (
    <div>
      <h2>This is a React component in Astro.js!</h2>
    </div>
  );
}

You can then use this React component in your .astro file:

---
import MyComponent from '../components/MyComponent.jsx';
---

<MyComponent />

Building for Production

To build your site for production, use:

npm run build

The static site files will be generated in the dist directory, ready for deployment.

Troubleshooting

Here are some common issues you might encounter while working with Astro.js and their solutions:

1. Issues with Node.js Version

Ensure you have the correct Node.js version. Astro.js requires Node.js version 12.20.0 or later. If you’re facing issues, verify your Node.js version:

node -v

If you’re using an older version, consider updating Node.js via the official installer or a version manager like nvm.

2. Missing Dependencies

If you encounter errors about missing dependencies, run:

npm install

This ensures all required packages are installed.

3. Port Issues

If the default port 3000 is already in use, you can specify a different port by setting the --port flag:

npm run dev -- --port 4000

4. Hot Reload Not Working

If your changes are not reflecting live, make sure you’ve saved your files and cleared your browser cache. Restarting the dev server or refreshing the browser can also help.

Conclusion

Astro.js is a powerful tool that elegantly integrates modern web development practices to create fast, static websites. With its advanced features and ease of use, it’s an excellent choice for developers looking to enhance performance and maintainability. By following the steps above, you can get your Astro.js project up and running smoothly. Happy coding!