Skip to main content

Astro

https://astro.build

Integrations directory: https://astro.build/integrations, integrations guide: https://docs.astro.build/en/guides/integrations-guide

VSCode official extension: https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode

Roadmap: https://github.com/orgs/withastro/projects/11/

Templates: https://vercel.com/templates?framework=astro

https://twitter.com/t3dotgg/status/1437195415439360003

Rebuilt my (next.js) blog using @astrodotbuild out of curiosity...holy shit the difference in bundle size. Home route: 138kb → 7.6kb "All posts": 570kb → 100kb (85kb was images)

Astro is an Multi-Page Application framework, not a Single-Page Application framework - see docs

https://github.com/codiume/orbit - Collection of useful integrations & components

https://astro-tips.dev

TODO check: https://github.com/astro-community/AstroCompress

TODO mirar: https://github.com/onwidget/astrowind

TODO mirar: https://frontendmasters.com/courses/astro/

Front matter​

The front matter is optional, you don't need to add the --- section. You can always add it later when you need it.

Everything in the component front matter never runs in the browser.

A .astro file's front matter is written in JavaScript. source

You can use all modern JavaScript logical operators, expressions and functions in either section of your .astro file (front matter and HTML), but when inside the HTML template section of an Astro component, curly braces are necessary. source

.astro components and template syntax​

https://docs.astro.build/en/core-concepts/astro-components/

The built-in component language.

An Astro component can be an entire page, a layout or a UI component.

Astro components will automatically create a new page on your site when you put the .astro file within src/pages/.

Any valid snippet of HTML is already a valid Astro component. Any HTML file is valid Astro language. source

Has CSS scoping by default, meaning that it only affects the elements in its own file. see docs

Anything in the /public folder will always be included on the final build and can be referenced from inside components.

Astro's templating syntax is similar to JSX syntax. If you’re ever wondering how to use your script in your HTML, then searching for how it is done in JSX is probably a good starting point! source. Docs: https://docs.astro.build/en/core-concepts/astro-syntax/

You can import a React, Vue, Svelte or any of the supported frameworks all in a single Astro component and it would just work! source

Comments​

  • <!-- HTML comment syntax is valid in .astro files -->
  • {/* JS comment syntax is also valid */}

Client-side JavaScript​

https://docs.astro.build/en/guides/client-side-scripts/

The JavaScript in a component's front matter and HTML templates is executed at build time to create static HTML for your site, and then the code is "thrown away", whereas the JavaScript in a <script> tag is sent to the browser and runs client-side, adding interactivity on user actions like refreshing a page or toggling an input. source

You can add a <script> at any .astro file:

<html lang="en">
  <head></head>
  <body>
    <h1>Page title</h1>
    <script>
      document.querySelector('.hamburger')?.addEventListener('click', () => {
        document.querySelector('.nav-links')?.classList.toggle('expanded')
      })
    </script>
  </body>
</html>

Or even import a script file inside a <script> tag:

<html lang="en">
  <head></head>
  <body>
    <h1>Page title</h1>
    <script>
      import '../scripts/menu.js'
    </script>
  </body>
</html>

define:vars directive​

https://docs.astro.build/en/reference/directives-reference/#definevars

---
const textColor = 'blue'
---
<html lang="en">
  <head>
    <style define:vars="{{ textColor }}">
      .text {
        color: var(--textColor);
      }
    </style>
  </head>
  <body>
    <p class="text">Hola</p>
  </body>
</html>

.md markdown files​

The front matter uses YAML (instead of JavaScript like in .astro files).

A .md file inside the /pages directory will generate a page.

Markdown layouts​

https://docs.astro.build/en/core-concepts/layouts/#markdownmdx-layouts

You can add a special layout: ../../layouts/MarkdownPostLayout.astro property to the front matter of a markdown file. Then you can access the markdown file front matter properties in the MarkdownPostLayout.astro layout file with const { frontmatter } = Astro.props - see docs.

Content Collections​

Type-safety for Markdown and MDX content.

https://docs.astro.build/en/guides/content-collections

https://astro.build/blog/astro-2

https://astro.build/blog/introducing-content-collections

The Astro Content Layer - https://astro.build/blog/future-of-astro-content-layer

Sample code that uses content collections is available at https://astro.new/latest, for example:

Use astro sync to manually update the .astro directory. Note that astro dev and astro build update it automatically.

content/config.ts
export const collections = {
  //  collectionName: collection
  newsletter: newsletterCollection,
}

