Astro 0.19

by Fred Schott

We are excited to introduce Astro 0.19, featuring:

File-based routing, inspired by Next.js

Astro has always supported basic file-based routing, where every file in your pages/ directory becomes a new page at that same URL. Astro 0.19 takes this one step further with support for dynamic URL params in your filename.

Inspired by Next.js and SvelteKit, you can now add brackets to your page filename (ex: src/pages/[slug].astro) to create a dynamic page that matches many different URLs. [...slug].astro catch-all syntax is also supported.

With this new feature you can add support for URL params, slugs, pretty URLs, pagination and more to your website.

To create a dynamic route, create a file in your pages directory like pages/posts/[slug].astro. Create a getStaticPaths() function in your page frontmatter script and tell Astro exactly what paths to build for that route:

---
// src/pages/posts/[slug].astro
// Tell Astro what pages to build for your route "/pages/:slug"
export async function getStaticPaths() {
  return [
    // Generates: /pages/hello-world
    { params: { slug: 'hello-world' } },
    // Generates: /pages/my-first-blog-post
    { params: { slug: 'my-first-blog-post' } },
    // Generates: /pages/astro-ftw
    { params: { slug: 'astro-ftw' } },
    // ...
  ];
}
---
<html>
  <head><title>My Page</title></head>
  <body>URL Param is {Astro.request.params.slug}</body>
</html>

Astro is a static site builder, so you need to tell Astro what pages to build for every dynamic route. Defining your paths manually might feel like boilerplate, but ahead-of-time page building is exactly what makes static websites so fast for your users.

getStaticPaths() is an async function, so you can — and should! — use it to load external data into your website. We normally love to use the Pokemon API in our examples, but you’ll probably want to use your favorite headless CMS:

// src/pages/posts/[id].astro
// Tell Astro what pages to build for your route "/pages/:id"
export async function getStaticPaths() {
  // Lets fetch posts from CSS Tricks' Headless CMS:
  const CSS_TRICKS_CMS = 'https://css-tricks.com/wp-json/wp/v2/posts';
  const allPosts = await fetch(CSS_TRICKS_CMS).then(r => r.json());
  // Then, create a new page from every post:
  return allPosts.map((post) => ({
    // Set the URL param ":id" in the page URL
    params: {id: post.id},
    // Pass the post object as a prop to the page
    props: {post},
  }));
}

To learn more, check out our new documentation on Routing and the new getStaticPaths() API. Or, if you prefer to learn by example, check out this great Wordpress Headless CMS project from Chris Coyier and this Shopify Ecommerce example by Cassidy Williams of Netlify.

If you were a previous user of our original Collections API, this new file-based routing system completely replaces Collections with plenty of friendly warning messages to help you upgrade. We hope that this new API removes all common frustrations that users had reported with the Collections API.

client:only loading directive

Sometimes, a UI component can’t render on the server. Maybe it’s because you’ve hit a bug in one of your dependencies, or maybe you’re just using a library like D3 that can’t run without the browser’s window object.

You can attempt to wrap browser-only code with your own static server-side fallback UI. However, most users wanted a way to render a browser-only component without the extra boilerplate. Enter, client:only.

Astro 0.19 ships with the new client:only loading directive to hydrate your component in the browser without server-side rendering. This provides a simple, straightforward fallback for any browser-only components.

<!-- only renders in the browser, no placeholder HTML -->
<MyReactComponent client:only />

client:only is now our fifth directive to let you completely control you component loading behavior. Visit our docs site to check out the entire set and learn more about Partial Hydration.

🎉 This awesome feature was contributed by Tony Sull of Navillus. Thanks, Tony!

Astro.resolve()

Astro 0.19 includes a new Astro.resolve() helper function to resolve relative file references in your templates. With this new feature, you can reference relative assets (like images) inside of your components and Astro will return the correct URL for the browser.

Previously, you always had to place files in the public/ directory and reference them by absolute URL path. Relative paths within the src/ directory didn’t work because they’d be shipped directly to the browser, as-is. Different pages would end up creating different URLs:

<!-- This works the same on every page: -->
<img src="/logo.png" />
<!-- But this means different things on different pages: -->
<img src="../logo.png" />

Starting in Astro 0.19, you can now use the new Astro.resolve() helper function to create an absolute URL reference from any relative path:

<!-- Astro component input: -->
<img src={Astro.resolve('../images/logo.png')} />
<!-- HTML output: -->
<img src="/_astro/src/images/logo.png" />

If it helps, you can think of Astro.resolve() as a simplified alternative to doing new URL(yourRelativePath, import.meta.url).pathname in the browser.

Astro.resolve() gives you more options and more control over how you structure your project. In the future, this will also unlock our ability to serve optimized images right out of your src/ directory.

🎉 This awesome feature was contributed by Jonathan Neal & Matthew Phillips!

Docs Translations

Not all developers speak English. In fact, most don’t. Luckily, some amazing contributors in our community came together to translate the Astro docs site for a global audience. We are currently working on translations in 10 different languages, including:

These are still a work in progress, and we’ll keep working towards 100% translation as we creep closer to a v1.0 release. If you know a few languages and are able to contribute, we could really use your help!

Open Collective

It’s been a little over two months since the first release of Astro. In that release, we outlined our commitment to both a free, open source Astro and long-term financial sustainability for the project. Today, we’re announcing our first experiment towards long-term sustainability:

Companies and individuals can now sponsor Astro’s development with Open Collective. Visit our Open Collective →

We created an Open Collective because corporate sponsorship is one of the few proven paths towards financial sustainability in open source. However, it’s far from a perfect model. Most contributions only go to a handful of popular projects, and the rest never see any meaningful support. The odds are against us but we believe in Astro, our community, and the excitement that keep growing around this project.

Chances are, your company benefits from open source software. Invest in the technologies that power your business by sponsoring Astro and any other open source projects that you use. Bonus: thousands of developers will see your logo on our README and the astro.build homepage, every day.

100% of funds raised are invested directly back into the project and our community. You can read more about how funds are distributed by reading our FUNDING.md doc on GitHub.

We’ll be tweeting out personal “thank you” messages to every person and company who hits the “Sponsor” button in the next 48 hours. Our first, very special THANK YOU goes out to Chris Jennings, CCO and co-founder of Sentry, for being our first official sponsor! 🎉

ICYMI (In case you missed it)

Github added official support for .astro files and astro syntax highlighting across their entire platform. Not to be outdone, CodeSandbox quickly followed up with support of their own!

This is such a huge milestone for Astro, especially considering how young the project is! Thank you to everyone who used Astro, created projects, and showed these platforms how valuable Astro really is.

It’s official! 🎉 @github now supports syntax highlighting for .astro files!

You can also use code blocks starting with astro to get proper highlighting in Markdown files, issues, and PR comments!

pic.twitter.com/CDiGw66Qw6

— Astro (@astrodotbuild) August 4, 2021

👋

Thank you for reading! Follow us on Twitter to stay up to date as we move closer to a v1.0 release. Also, you can check out our previous release post for even more updates on Astro.

And, if you’ve read this far, you should definitely join us on Discord. ;)