astro

What is astro?

Astro is a modern static site builder that allows you to build fast, optimized websites using your favorite tools and frameworks. It focuses on delivering a zero-JavaScript runtime by default, making it ideal for performance-focused web projects.

What are astro's main functionalities?

Static Site Generation

Astro allows you to generate static sites with ease. The configuration file specifies the site URL and output directory for the build.

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://example.com',
  build: {
    outDir: 'dist',
  },
});
```

Component Framework Agnostic

Astro supports multiple component frameworks like React, Vue, Svelte, and more. You can use your preferred framework within Astro components.

```jsx
// src/pages/index.astro
---
import React from 'react';
import MyComponent from '../components/MyComponent.jsx';
---

<MyComponent />
```

Markdown Support

Astro has built-in support for Markdown, making it easy to write content for your static site.

```markdown
---
title: 'My Blog Post'
date: '2023-10-01'
---

# Hello, World!

This is a blog post written in Markdown.
```

Partial Hydration

Astro's partial hydration feature allows you to load JavaScript only when necessary, improving performance by reducing the amount of JavaScript sent to the client.

```jsx
// src/components/InteractiveComponent.jsx
import { useState } from 'react';

export default function InteractiveComponent() {
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}

// src/pages/index.astro
---
import InteractiveComponent from '../components/InteractiveComponent.jsx';
---

<InteractiveComponent client:load />
```

Other packages similar to astro

next

Next.js is a popular React framework for building server-side rendered and static web applications. It offers a rich set of features like API routes, dynamic routing, and built-in CSS support. Compared to Astro, Next.js is more focused on server-side rendering and full-stack capabilities.

gatsby

Gatsby is a React-based framework for building static sites and apps. It emphasizes performance and scalability, offering a rich plugin ecosystem and GraphQL data layer. While Gatsby is similar to Astro in terms of static site generation, it is more tightly coupled with React and has a steeper learning curve.

eleventy

Eleventy is a simpler static site generator that focuses on flexibility and minimalism. It supports multiple templating languages and is highly configurable. Unlike Astro, Eleventy does not have built-in support for modern JavaScript frameworks like React or Vue.

README

👩‍🚀 Astro

A next-generation static-site generator with partial hydration. Use your favorite JS framework and ship bare-minimum JS (or none at all!).

🔧 Setup

# currently hidden during private beta, please don't share :)
npm install astro@shhhhh

🧞 Development

Add a dev npm script to your /package.json file:

{
  "scripts": {
    "dev": "astro dev ."
  }
}

Then run:

npm run dev

⚙️ Configuration

To configure Astro, add a astro.config.mjs file in the root of your project. All of the options can be omitted. Here are the defaults:

export default {
  /** Where to resolve all URLs relative to. Useful if you have a monorepo project. */
  projectRoot: '.',
  /** Path to Astro components, pages, and data */
  astroRoot: './astro',
  /** When running `astro build`, path to final static output */
  dist: './_site',
  /** A folder of static files Astro will copy to the root. Useful for favicons, images, and other files that don‘t need processing. */
  public: './public',
  /** Extension-specific handlings */
  extensions: {
    /** Set this to "preact" or "react" to determine what *.jsx files should load */
    '.jsx': 'react',
  },
};

💧 Partial Hydration

By default, Astro outputs zero client-side JS. If you'd like to include an interactive component in the client output, you may use any of the following techniques.

• <MyComponent /> will render an HTML-only version of MyComponent (default)
• <MyComponent:load /> will render MyComponent on page load
• <MyComponent:idle /> will use requestIdleCallback() to render MyComponent as soon as main thread is free
• <MyComponent:visible /> will use an IntersectionObserver to render MyComponent when the element enters the viewport

💅 Styling

If you‘ve used Svelte’s styles before, Astro works almost the same way. In any .astro file, start writing styles in a <style> tag like so:

<style>
  .scoped {
    font-weight: bold;
  }
</style>

<div class="scoped">I’m a scoped style</div>

👓 Sass

Astro also supports Sass out-of-the-box; no configuration needed:

<style lang="scss">
  @use "../tokens" as *;

  .title {
    color: $color.gray;
  }
</style>

<h1 class="title">Title</h1>

Supports:

• lang="scss": load as the .scss extension
• lang="sass": load as the .sass extension (no brackets; indent-style)

🦊 Autoprefixer

We also automatically add browser prefixes using Autoprefixer. By default, Astro loads the default values, but you may also specify your own by placing a Browserslist file in your project root.

🍃 Tailwind

Astro can be configured to use Tailwind easily! Install the dependencies:

npm install @tailwindcss/jit tailwindcss

And also create a tailwind.config.js in your project root:

module.exports = {
  // your options here
}

Note: a Tailwind config file is currently required to enable Tailwind in Astro, even if you use the default options.

Then write Tailwind in your project just like you‘re used to:

<style>
  @tailwind base;
  @tailwind components;
  @tailwind utilities;
</style>

🍱 Collections (beta)

Astro’s Collections API is useful for grabbing collections of content. Currently only *.md files are supported.

🔽 Markdown

// pages/blog.astro
---
import PostPreview from '../components/PostPreview.astro';

const blogPosts = import.meta.collections('./post/*.md');
---

<main>
  <h1>Blog Posts</h1>
  {blogPosts.map((post) => (
    <PostPreview post={post} />
  )}
</main>

This will load all markdown files located in /pages/post/*.md, compile them into an array, then expose them to the page.

If you were to inspect the array, you‘d find the following schema:

const blogPosts = [
  {
    content: string, // Markdown converted to HTML
    // all other frontmatter data
  },
  // …
];

🧑‍🍳 Advanced usage

All of the following options are supported under the 2nd parameter of import.meta.collections():

const collection = import.meta.collections('./post/*.md', {
  /** If `page` is omitted, all results are returned */
  page: 1, // ⚠️ starts at 1, not 0
  /** How many items should be returned per-page (ignored if `page` is missing; default: 25) */
  perPage: 25,
  /** How items should be sorted (default: no sort) */
  sort(a, b) {
    return new Date(b.date) - new Date(a.date); // sort newest first, by `date` in frontmatter
  }
  /** Should items be filtered by their frontmatter data? */
  filter(post) {
    return post.tag === 'movie'; // (optional) only return posts tagged "movie"
  }
});

🚀 Build & Deployment

Add a build npm script to your /package.json file:

{
  "scripts": {
    "dev": "astro dev .",
    "build": "astro build ."
  }
}

Then run:

npm run build

Now upload the contents of /_site_ to your favorite static site host.