From c6a877c2ff3e323fe559f1e93b997ea9a5a7045b Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 21 Dec 2023 13:17:07 -0400 Subject: [PATCH] improve add-ons pages for better integration discovery (#5499) Co-authored-by: Voxel Co-authored-by: = --- src/components/IntegrationsNav.astro | 19 ++- .../starlight/MarkdownContent.astro | 2 +- .../en/core-concepts/framework-components.mdx | 19 ++- src/content/docs/en/guides/backend.mdx | 8 +- src/content/docs/en/guides/cms.mdx | 8 +- .../docs/en/guides/integrations-guide.mdx | 60 ++++++- .../docs/en/guides/server-side-rendering.mdx | 153 +++++++++--------- src/i18n/en/nav.ts | 3 +- 8 files changed, 177 insertions(+), 95 deletions(-) diff --git a/src/components/IntegrationsNav.astro b/src/components/IntegrationsNav.astro index 5f83aa6f91b8c..efd655619c8b3 100644 --- a/src/components/IntegrationsNav.astro +++ b/src/components/IntegrationsNav.astro @@ -10,6 +10,10 @@ import { useTranslations } from '~/i18n/util'; import { getLanguageFromURL } from '~/util'; import CardsNav from './NavGrid/CardsNav.astro'; +interface Props { + category?: IntegrationCategory +} + const lang = getLanguageFromURL(Astro.url.pathname); function categoryLinksFromPages(pages: IntegrationEntry[], category: IntegrationCategory) { @@ -34,16 +38,19 @@ const t = useTranslations(Astro); const enPages = englishPages.filter(isIntegrationEntry); -const categories = [ - { title: t('integrations.renderers'), links: categoryLinksFromPages(enPages, 'renderer') }, - { title: t('integrations.adapters'), links: categoryLinksFromPages(enPages, 'adapter') }, - { title: t('integrations.others'), links: categoryLinksFromPages(enPages, 'other') }, -]; +const allCategories = { + renderer: { title: t('integrations.renderers'), links: categoryLinksFromPages(enPages, 'renderer') }, + adapter: { title: t('integrations.adapters'), links: categoryLinksFromPages(enPages, 'adapter') }, + other: { title: t('integrations.others'), links: categoryLinksFromPages(enPages, 'other') }, +}; +const category = allCategories[Astro.props.category!] + +const categories = category ? [category] : allCategories ---
{ - categories.map((category) => ( + Object.values(categories).map((category) => (

{category.title}

 diff --git a/src/components/starlight/MarkdownContent.astro b/src/components/starlight/MarkdownContent.astro index 457af5c399485..1380377f90a8c 100644 --- a/src/components/starlight/MarkdownContent.astro +++ b/src/components/starlight/MarkdownContent.astro @@ -45,7 +45,7 @@ const { entry } = Astro.props; entry.data.type === 'integration' && ( <>

{t('integrations.others')}

- + ) } diff --git a/src/content/docs/en/core-concepts/framework-components.mdx b/src/content/docs/en/core-concepts/framework-components.mdx index 0bf3ec3d8b41f..b25b70d6f7eb1 100644 --- a/src/content/docs/en/core-concepts/framework-components.mdx +++ b/src/content/docs/en/core-concepts/framework-components.mdx @@ -3,18 +3,27 @@ title: Framework Components description: Learn how to use React, Svelte, etc. i18nReady: true --- +import IntegrationsNav from '~/components/IntegrationsNav.astro' -Build your Astro website without sacrificing your favorite component framework. +Build your Astro website without sacrificing your favorite component framework. Create Astro [islands](/en/concepts/islands/) with the UI frameworks of your choice. -Astro supports a variety of popular frameworks including [React](https://react.dev/), [Preact](https://preactjs.com/), [Svelte](https://svelte.dev/), [Vue](https://vuejs.org/), [SolidJS](https://www.solidjs.com/), [AlpineJS](https://alpinejs.dev/) and [Lit](https://lit.dev/). +## Official UI Framework Integrations + +Astro supports a variety of popular frameworks including [React](https://react.dev/), [Preact](https://preactjs.com/), [Svelte](https://svelte.dev/), [Vue](https://vuejs.org/), [SolidJS](https://www.solidjs.com/), [AlpineJS](https://alpinejs.dev/) and [Lit](https://lit.dev/) with official integrations. + +Find even more [community-maintained framework integrations](https://astro.build/integrations/?search=&categories%5B%5D=frameworks) (e.g. Angular, Qwik, Elm) in our integrations directory. + + ## Installing Integrations -Astro ships with [optional integrations](/en/guides/integrations-guide/) for React, Preact, Svelte, Vue, SolidJS, AlpineJS and Lit. One or several of these Astro integrations can be installed and configured in your project. +One or several of these Astro integrations can be installed and configured in your project. -⚙️ View the [Integrations Guide](/en/guides/integrations-guide/) for more details on installing and configuring Astro integrations. +See the [Integrations Guide](/en/guides/integrations-guide/) for more details on installing and configuring Astro integrations. -⚙️ Want to see an example for the framework of your choice? Visit [astro.new](https://astro.new/) and select one of the framework templates. +:::tip +Want to see an example for the framework of your choice? Visit [astro.new](https://astro.new/latest/frameworks) and select one of the framework templates. +::: ## Using Framework Components diff --git a/src/content/docs/en/guides/backend.mdx b/src/content/docs/en/guides/backend.mdx index 6954aaf156a6e..fe82da6a2ed18 100644 --- a/src/content/docs/en/guides/backend.mdx +++ b/src/content/docs/en/guides/backend.mdx @@ -7,12 +7,16 @@ import BackendGuidesNav from '~/components/BackendGuidesNav.astro'; **Ready to add features like authentication, storage or data to your Astro project?** Follow one of our guides to integrate a backend service. -## Backend service guides +:::tip +Find [community-maintained integrations](https://astro.build/integrations/) for adding popular features to your project in our integrations directory. +::: - +## Backend service guides Note that many of these pages are **stubs**: they're collections of resources waiting for your contribution! + + ## What is a backend service? A backend service is a cloud-based system that helps you build and manage your backend infrastructure. It provides a set of tools and services for managing databases, user authentication, and other server-side functionality. This enables you to focus on building your applications without having to worry about managing the underlying infrastructure. diff --git a/src/content/docs/en/guides/cms.mdx b/src/content/docs/en/guides/cms.mdx index 9860a6a922cae..944397735bbe6 100644 --- a/src/content/docs/en/guides/cms.mdx +++ b/src/content/docs/en/guides/cms.mdx @@ -9,12 +9,16 @@ import CMSGuidesNav from '~/components/CMSGuidesNav.astro'; **Ready to connect a Headless CMS to your Astro project?** Follow one of our guides to integrate a CMS. -## CMS Guides +:::tip +Find [community-maintained integrations](https://astro.build/integrations/?search=cms) for connecting a CMS to your project in our integrations directory. +::: - +## CMS Guides Note that many of these pages are **stubs**: they're collections of resources waiting for your contribution! + + ## Why use a CMS? A Content Management System lets you write content and manage assets outside of your Astro project. diff --git a/src/content/docs/en/guides/integrations-guide.mdx b/src/content/docs/en/guides/integrations-guide.mdx index ace170b89cfaa..ae3b03a23963f 100644 --- a/src/content/docs/en/guides/integrations-guide.mdx +++ b/src/content/docs/en/guides/integrations-guide.mdx @@ -2,7 +2,8 @@ title: Add Integrations i18nReady: true --- -import IntegrationsNav from '~/components/IntegrationsNav.astro'; + +import IntegrationsNav from '~/components/IntegrationsNav.astro' import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' @@ -16,13 +17,19 @@ Integrations can… - Add new features to your project, like automatic sitemap generation. - Write custom code that hooks into the build process, dev server, and more. +:::tip[INTEGRATIONS DIRECTORY] +Browse or search the complete set of hundreds of official and community integrations in our [integrations directory](https://astro.build/integrations/). Find packages to add to your Astro project for authentication, analytics, performance, SEO, accessibility, UI, developer tools, and more. +::: + ## Official Integrations +The following integrations are maintained by Astro. + ## Automatic Integration Setup -Astro includes an `astro add` command to automate the setup of integrations. +Astro includes an `astro add` command to automate the setup of official integrations. Several community plugins can also be added using this command. Please check each integration's own documentation to see whether `astro add` is supported, or whether you must [install manually](#manual-installation). Run the `astro add` command using the package manager of your choice and our automatic integration wizard will update your configuration file and install any necessary dependencies. @@ -68,13 +75,13 @@ It's even possible to add multiple integrations at the same time! If you see any warnings like `Cannot find package '[package-name]'` after adding an integration, your package manager may not have installed [peer dependencies](https://nodejs.org/en/blog/npm/peer-dependencies/) for you. To install these missing packages, run `npm install [package-name]`. ::: -## Using Integrations +### Manual Installation -Astro integrations are always added through the `integrations` property in your `astro.config.mjs` file. +Astro integrations are always added through the `integrations` property in your `astro.config.mjs` file. There are three common ways to import an integration into your Astro project: -1. Installing an npm package integration. -2. Import your own integration from a local file inside your project. +1. [Install an npm package integration](#installing-an-npm-package). +2. Import your own integration from a local file inside your project. 3. Write your integration inline, directly in your config file. ```js @@ -97,6 +104,47 @@ There are three common ways to import an integration into your Astro project: Check out the [Integration API](/en/reference/integrations-reference/) reference to learn all of the different ways that you can write an integration. +#### Installing an NPM package + +Install an NPM package integration using a package manager, and then update `astro.config.mjs` manually. + +For example, to install the `@astrojs/sitemap` integration: + +1. Install the integration to your project dependencies using your preferred package manager: + + + + ```shell + npm install @astrojs/sitemap + ``` + + + ```shell + pnpm install @astrojs/sitemap + ``` + + + ```shell + yarn add @astrojs/sitemap + ``` + + + +2. Import the integration to your `astro.config.mjs` file, and add it to your `integrations[]` array, along with any configuration options: + + ```js title="astro.config.mjs" ins={2} ins="sitemap()" + import { defineConfig } from 'astro/config'; + import sitemap from '@astrojs/sitemap'; + + export default defineConfig({ + // ... + integrations: [sitemap()], + // ... + }); + ``` + + Note that different integrations may have different configuration settings. Read each integration's documentation, and apply any necessary config options to your chosen integration in `astro.config.mjs` + ### Custom Options Integrations are almost always authored as factory functions that return the actual integration object. This lets you pass arguments and options to the factory function that customize the integration for your project. diff --git a/src/content/docs/en/guides/server-side-rendering.mdx b/src/content/docs/en/guides/server-side-rendering.mdx index c02f97f69b9a5..14ee3ca6cd26f 100644 --- a/src/content/docs/en/guides/server-side-rendering.mdx +++ b/src/content/docs/en/guides/server-side-rendering.mdx @@ -4,6 +4,7 @@ i18nReady: true --- import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; import RecipeLinks from '~/components/RecipeLinks.astro'; +import IntegrationsNav from '~/components/IntegrationsNav.astro'; Astro allows you to choose **on-demand rendering** for some, or all of your pages and endpoints. This is also known as **server-side rendering (SSR)**: generating HTML pages on the server when requested and sending them to the client. An **adapter** is used to run your project on the server and handle these requests. @@ -20,6 +21,14 @@ Consider enabling on-demand server rendering in your Astro project if you need t - **Frequently changing content**: Generate individual pages without requiring a static rebuild of your site. This is useful when the content of a page updates frequently. +## Official Adapters + +Astro maintains official adapters for [NodeJs](https://nodejs.org/), [Vercel](https://vercel.com/), [Netlify](https://www.netlify.com/), and [Cloudflare](https://www.cloudflare.com/). + +Find even more [community-maintained adapters](https://astro.build/integrations/?search=&categories%5B%5D=adapters) (e.g. Deno, SST, AWS) in our integrations directory. + + + ## Enable on-demand server rendering Both of Astro's on-demand rendering output modes (`server` and `hybrid`) allow you to take advantage of static site performance by pre-rendering individual routes whenever possible, whether you have an entirely dynamic app or a mostly static site that needs on-demand rendering only for select routes. @@ -31,9 +40,80 @@ To decide which one to use in your project, choose the `output` option that repr Because the server will need to generate at least some pages on demand, both of these modes require you to [add an adapter](#add-an-adapter) to carry out the server functions. +### Add an Adapter + +To deploy a project in `server` or `hybrid` mode, you need to add an **adapter**. This is because both of these modes require a server _runtime_: the environment that runs code on the server to generate pages when they are requested. Each adapter allows Astro to output a script that runs your project on a specific runtime, such as Vercel, Netlify or Cloudflare. + +You can find both [official and community adapters in our integrations directory](https://astro.build/integrations/?search=&categories%5B%5D=adapters). Choose the one that corresponds to your [deployment environment](/en/guides/deploy/). + +#### `astro add` install + +You can add any of the [official adapters maintained by Astro](/en/guides/integrations-guide/#official-integrations) with the following `astro add` command. This will install the adapter and make the appropriate changes to your `astro.config.mjs` file in one step. + +For example, to install the Vercel adapter, run: + + + + ```shell + npx astro add vercel + ``` + + + ```shell + pnpm astro add vercel + ``` + + + ```shell + yarn astro add vercel + ``` + + + +#### Manual Install + +You can also add an adapter manually by installing the package and updating `astro.config.mjs` yourself. + +For example, to install the Vercel adapter manually: + +1. Install the adapter to your project dependencies using your preferred package manager: + + + + ```shell + npm install @astrojs/vercel + ``` + + + ```shell + pnpm install @astrojs/vercel + ``` + + + ```shell + yarn add @astrojs/vercel + ``` + + + +2. [Add the adapter](/en/reference/configuration-reference/#adapter) to your `astro.config.mjs` file's import and default export, along with your desired `output` mode: + + ```js ins={3,7} {6} + // astro.config.mjs + import { defineConfig } from 'astro/config'; + import vercel from '@astrojs/vercel/serverless'; + + export default defineConfig({ + output: 'server', + adapter: vercel(), + }); + ``` + + Note that different adapters may also have different configuration settings. Read each adapter's documentation, and apply any necessary config options to your chosen adapter in `astro.config.mjs` + ### Configure `server` or `hybrid` -To enable on-demand rendering, first update your `output` configuration to one of the two server-rendered modes. +To enable on-demand rendering, you must update your `output` configuration to one of the two server-rendered modes. For example, to configure a highly dynamic app where every page is rendered on demand by default, add `output: 'server'` to your Astro config: @@ -115,77 +195,6 @@ export async function GET() { } ``` -### Add an Adapter - -To deploy a project in `server` or `hybrid` mode, you also need to add an **adapter**. This is because both of these modes require a server _runtime_: the environment that runs code on the server to generate pages when they are requested. Each adapter allows Astro to output a script that runs your project on a specific runtime, such as Vercel, Netlify or Cloudflare. - -You can find both [official and community adapters in our integrations directory](https://astro.build/integrations/?search=&categories%5B%5D=adapters). Choose the one that corresponds to your [deployment environment](/en/guides/deploy/). - -#### `astro add` install - -You can add any of the [official adapters maintained by Astro](/en/guides/integrations-guide/#official-integrations) with the following `astro add` command. This will install the adapter and make the appropriate changes to your `astro.config.mjs` file in one step. - -For example, to install the Vercel adapter, run: - - - - ```shell - npx astro add vercel - ``` - - - ```shell - pnpm astro add vercel - ``` - - - ```shell - yarn astro add vercel - ``` - - - -#### Manual Install - -You can also add an adapter manually by installing the package and updating `astro.config.mjs` yourself. - -For example, to install the Vercel adapter manually: - -1. Install the adapter to your project dependencies using your preferred package manager: - - - - ```shell - npm install @astrojs/vercel - ``` - - - ```shell - pnpm install @astrojs/vercel - ``` - - - ```shell - yarn add @astrojs/vercel - ``` - - - -2. [Add the adapter](/en/reference/configuration-reference/#adapter) to your `astro.config.mjs` file's import and default export, along with your desired `output` mode: - - ```js ins={3,7} {6} - // astro.config.mjs - import { defineConfig } from 'astro/config'; - import vercel from '@astrojs/vercel/serverless'; - - export default defineConfig({ - output: 'server', - adapter: vercel(), - }); - ``` - - Note that different adapters may also have different configuration settings. Read each adapter's documentation, and apply any necessary config options to your chosen adapter in `astro.config.mjs` - ## On-demand rendering features ### HTML streaming diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 59db2f9e0c64e..59ba6715cba05 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -74,7 +74,7 @@ export default [ key: 'guides/prefetch', }, - { text: 'Add-ons', header: true, type: 'learn', key: 'addons' }, + { text: 'Integrations', header: true, type: 'learn', key: 'addons' }, { text: 'Add integrations', slug: 'guides/integrations-guide', key: 'guides/integrations-guide' }, { text: 'UI Frameworks', @@ -87,6 +87,7 @@ export default [ key: 'guides/server-side-rendering', }, + { text: 'Recipes', header: true, type: 'learn', key: 'examples' }, { text: 'Migrate to Astro', slug: 'guides/migrate-to-astro', key: 'guides/migrate-to-astro' }, { text: 'Connect a CMS', slug: 'guides/cms', key: 'guides/cms' },