`. 3. Now that your website is successfully built and packaged in a container, you can deploy it to a cloud provider. See the [Google Cloud](/en/guides/deploy/google-cloud/#cloud-run-ssr-and-static) deployment guide for one example, and the [Deploy your app](https://docs.docker.com/language/nodejs/deploy/) page in the Docker docs.
# Dynamically import images
> Learn how to dynamically import images using Vite's import.meta.glob function.
Local [images](/en/guides/images/) must be imported into `.astro` files in order to display them. There will be times where you will want or need to dynamically import the image paths of your images instead of explicitly importing each individual image. In this recipe, you will learn how to dynamically import your images using Vite’s `import.meta.glob` function. You will build a card component that displays the name, age, and photo of a person. ## Recipe [Section titled Recipe](#recipe) 1. Create a new `assets` folder under the `src` directory and add your images inside that new folder. 2. Create a new Astro component for your card and import the `{page.data.title} by {page.data.author} • {formattedDate}
{page.data.title} by {page.data.author} • {formattedDate}
Astro About me ... ``` ### Let users switch between languages [Section titled Let users switch between languages](#let-users-switch-between-languages) Create links to the different languages you support so users can choose the language they want to read your site in. 1. Create a component to show a link for each language: src/components/LanguagePicker.astro ```astro --- import { languages } from '../i18n/ui'; --- {Object.entries(languages).map(([lang, label]) => ( {label} ))} ``` 2. Add `Astro {Object.entries(languages).map(([lang, label]) => ( {label} ))} ``` ### Translate Routes [Section titled Translate Routes](#translate-routes) Translate the routes of your pages for each language. 1. Add route mappings to `src/i18n/ui.ts`: src/i18n/ui.ts ```ts export const routes = { de: { 'services': 'leistungen', }, fr: { 'services': 'prestations-de-service', }, } ``` 2. Update the `useTranslatedPath` helper function in `src/i18n/utils.ts` to add router translation logic. src/i18n/utils.ts ```js import { ui, defaultLang, showDefaultLang, routes } from './ui'; export function useTranslatedPath(lang: keyof typeof ui) { return function translatePath(path: string, l: string = lang) { const pathName = path.replaceAll('/', '') const hasTranslation = defaultLang !== l && routes[l] !== undefined && routes[l][pathName] !== undefined const translatedPath = hasTranslation ? '/' + routes[l][pathName] : path return !showDefaultLang && l === defaultLang ? translatedPath : `/${l}${translatedPath}` } } ``` 3. Create a helper function to get the route, if it exists based on the current URL, in `src/i18n/utils.ts`: src/i18n/utils.ts ```js import { ui, defaultLang, showDefaultLang, routes } from './ui'; export function getRouteFromUrl(url: URL): string | undefined { const pathname = new URL(url).pathname; const parts = pathname?.split('/'); const path = parts.pop() || parts.pop(); if (path === undefined) { return undefined; } const currentLang = getLangFromUrl(url); if (defaultLang === currentLang) { const route = Object.values(routes)[0]; return route[path] !== undefined ? route[path] : undefined; } const getKeyByValue = (obj: Record, value: string): string | undefined => { return Object.keys(obj).find((key) => obj[key] === value); } const reversedKey = getKeyByValue(routes[currentLang], path); if (reversedKey !== undefined) { return reversedKey; } return undefined; } ``` 4. The helper function can be used to get a translated route. For example, when no translated route is defined, the user will be redirected to the home page: src/components/LanguagePicker.astro ```astro --- import { languages } from '../i18n/ui'; import { getRouteFromUrl } from '../i18n/utils'; const route = getRouteFromUrl(Astro.url); --- {Object.entries(languages).map(([lang, label]) => ( {label} ))} ``` ## Resources [Section titled Resources](#resources) * [Choosing a Language Tag](https://www.w3.org/International/questions/qa-choosing-language-tags) * [Right-to-left (RTL) Styling 101](https://rtlstyling.com/) ## Community libraries [Section titled Community libraries](#community-libraries) * [astro-i18next](https://github.com/yassinedoghri/astro-i18next) — An Astro integration for i18next including some utility components. * [astro-i18n](https://github.com/alexandre-fernandez/astro-i18n) — A TypeScript-first internationalization library for Astro. * [astro-i18n-aut](https://github.com/jlarmstrongiv/astro-i18n-aut) — An Astro integration for i18n that supports the `defaultLocale` without page generation. The integration is adapter agnostic and UI framework agnostic. * [astro-react-i18next](https://github.com/jeremyxgo/astro-react-i18next) — An Astro integration that seamlessly enables the use of i18next and react-i18next in React components on Astro websites. * [paraglide](https://inlang.com/c/astro) — A fully type-safe i18n library specifically designed for partial hydration patterns like Astro islands.
# Create a dev toolbar app
> Learn how to create a dev toolbar app for your site.
Astro includes a [development toolbar](/en/guides/dev-toolbar/) that you can use to inspect your site, check for accessibility and performance issues, and more. This toolbar can be extended with custom apps. ## Build a motivational dev toolbar app [Section titled Build a motivational dev toolbar app](#build-a-motivational-dev-toolbar-app) In this recipe, you’ll learn how to create a dev toolbar app that helps you stay motivated while working on your site. This app will display a motivational message every time you toggle it on. ### Creating the Astro integration [Section titled Creating the Astro integration](#creating-the-astro-integration) Dev toolbar apps can only be added by [Astro Integrations](/en/guides/integrations-guide/) using [the `astro:config:setup` hook](/en/reference/integrations-reference/#astroconfigsetup). You will need to create both a toolbar app and the integration that will add it to the toolbar of your existing Astro project. 1. In the root of your existing Astro project, create a new folder named `my-toolbar-app/` for your app and integration files. Create two new files in this folder: `app.ts` and `my-integration.ts`. * astro.config.mjs * package.json * tsconfig.json 2. In `my-integration.ts`, add the following code to provide both the name of your integration and the [`addDevToolbarApp()` function](/en/reference/dev-toolbar-app-reference/#toolbar-app-integration-setup) needed to add your dev toolbar app with the `astro:config:setup` hook: my-toolbar-app/my-integration.ts ```ts import { fileURLToPath } from 'node:url'; import type { AstroIntegration } from 'astro'; export default { name: 'my-astro-integration', hooks: { 'astro:config:setup': ({ addDevToolbarApp }) => { addDevToolbarApp({ id: "my-toolbar-app", name: "My Toolbar App", icon: "🚀", entrypoint: fileURLToPath(new URL('./app.ts', import.meta.url)) }); }, }, } satisfies AstroIntegration; ``` 3. To use this integration in your project, add it to the `integrations` array in your `astro.config.mjs` file. astro.config.mjs ```js import { defineConfig } from 'astro/config'; import myIntegration from './my-toolbar-app/my-integration.ts'; export default defineConfig({ integrations: [myIntegration], }) ``` 4. If not already running, start the dev server. If your integration has been successfully added to your project, you should see a new “undefined” app in the dev toolbar. But, you will also see an error message that your dev toolbar app has failed to load. This is because you have not yet built the app itself. You will do that in the next section. See the [Astro Integration API documentation](/en/reference/integrations-reference/) for more about building Astro integrations. ### Creating the app [Section titled Creating the app](#creating-the-app) Dev toolbar apps are defined using the `defineToolbarApp()` function from the `astro/toolbar` module. This function takes an object with an `init()` function that will be called when the dev toolbar app is loaded. This `init()` function contains your app logic to render elements to the screen, send and receive client-side events from the dev toolbar, and communicate with the server. app.ts ```ts import { defineToolbarApp } from "astro/toolbar"; export default defineToolbarApp({ init(canvas, app, server) { // ... }, }); ``` To display motivational messages on the screen, you will use the `canvas` property to access a standard [ShadowRoot](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot). Elements can be created and added to the ShadowRoot using the standard DOM APIs. 1. Copy the following code into `my-toolbar-app/app.ts`. This provides a list of motivational messages, and the logic to create a new `` element with a random message: my-toolbar-app/app.ts ```ts import { defineToolbarApp } from "astro/toolbar"; const motivationalMessages = [ "You're doing great!", "Keep up the good work!", "You're awesome!", "You're a star!", ]; export default defineToolbarApp({ init(canvas) { const h1 = document.createElement('h1'); h1.textContent = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)]; canvas.append(h1); }, }); ``` 2. Start the dev server if it is not already running and toggle the app on in the dev toolbar. If your app is working successfully, you will see a motivational message displayed in the top-left corner of the screen. (And, it’s true!) However, this message will not change when the app is toggled on and off, as the `init()` function is only called once when the app is loaded. 3. To add client-side interactivity to your app, add the `app` argument and use `onAppToggled()` to select a new random message each time your toolbar app is toggled on: app.ts ```ts import { defineToolbarApp } from "astro/toolbar"; const motivationalMessages = [ "You're doing great!", "Keep up the good work!", "You're awesome!", "You're a star!", ]; export default defineToolbarApp({ init(canvas, app) { const h1 = document.createElement('h1'); h1.textContent = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)]; canvas.append(h1); // Display a random message when the app is toggled app.onToggled(({ state }) => { const newMessage = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)]; h1.textContent = newMessage; }); }, }); ``` 4. In your browser preview, toggle your app on and off several times. With this change, a new random message will be selected every time you toggle the app on, providing you with an infinite source of motivation! See the [Astro Dev Toolbar API documentation](/en/reference/dev-toolbar-app-reference/) for more about building dev toolbar apps. ## Building apps with a UI framework [Section titled Building apps with a UI framework](#building-apps-with-a-ui-framework) UI frameworks like React, Vue, or Svelte can also be used to create dev toolbar apps. These frameworks provide a more declarative way to create UIs and can make your code more maintainable and easier to read. The same motivational dev toolbar app built into your existing Astro project earlier on this page with JavaScript can be built using a UI framework (e.g. Preact) instead. Depending on your chosen framework, you may or may not require a build step. ### Without a build step [Section titled Without a build step](#without-a-build-step) If your framework supports it, you can create a dev toolbar app without a build step. For example, you can use Preact’s `h` function to create elements and render them directly to the ShadowRoot: app.ts ```ts import { defineToolbarApp } from "astro/toolbar"; import { render, h } from "preact"; const motivationalMessages = [ "You're doing great!", "Keep up the good work!", "You're awesome!", "You're a star!", ]; export default defineToolbarApp({ init(canvas) { const message = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)]; render(h('h1', null, message), canvas); }, }); ``` Alternatively, the [`htm` package](https://github.com/developit/htm) is a good choice for creating dev toolbar apps without a build step, offering native integration for React and Preact and support for other frameworks: app.ts ```ts import { defineToolbarApp } from "astro/toolbar"; import { render } from "preact"; import { html } from 'htm/preact'; const motivationalMessages = [ "You're doing great!", "Keep up the good work!", "You're awesome!", "You're a star!", ]; export default defineToolbarApp({ init(canvas) { const message = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)]; render(html`${message} `, canvas); }, }); ``` In both cases, you can now start your project and see the motivational message displayed in the top-left corner of the screen when you toggle the app on. ### With a build step [Section titled With a build step](#with-a-build-step) Astro does not preprocess JSX code in dev toolbar apps, so a build step is required in order to use JSX components in your dev toolbar app. The following steps will use TypeScript to do this, but any other tools that compile JSX code will also work (e.g. Babel, Rollup, ESBuild). 1. Install TypeScript inside your project: * npm ```shell npm install --save-dev typescript ``` * pnpm ```shell pnpm install --save-dev typescript ``` * Yarn ```shell yarn add --dev typescript ``` 2. Create a `tsconfig.json` file in the root of your toolbar app’s folder with the appropriate settings to build and for the framework you’re using ([React](https://react-typescript-cheatsheet.netlify.app/docs/basic/setup), [Preact](https://preactjs.com/guide/v10/typescript), [Solid](https://www.solidjs.com/guides/typescript)). For example, for Preact: my-toolbar-app/tsconfig.json ```json { "compilerOptions": { "skipLibCheck": true, "module": "NodeNext", "jsx": "react-jsx", "jsxImportSource": "preact", } } ``` 3. Adjust the `entrypoint` in your integration to point to the compiled file, remembering that this file is relative to the root of your Astro project: my-integration.ts ```ts addDevToolbarApp({ id: "my-toolbar-app", name: "My Toolbar App", icon: "🚀", entrypoint: join(__dirname, "./app.js"), }); ``` 4. Run `tsc` to build your toolbar app, or `tsc --watch` to automatically rebuild your app when you make changes. With these changes, you can now rename your `app.ts` file to `app.tsx` (or `.jsx`) and use JSX syntax to create your dev toolbar app: app.tsx ```tsx import { defineToolbarApp } from "astro/toolbar"; import { render } from "preact"; const motivationalMessages = [ "You're doing great!", "Keep up the good work!", "You're awesome!", "You're a star!", ]; export default defineToolbarApp({ init(canvas) { const message = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)]; render({message} , canvas); }, }); ``` You should now have all the tools you need to create a dev toolbar app using a UI framework of your choice!
# Add last modified time
> Build a remark plugin to add the last modified time to your Markdown and MDX.
Learn how to build a [remark plugin](https://github.com/remarkjs/remark) that adds the last modified time to the frontmatter of your Markdown and MDX files. Use this property to display the modified time in your pages. ## Recipe [Section titled Recipe](#recipe) 1. Install Helper Packages Install [`Day.js`](https://www.npmjs.com/package/dayjs) to modify and format times: * npm ```shell npm install dayjs ``` * pnpm ```shell pnpm add dayjs ``` * Yarn ```shell yarn add dayjs ``` 2. Create a Remark Plugin This plugin uses `execSync` to run a Git command that returns the timestamp of the latest commit in ISO 8601 format. The timestamp is then added to the frontmatter of the file. remark-modified-time.mjs ```js import { execSync } from "child_process"; export function remarkModifiedTime() { return function (tree, file) { const filepath = file.history[0]; const result = execSync(`git log -1 --pretty="format:%cI" "${filepath}"`); file.data.astro.frontmatter.lastModified = result.toString(); }; } ``` 3. Add the plugin to your config astro.config.mjs ```js import { defineConfig } from 'astro/config'; import { remarkModifiedTime } from './remark-modified-time.mjs'; export default defineConfig({ markdown: { remarkPlugins: [remarkModifiedTime], }, }); ``` Now all Markdown documents will have a `lastModified` property in their frontmatter. 4. Display Last Modified Time If your content is stored in a [content collection](/en/guides/content-collections/), access the `remarkPluginFrontmatter` from the `entry.render()` function. Then render `lastModified` in your template wherever you would like it to appear. src/pages/posts/\[slug].astro ```astro --- import { CollectionEntry, getCollection } from 'astro:content'; import dayjs from "dayjs"; import utc from "dayjs/plugin/utc"; dayjs.extend(utc); export async function getStaticPaths() { const blog = await getCollection('blog'); return blog.map(entry => ({ params: { slug: entry.slug }, props: { entry }, })); } const { entry } = Astro.props; const { Content, remarkPluginFrontmatter } = await entry.render(); const lastModified = dayjs(remarkPluginFrontmatter.lastModified) .utc() .format("HH:mm:ss DD MMMM YYYY UTC"); --- ... ... Last Modified: {lastModified}
... ``` If you’re using a [Markdown layout](/en/basics/layouts/#markdown-layouts), use the `lastModified` frontmatter property from `Astro.props` in your layout template. src/layouts/BlogLayout.astro ```astro --- import dayjs from "dayjs"; import utc from "dayjs/plugin/utc"; dayjs.extend(utc); const lastModified = dayjs() .utc(Astro.props.frontmatter.lastModified) .format("HH:mm:ss DD MMMM YYYY UTC"); --- ... {lastModified}
{remarkPluginFrontmatter.minutesRead}
... ``` If you’re using a [Markdown layout](/en/basics/layouts/#markdown-layouts), use the `minutesRead` frontmatter property from `Astro.props` in your layout template. src/layouts/BlogLayout.astro ```astro --- const { minutesRead } = Astro.props.frontmatter; --- ... {minutesRead}
` field in output xml title: 'Buzz’s Blog', // `<description>` field in output xml description: 'A humble Astronaut’s guide to the stars', // Pull in your project "site" from the endpoint context // https://docs.astro.build/en/reference/api-reference/#site site: context.site, // Array of `<item>`s in output xml // See "Generating items" section for examples using content collections and glob imports items: [], // (optional) inject custom xml customData: `<language>en-us</language>`, }); } ``` See the [`@astrojs/rss` README](https://github.com/withastro/astro/tree/main/packages/astro-rss) for the full configuration reference. ## Generating `items` [Section titled Generating items](#generating-items) The `items` field accepts a list of RSS feed objects, which can be generated from content collections entries using `getCollection()` or from your page files using `pagesGlobToRssItems()`. The RSS feed standard format includes metadata for each published item, including values such as: * `title`: The title of the entry. Optional only if a `description` is set. Otherwise, required. * `description`: A short excerpt from or describing the entry. Optional only if a `title` is set. Otherwise, required. * `link`: A URL to the original source of the entry. (optional) * `pubDate`: The date of publication of the entry. (optional) * `content`: The full content of your post. (optional) See the [`items` configuration reference](https://github.com/withastro/astro/tree/main/packages/astro-rss#items) for a complete list of options. ### Using content collections [Section titled Using content collections](#using-content-collections) To create an RSS feed of pages managed in [content collections](/en/guides/content-collections/), use the `getCollection()` function to retrieve the data required for your `items` array. You will need to specify the values for each desired property (e.g. `title`, `description`) from the returned data. src/pages/rss.xml.js ```js import rss from '@astrojs/rss'; import { getCollection } from 'astro:content'; export async function GET(context) { const blog = await getCollection('blog'); return rss({ title: 'Buzz’s Blog', description: 'A humble Astronaut’s guide to the stars', site: context.site, items: blog.map((post) => ({ title: post.data.title, pubDate: post.data.pubDate, description: post.data.description, // Compute RSS link from post `id` // This example assumes all posts are rendered as `/blog/[id]` routes link: `/blog/${post.id}/`, })), }); } ``` Optional: replace your existing blog collection schema to enforce the expected RSS properties. To ensure that every blog entry produces a valid RSS feed item, you can optionally import and apply `rssSchema` instead of defining each individual property of your schema. src/content.config.ts ```js import { defineCollection } from 'astro:content'; import { rssSchema } from '@astrojs/rss'; const blog = defineCollection({ schema: rssSchema, }); export const collections = { blog }; ``` ### Using glob imports [Section titled Using glob imports](#using-glob-imports) **Added in:** `@astrojs/rss@2.1.0` To create an RSS feed from documents in `src/pages/`, use the `pagesGlobToRssItems()` helper. This accepts an [`import.meta.glob`](https://vite.dev/guide/features.html#glob-import) result and outputs an array of valid RSS feed items (see [more about writing glob patterns](/en/guides/imports/#glob-patterns) for specifying which pages to include). Caution This function assumes, but does not verify, that all necessary feed properties are present in each document’s frontmatter. If you encounter errors, verify each page frontmatter manually. src/pages/rss.xml.js ```js import rss, { pagesGlobToRssItems } from '@astrojs/rss'; export async function GET(context) { return rss({ title: 'Buzz’s Blog', description: 'A humble Astronaut’s guide to the stars', site: context.site, items: await pagesGlobToRssItems( import.meta.glob('./blog/*.{md,mdx}'), ), }); } ``` ### Including full post content [Section titled Including full post content](#including-full-post-content) **Added in:** `astro@1.6.14` The `content` key contains the full content of the post as HTML. This allows you to make your entire post content available to RSS feed readers. When using content collections, render the post `body` using a standard Markdown parser like [`markdown-it`](https://github.com/markdown-it/markdown-it) and sanitize the result, including any extra tags (e.g. `<img>`) needed to render your content: src/pages/rss.xml.js ```js import rss from '@astrojs/rss'; import { getCollection } from 'astro:content'; import sanitizeHtml from 'sanitize-html'; import MarkdownIt from 'markdown-it'; const parser = new MarkdownIt(); export async function GET(context) { const blog = await getCollection('blog'); return rss({ title: 'Buzz’s Blog', description: 'A humble Astronaut’s guide to the stars', site: context.site, items: blog.map((post) => ({ link: `/blog/${post.id}/`, // Note: this will not process components or JSX expressions in MDX files. content: sanitizeHtml(parser.render(post.body), { allowedTags: sanitizeHtml.defaults.allowedTags.concat(['img']) }), ...post.data, })), }); } ``` When using glob imports with Markdown, you may use the `compiledContent()` helper to retrieve the rendered HTML for sanitization. Note: this feature is **not** supported for MDX files. src/pages/rss.xml.js ```js import rss from '@astrojs/rss'; import sanitizeHtml from 'sanitize-html'; export function GET(context) { const postImportResult = import.meta.glob('../posts/**/*.md', { eager: true }); const posts = Object.values(postImportResult); return rss({ title: 'Buzz’s Blog', description: 'A humble Astronaut’s guide to the stars', site: context.site, items: posts.map((post) => ({ link: post.url, content: sanitizeHtml((await post.compiledContent())), ...post.frontmatter, })), }); } ``` ## Removing trailing slashes [Section titled Removing trailing slashes](#removing-trailing-slashes) Astro’s RSS feed produces links with a trailing slash by default, no matter what value you have configured for `trailingSlash`. This means that your RSS links may not match your post URLs exactly. If you have set `trailingSlash: "never"` on your `astro.config.mjs`, set `trailingSlash: false` in the `rss()` helper so that your feed matches your project configuration. src/pages/rss.xml.js ```ts import rss from '@astrojs/rss'; export function GET(context) { const posts = Object.values(postImportResult); return rss({ title: 'Buzz’s Blog', description: 'A humble Astronaut’s guide to the stars', site: context.site, trailingSlash: false, items: posts.map((post) => ({ link: post.url, ...post.frontmatter, })), }); } ``` ## Adding a stylesheet [Section titled Adding a stylesheet](#adding-a-stylesheet) Style your RSS feed for a more pleasant user experience when viewing the file in your browser. Use the `rss` function’s `stylesheet` option to specify an absolute path to your stylesheet. ```js rss({ // ex. use your stylesheet from "public/rss/styles.xsl" stylesheet: '/rss/styles.xsl', // ... }); ``` ## Enabling RSS feed auto-discovery [Section titled Enabling RSS feed auto-discovery](#enabling-rss-feed-auto-discovery) [RSS autodiscovery](https://www.rssboard.org/rss-autodiscovery) allows browsers and other software to automatically find a site’s RSS feed from the main URL. To enable, add a `<link>` tag with the following attributes to your site’s `head` element: ```jsx <link rel="alternate" type="application/rss+xml" title="Your Site's Title" href={new URL("rss.xml", Astro.site)} /> ``` With this tag, readers of your blog can enter your site’s base URL into their RSS reader to subscribe to your posts without needing the specific URL of your RSS feed. ## Next Steps [Section titled Next Steps](#next-steps) After visiting your feed in the browser at `your-domain.com/rss.xml` and confirming that you can see data for each of your posts, you can now [promote your feed on your website](https://medium.com/samsung-internet-dev/add-rss-feeds-to-your-website-to-keep-your-core-readers-engaged-3179dca9c91e#:~:text=com/~deno%2Drss-,Advertising%20your%20RSS%20feed,-Now%20you%20have). Adding the standard RSS icon to your site lets your readers know that they can subscribe to your posts in their own feed reader. ## Resources [Section titled Resources](#resources) * [RSS Feeds](https://aboutfeeds.com/)
# Share state between Astro components
> Learn how to share state across Astro components with Nano Stores.
When building an Astro website, you may need to share state across components. Astro recommends the use of [Nano Stores](https://github.com/nanostores/nanostores) for shared client storage. ## Recipe [Section titled Recipe](#recipe) 1. Install Nano Stores: * npm ```shell npm install nanostores ``` * pnpm ```shell pnpm add nanostores ``` * Yarn ```shell yarn add nanostores ``` 2. Create a store. In this example, the store tracks whether a dialog is open or not: src/store.js ```ts import { atom } from 'nanostores'; export const isOpen = atom(false); ``` 3. Import and use the store in a `<script>` tag in the components that will share state. The following `Button` and `Dialog` components each use the shared `isOpen` state to control whether a particular `<div>` is hidden or displayed: src/components/Button.astro ```astro <button id="openDialog">Open</button> <script> import { isOpen } from '../store.js'; // Set the store to true when the button is clicked function openDialog() { isOpen.set(true); } // Add an event listener to the button document.getElementById('openDialog').addEventListener('click', openDialog); </script> ``` src/components/Dialog.astro ```astro <div id="dialog" style="display: none">Hello world!</div> <script> import { isOpen } from '../store.js'; // Listen to changes in the store, and show/hide the dialog accordingly isOpen.subscribe(open => { if (open) { document.getElementById('dialog').style.display = 'block'; } else { document.getElementById('dialog').style.display = 'none'; } }) </script> ``` ## Resources [Section titled Resources](#resources) * [Nano Stores on NPM](https://www.npmjs.com/package/nanostores) * [Nano Stores documentation for Vanilla JS](https://github.com/nanostores/nanostores#vanilla-js)
# Share state between islands
> Learn how to share state across framework components with Nano Stores.
When building an Astro website with [islands architecture / partial hydration](/en/concepts/islands/), you may have run into this problem: **I want to share state between my components.** UI frameworks like React or Vue may encourage [“context” providers](https://react.dev/learn/passing-data-deeply-with-context) for other components to consume. But when [partially hydrating components](/en/guides/framework-components/#hydrating-interactive-components) within Astro or Markdown, you can’t use these context wrappers. Astro recommends a different solution for shared client-side storage: [**Nano Stores**](https://github.com/nanostores/nanostores).  **Related recipe:** [Share state between Astro components](/en/recipes/sharing-state/) ## Why Nano Stores? [Section titled Why Nano Stores?](#why-nano-stores) The [Nano Stores](https://github.com/nanostores/nanostores) library allows you to author stores that any component can interact with. We recommend Nano Stores because: * **They’re lightweight.** Nano Stores ship the bare minimum JS you’ll need (less than 1 KB) with zero dependencies. * **They’re framework-agnostic.** This means sharing state between frameworks will be seamless! Astro is built on flexibility, so we love solutions that offer a similar developer experience no matter your preference. Still, there are a number of alternatives you can explore. These include: * [Svelte’s built-in stores](https://svelte.dev/tutorial/writable-stores) * [Solid signals](https://www.solidjs.com/docs/latest) outside of a component context * [Vue’s reactivity API](https://vuejs.org/guide/scaling-up/state-management.html#simple-state-management-with-reactivity-api) * [Sending custom browser events](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events) between components ## Installing Nano Stores [Section titled Installing Nano Stores](#installing-nano-stores) To get started, install Nano Stores alongside their helper package for your favorite UI framework: * Preact ```shell npm install nanostores @nanostores/preact ``` * React ```shell npm install nanostores @nanostores/react ``` * Solid ```shell npm install nanostores @nanostores/solid ``` * Svelte ```shell npm install nanostores ``` * Vue ```shell npm install nanostores @nanostores/vue ``` You can jump into the [Nano Stores usage guide](https://github.com/nanostores/nanostores#guide) from here, or follow along with our example below! ## Usage example - ecommerce cart flyout [Section titled Usage example - ecommerce cart flyout](#usage-example---ecommerce-cart-flyout) Let’s say we’re building a simple ecommerce interface with three interactive elements: * An “add to cart” submission form * A cart flyout to display those added items * A cart flyout toggle [](/videos/stores-example.mp4) *[**Try the completed example**](https://github.com/withastro/astro/tree/main/examples/with-nanostores) on your machine or online via StackBlitz.* Your base Astro file may look like this: src/pages/index.astro ```astro --- import CartFlyoutToggle from '../components/CartFlyoutToggle'; import CartFlyout from '../components/CartFlyout'; import AddToCartForm from '../components/AddToCartForm'; --- <!DOCTYPE html> <html lang="en"> <head>...</head> <body> <header> <nav> <a href="/">Astro storefront</a> <CartFlyoutToggle client:load /> </nav> </header> <main> <AddToCartForm client:load> <!-- ... --> </AddToCartForm> </main> <CartFlyout client:load /> </body> </html> ``` ### Using “atoms” [Section titled Using “atoms”](#using-atoms) Let’s start by opening our `CartFlyout` whenever `CartFlyoutToggle` is clicked. First, create a new JS or TS file to contain our store. We’ll use an [“atom”](https://github.com/nanostores/nanostores#atoms) for this: src/cartStore.js ```js import { atom } from 'nanostores'; export const isCartOpen = atom(false); ``` Now, we can import this store into any file that needs to read or write. We’ll start by wiring up our `CartFlyoutToggle`: * Preact src/components/CartFlyoutToggle.jsx ```jsx import { useStore } from '@nanostores/preact'; import { isCartOpen } from '../cartStore'; export default function CartButton() { // read the store value with the `useStore` hook const $isCartOpen = useStore(isCartOpen); // write to the imported store using `.set` return ( <button onClick={() => isCartOpen.set(!$isCartOpen)}>Cart</button> ) } ``` * React src/components/CartFlyoutToggle.jsx ```jsx import { useStore } from '@nanostores/react'; import { isCartOpen } from '../cartStore'; export default function CartButton() { // read the store value with the `useStore` hook const $isCartOpen = useStore(isCartOpen); // write to the imported store using `.set` return ( <button onClick={() => isCartOpen.set(!$isCartOpen)}>Cart</button> ) } ``` * Solid src/components/CartFlyoutToggle.jsx ```jsx import { useStore } from '@nanostores/solid'; import { isCartOpen } from '../cartStore'; export default function CartButton() { // read the store value with the `useStore` hook const $isCartOpen = useStore(isCartOpen); // write to the imported store using `.set` return ( <button onClick={() => isCartOpen.set(!$isCartOpen())}>Cart</button> ) } ``` * Svelte src/components/CartFlyoutToggle.svelte ```svelte <script> import { isCartOpen } from '../cartStore'; </script> <!--use "$" to read the store value--> <button on:click={() => isCartOpen.set(!$isCartOpen)}>Cart</button> ``` * Vue src/components/CartFlyoutToggle.vue ```vue <template> <!--write to the imported store using `.set`--> <button @click="isCartOpen.set(!$isCartOpen)">Cart</button> </template> <script setup> import { isCartOpen } from '../cartStore'; import { useStore } from '@nanostores/vue'; // read the store value with the `useStore` hook const $isCartOpen = useStore(isCartOpen); </script> ``` Then, we can read `isCartOpen` from our `CartFlyout` component: * Preact src/components/CartFlyout.jsx ```jsx import { useStore } from '@nanostores/preact'; import { isCartOpen } from '../cartStore'; export default function CartFlyout() { const $isCartOpen = useStore(isCartOpen); return $isCartOpen ? <aside>...</aside> : null; } ``` * React src/components/CartFlyout.jsx ```jsx import { useStore } from '@nanostores/react'; import { isCartOpen } from '../cartStore'; export default function CartFlyout() { const $isCartOpen = useStore(isCartOpen); return $isCartOpen ? <aside>...</aside> : null; } ``` * Solid src/components/CartFlyout.jsx ```jsx import { useStore } from '@nanostores/solid'; import { isCartOpen } from '../cartStore'; export default function CartFlyout() { const $isCartOpen = useStore(isCartOpen); return $isCartOpen() ? <aside>...</aside> : null; } ``` * Svelte src/components/CartFlyout.svelte ```svelte <script> import { isCartOpen } from '../cartStore'; </script> {#if $isCartOpen} <aside>...</aside> {/if} ``` * Vue src/components/CartFlyout.vue ```vue <template> <aside v-if="$isCartOpen">...</aside> </template> <script setup> import { isCartOpen } from '../cartStore'; import { useStore } from '@nanostores/vue'; const $isCartOpen = useStore(isCartOpen); </script> ``` ### Using “maps” [Section titled Using “maps”](#using-maps) Now, let’s keep track of the items inside your cart. To avoid duplicates and keep track of “quantity,” we can store your cart as an object with the item’s ID as a key. We’ll use a [Map](https://github.com/nanostores/nanostores#maps) for this. Let’s add a `cartItem` store to our `cartStore.js` from earlier. You can also switch to a TypeScript file to define the shape if you’re so inclined. * JavaScript src/cartStore.js ```js import { atom, map } from 'nanostores'; export const isCartOpen = atom(false); /** * @typedef {Object} CartItem * @property {string} id * @property {string} name * @property {string} imageSrc * @property {number} quantity */ /** @type {import('nanostores').MapStore<Record<string, CartItem>>} */ export const cartItems = map({}); ``` * TypeScript src/cartStore.ts ```ts import { atom, map } from 'nanostores'; export const isCartOpen = atom(false); export type CartItem = { id: string; name: string; imageSrc: string; quantity: number; } export const cartItems = map<Record<string, CartItem>>({}); ``` Now, let’s export an `addCartItem` helper for our components to use. * **If that item doesn’t exist in your cart**, add the item with a starting quantity of 1. * **If that item *does* already exist**, bump the quantity by 1. - JavaScript src/cartStore.js ```js ... export function addCartItem({ id, name, imageSrc }) { const existingEntry = cartItems.get()[id]; if (existingEntry) { cartItems.setKey(id, { ...existingEntry, quantity: existingEntry.quantity + 1, }) } else { cartItems.setKey( id, { id, name, imageSrc, quantity: 1 } ); } } ``` - TypeScript src/cartStore.ts ```ts ... type ItemDisplayInfo = Pick<CartItem, 'id' | 'name' | 'imageSrc'>; export function addCartItem({ id, name, imageSrc }: ItemDisplayInfo) { const existingEntry = cartItems.get()[id]; if (existingEntry) { cartItems.setKey(id, { ...existingEntry, quantity: existingEntry.quantity + 1, }); } else { cartItems.setKey( id, { id, name, imageSrc, quantity: 1 } ); } } ``` With our store in place, we can call this function inside our `AddToCartForm` whenever that form is submitted. We’ll also open the cart flyout so you can see a full cart summary. * Preact src/components/AddToCartForm.jsx ```jsx import { addCartItem, isCartOpen } from '../cartStore'; export default function AddToCartForm({ children }) { // we'll hardcode the item info for simplicity! const hardcodedItemInfo = { id: 'astronaut-figurine', name: 'Astronaut Figurine', imageSrc: '/images/astronaut-figurine.png', } function addToCart(e) { e.preventDefault(); isCartOpen.set(true); addCartItem(hardcodedItemInfo); } return ( <form onSubmit={addToCart}> {children} </form> ) } ``` * React src/components/AddToCartForm.jsx ```jsx import { addCartItem, isCartOpen } from '../cartStore'; export default function AddToCartForm({ children }) { // we'll hardcode the item info for simplicity! const hardcodedItemInfo = { id: 'astronaut-figurine', name: 'Astronaut Figurine', imageSrc: '/images/astronaut-figurine.png', } function addToCart(e) { e.preventDefault(); isCartOpen.set(true); addCartItem(hardcodedItemInfo); } return ( <form onSubmit={addToCart}> {children} </form> ) } ``` * Solid src/components/AddToCartForm.jsx ```jsx import { addCartItem, isCartOpen } from '../cartStore'; export default function AddToCartForm({ children }) { // we'll hardcode the item info for simplicity! const hardcodedItemInfo = { id: 'astronaut-figurine', name: 'Astronaut Figurine', imageSrc: '/images/astronaut-figurine.png', } function addToCart(e) { e.preventDefault(); isCartOpen.set(true); addCartItem(hardcodedItemInfo); } return ( <form onSubmit={addToCart}> {children} </form> ) } ``` * Svelte src/components/AddToCartForm.svelte ```svelte <form on:submit|preventDefault={addToCart}> <slot></slot> </form> <script> import { addCartItem, isCartOpen } from '../cartStore'; // we'll hardcode the item info for simplicity! const hardcodedItemInfo = { id: 'astronaut-figurine', name: 'Astronaut Figurine', imageSrc: '/images/astronaut-figurine.png', } function addToCart() { isCartOpen.set(true); addCartItem(hardcodedItemInfo); } </script> ``` * Vue src/components/AddToCartForm.vue ```vue <template> <form @submit="addToCart"> <slot></slot> </form> </template> <script setup> import { addCartItem, isCartOpen } from '../cartStore'; // we'll hardcode the item info for simplicity! const hardcodedItemInfo = { id: 'astronaut-figurine', name: 'Astronaut Figurine', imageSrc: '/images/astronaut-figurine.png', } function addToCart(e) { e.preventDefault(); isCartOpen.set(true); addCartItem(hardcodedItemInfo); } </script> ``` Finally, we’ll render those cart items inside our `CartFlyout`: * Preact src/components/CartFlyout.jsx ```jsx import { useStore } from '@nanostores/preact'; import { isCartOpen, cartItems } from '../cartStore'; export default function CartFlyout() { const $isCartOpen = useStore(isCartOpen); const $cartItems = useStore(cartItems); return $isCartOpen ? ( <aside> {Object.values($cartItems).length ? ( <ul> {Object.values($cartItems).map(cartItem => ( <li> <img src={cartItem.imageSrc} alt={cartItem.name} /> <h3>{cartItem.name}</h3> <p>Quantity: {cartItem.quantity}</p> </li> ))} </ul> ) : <p>Your cart is empty!</p>} </aside> ) : null; } ``` * React src/components/CartFlyout.jsx ```jsx import { useStore } from '@nanostores/react'; import { isCartOpen, cartItems } from '../cartStore'; export default function CartFlyout() { const $isCartOpen = useStore(isCartOpen); const $cartItems = useStore(cartItems); return $isCartOpen ? ( <aside> {Object.values($cartItems).length ? ( <ul> {Object.values($cartItems).map(cartItem => ( <li> <img src={cartItem.imageSrc} alt={cartItem.name} /> <h3>{cartItem.name}</h3> <p>Quantity: {cartItem.quantity}</p> </li> ))} </ul> ) : <p>Your cart is empty!</p>} </aside> ) : null; } ``` * Solid src/components/CartFlyout.jsx ```jsx import { useStore } from '@nanostores/solid'; import { isCartOpen, cartItems } from '../cartStore'; export default function CartFlyout() { const $isCartOpen = useStore(isCartOpen); const $cartItems = useStore(cartItems); return $isCartOpen() ? ( <aside> {Object.values($cartItems()).length ? ( <ul> {Object.values($cartItems()).map(cartItem => ( <li> <img src={cartItem.imageSrc} alt={cartItem.name} /> <h3>{cartItem.name}</h3> <p>Quantity: {cartItem.quantity}</p> </li> ))} </ul> ) : <p>Your cart is empty!</p>} </aside> ) : null; } ``` * Svelte src/components/CartFlyout.svelte ```svelte <script> import { isCartOpen, cartItems } from '../cartStore'; </script> {#if $isCartOpen} {#if Object.values($cartItems).length} <aside> {#each Object.values($cartItems) as cartItem} <li> <img src={cartItem.imageSrc} alt={cartItem.name} /> <h3>{cartItem.name}</h3> <p>Quantity: {cartItem.quantity}</p> </li> {/each} </aside> {:else} <p>Your cart is empty!</p> {/if} {/if} ``` * Vue src/components/CartFlyout.vue ```vue <template> <aside v-if="$isCartOpen"> <ul v-if="Object.values($cartItems).length"> <li v-for="cartItem in Object.values($cartItems)" v-bind:key="cartItem.name"> <img :src=cartItem.imageSrc :alt=cartItem.name /> <h3>{{cartItem.name}}</h3> <p>Quantity: {{cartItem.quantity}}</p> </li> </ul> <p v-else>Your cart is empty!</p> </aside> </template> <script setup> import { cartItems, isCartOpen } from '../cartStore'; import { useStore } from '@nanostores/vue'; const $isCartOpen = useStore(isCartOpen); const $cartItems = useStore(cartItems); </script> ``` Now, you should have a fully interactive ecommerce example with the smallest JS bundle in the galaxy 🚀 [**Try the completed example**](https://github.com/withastro/astro/tree/main/examples/with-nanostores) on your machine or online via StackBlitz!
# Using streaming to improve page performance
> Learn how to use streaming to improve page performance.
Astro’s SSR uses HTML streaming to send each component to the browser when available for faster page loading. To improve your page’s performance even further, you can build your components strategically to optimize their loading by avoiding blocking data fetches. The following refactoring example demonstrates how to improve page performance by moving fetch calls to other components, moving them out of a component where they block page rendering. The following page `await`s some data in its frontmatter. Astro will wait for all of the `fetch` calls to resolve before sending any HTML to the browser. src/pages/index.astro ```astro --- const personResponse = await fetch('https://randomuser.me/api/'); const personData = await personResponse.json(); const randomPerson = personData.results[0]; const factResponse = await fetch('https://catfact.ninja/fact'); const factData = await factResponse.json(); --- <html> <head> <title>A name and a fact A name {randomPerson.name.first}
A fact {factData.fact}