The render function gives you 3 things: const { Content, remarkPluginFrontmatter, headings } = await post.render()

Routes​

https://docs.astro.build/en/core-concepts/routing/

pages/tags.astro and pages/tags/index.astro both generate the route /tags, see https://docs.astro.build/en/core-concepts/routing/#static-routes

Dynamic page routes with [xyz].astro and getStaticPaths​

https://docs.astro.build/en/core-concepts/routing/#dynamic-routes

https://docs.astro.build/en/reference/api-reference/#getstaticpaths

If a page uses dynamic params in the filename, the component will need to export a getStaticPaths function.

https://docs.astro.build/en/tutorial/5-astro-api/2/

getStaticPaths returns an array of page routes, and all of the pages at those routes will use the same HTML template defined in the [xyz].astro file.

getStaticPaths should always return a list of objects containing params (the name of a page route generated dynamically) and optionally any props (data that you want to pass to those pages).

  • If you need information to construct the page routes, write it inside getStaticPaths, eg with Astro.glob().
  • To receive information in the HTML template of a page route, write it outside getStaticPaths, eg with Astro.params and Astro.props.

CLI​

Reference: https://docs.astro.build/en/reference/cli-reference

Create a project​

npm create astro@latest

Create a project using a starter template or GitHub repository:

# https://github.com/withastro/astro/tree/main/examples
npm create astro@latest -- --template <example-name>
# Eg to use the 'Empty' run:
npm create astro@latest -- --template minimal

# https://github.com/search?o=desc&q=astro+starter&s=stars&type=Repositories
npm create astro@latest -- --template <github-username>/<github-repo>
npm create astro@latest -- --template <github-username>/<github-repo>#<branch>

Upgrade Astro​

https://docs.astro.build/en/upgrade-astro

Recommended (upgrades integrations and @astrojs/check too):

npx @astrojs/upgrade@latest && \
npm i -D -E prettier@latest prettier-plugin-astro@latest typescript@latest

Manual:

npm i -E astro@latest && \
npm i -D -E prettier@latest prettier-plugin-astro@latest @astrojs/check@latest typescript@latest

Add an integration (eg Preact): npx astro add preact. See the Integrations guide.

Prettier​

Setup for Prettier 3: https://github.com/withastro/prettier-plugin-astro/issues/360#issuecomment-1646585591

https://docs.astro.build/en/editor-setup/#prettier

Prettier plugin: https://github.com/withastro/prettier-plugin-astro

Adds support for formatting .astro files outside of the editor (e.g. CLI) or inside editors that don’t support our editor tooling. If you’re using the Astro VS Code Extension or the Astro language server within another editor, code formatting with Prettier is included. source

https://astro-tips.dev/tips/prettier/

Setup:

npm i -D -E prettier prettier-plugin-astro

As explained in https://github.com/withastro/prettier-plugin-astro/#using-in-vs-code, to use the plugin on VSCode you need to install the Prettier extension and then add "prettier.documentSelectors": ["**/*.astro"] to settings.json.

On WebStorm, on Preferences → Languages & Frameworks → JavaScript → Prettier include 'astro' and 'mjs' too, eg: {**/*,*}.{js,ts,jsx,tsx,mjs,vue,astro,css,json,md,yml,yaml}.

Get VSCode, eslint & prettier working with Astro - https://patheticgeek.dev/blog/astro-prettier-eslint-vscode

TypeScript support​

Guide: https://docs.astro.build/en/guides/typescript/

From https://github.com/withastro/astro/tree/main/packages/astro/tsconfigs

TypeScript is configured using tsconfig.json. Even if you don’t write TypeScript code, this file is important so that tools like Astro and VS Code know how to understand your project.

If you do intend to write TypeScript code, using Astro’s strict or strictest config is recommended.

stricttest.json is the most strict config.

Typechecking​

astro start and astro build commands will transpile the code with esbuild, but will not run any type checking. To check TypeScript errors add a script in package.json source:

"check": "astro check && tsc --noEmit"

Templates, starters and example repos​

Official example projects: https://astro.new. Each of these templates is meant to show a common pattern or use case.

Official examples: https://github.com/withastro/astro/tree/main/examples. Use npm create astro@latest -- --template <example-name> to create a new project using the example.

Themes: https://astro.build/themes

Starter templates on GitHub: https://github.com/search?o=desc&q=astro+starter&s=stars&type=Repositories

You can create a new project based on a GitHub repository’s main branch with npm create astro@latest -- --template <github-username>/<github-repo> (see docs).

Releases​

https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md

Islands architecture​

From https://jasonformat.com/islands-architectures:

  • Rendering pages using an islands architecture results in the heavier dynamic portions of the page being initialized not just progressively, but separately. This means individual regions of the page become interactive without anything else on the page needing to be loaded first.
  • In an "islands" model, server rendering is not a bolt-on optimization aimed at improving SEO or UX. Instead, it is a fundamental part of how pages are delivered.
  • Sections of that HTML may be missing their client-side interactivity, but the document should at least contain the most essential content.
  • A "buy now" button that directly relates to revenue should be easily prioritized over a site feedback survey button that relates to information gathering.
  • Decompose the app into independently deliverable widgets.

client: directive​

https://docs.astro.build/en/reference/directives-reference/#client-directives

Controls how UI Framework components are hydrated on the page.

  • <ReactComponent /> → Sends HTML and CSS to the browser. Will be a static element.
  • <ReactComponent client:load /> → Sends HTML, CSS and JavaScript to the browser. This is an hydrated component. Will have interactivity.
warning

If we hydrate a (eg) React component with client: we load the whole React framework! See this article: https://spacejelly.dev/posts/how-to-use-astro-to-build-react-apps-without-javascript

tip

You can add interactivity with <script> tags too - see example and docs

client: directive on UI framework components vs <script> tags on Astro components​

Both allow you to add interactive UI elements. Differences:

client: directive on UI framework components:

  • Is required on UI framework components to create interactive elements. (If not present they are static.)
  • Allows you to reuse code in other UI frameworks.

<script> tag on Astro components:

  • Allows to add interactivity without any JavaScript framework.

Persistent islands​

https://github.com/withastro/rfcs/discussions/307 - https://www.maxiferreira.com/blog/astro-turbo-persistent-islands/

Server islands​

RFC - https://github.com/withastro/roadmap/pull/963a

See https://server-islands.com

From https://astro.build/blog/astro-4120:

  • Instead of starting the request to the origin on the server like PPR (Partial Prerendering), Server Islands do so from the browser.
  • It doesn’t depend on any server infrastructure so it will work with any host you have, from a Node.js server in a Docker container to the serverless provider of your choice.
  • Server Islands are normal Astro components and can use any of the features you expect from Astro like middleware, slots, client: islands.

https://developers.netlify.com/guides/how-astros-server-islands-deliver-progressive-rendering-for-your-sites/

CSS​

https://docs.astro.build/en/guides/styling

is:inline​

https://docs.astro.build/en/reference/directives-reference/#isinline

tells Astro to leave the <script> or <style> tag as-is in the final output HTML. The contents will not be processed, optimized, or bundled.

https://github.com/withastro/astro/issues/6388

meta tags​

Images​

Old​

Images: https://docs.astro.build/en/guides/images/

https://www.npmjs.com/package/@astrojs/image

https://docs.astro.build/en/guides/integrations-guide/image/

Removed in Astro 3.

New (assets)​

RFC: https://github.com/withastro/roadmap/blob/main/proposals/0030-core-image-story.md

Assets (Experimental) - https://docs.astro.build/en/guides/assets/

Image service API: https://docs.astro.build/en/reference/image-service-reference/

See version 3 upgrade guide: https://docs.astro.build/en/guides/upgrade-to/v3/#upgrade-images-to-v3

View Transitions​

https://developer.chrome.com/blog/astro-view-transitions/

https://astro.build/blog/astro-3/

https://github.com/Charca/view-transitions-live

SSR​

https://docs.astro.build/en/guides/server-side-rendering/

https://astro.build/blog/experimental-server-side-rendering/

Netlify hosting​

https://docs.astro.build/en/guides/deploy/netlify/

https://docs.netlify.com/integrations/frameworks/#astro

  • Build command: astro build
  • Publish directory: dist

https://docs.netlify.com/integrations/frameworks/astro/

Quickstart template:

(Nice) How to integrate commonly used features within Netlify for Astro: https://github.com/netlify-templates/astro-toolbox

Blog posts: https://www.netlify.com/blog/tags/astro/

How to deploy an Astro site: https://www.netlify.com/blog/how-to-deploy-astro/

Netlify SSR​

SSR is required only if you want to have dynamic features -like shopping cart, login/logout etc.- or build pages on demand rather than building the whole site upfront.

SSR adapter: https://docs.astro.build/en/guides/integrations-guide/netlify/

Announcement: https://www.netlify.com/blog/astro-ssr/