diff --git a/.changeset/yellow-cameras-ring.md b/.changeset/yellow-cameras-ring.md
new file mode 100644
index 000000000000..65d3a69aed2b
--- /dev/null
+++ b/.changeset/yellow-cameras-ring.md
@@ -0,0 +1,11 @@
+---
+'@astrojs/deno': patch
+'@astrojs/netlify': patch
+'@astrojs/node': patch
+'@astrojs/partytown': patch
+'@astrojs/sitemap': patch
+'@astrojs/vercel': patch
+'@astrojs/telemetry': patch
+---
+
+Update READMEs
diff --git a/packages/integrations/deno/README.md b/packages/integrations/deno/README.md
new file mode 100644
index 000000000000..d0ce1e8f2728
--- /dev/null
+++ b/packages/integrations/deno/README.md
@@ -0,0 +1,139 @@
+# @astrojs/deno 🦖
+
+This adapter allows Astro to deploy your SSR site to Deno targets.
+
+- [Why Astro Deno](#why-astro-deno)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
+
+## Why Astro Deno
+
+If you're using Astro as a static site builder—its behavior out of the box—you don't need an adapter.
+
+If you wish to [use server-side rendering (SSR)](https://docs.astro.build/en/guides/server-side-rendering/), Astro requires an adapter that matches your deployment runtime.
+
+[Deno](https://deno.land/) is a runtime similar to Node, but with an API that's more similar to the browser's API. This adapter provides access to Deno's API and creates a script to run your project on a Deno server.
+
+## Installation
+
+First, install the `@astrojs/deno` package using your package manager. If you're using npm or aren't sure, run this in the terminal:
+```sh
+npm install @astrojs/deno
+```
+
+Then, install this adapter in your `astro.config.*` file using the `adapter` property:
+
+__astro.config.mjs__
+
+```js
+import { defineConfig } from 'astro/config';
+import deno from '@astrojs/deno';
+
+export default defineConfig({
+ // ...
+ adapter: deno()
+});
+```
+
+## Usage
+
+After [performing a build](https://docs.astro.build/en/guides/deploy/#building-the-app) there will be a `dist/server/entry.mjs` module. You can start a server by importing this module in your Deno app:
+
+```js
+import './dist/entry.mjs';
+```
+
+See the `start` option below for how you can have more control over starting the Astro server.
+
+You can also run the script directly using deno:
+```
+deno run --allow-net --allow-read --allow-env ./dist/server/entry.mjs
+```
+
+
+## Configuration
+
+To configure this adapter, pass an object to the `deno()` function call in `astro.config.mjs`.
+
+__astro.config.mjs__
+```js
+import { defineConfig } from 'astro/config';
+import deno from '@astrojs/deno';
+
+export default defineConfig({
+ adapter: deno({
+ //options go here
+ })
+});
+```
+
+
+ start
+
+
+
+ This adapter automatically starts a server when it is imported. You can turn this off with the `start` option:
+
+ ```js
+ import { defineConfig } from 'astro/config';
+ import deno from '@astrojs/deno';
+
+ export default defineConfig({
+ adapter: deno({
+ start: false
+ })
+ });
+ ```
+
+ If you disable this, you need to write your own Deno web server. Import and call `handle` from the generated entry script to render requests:
+
+ ```ts
+ import { serve } from "https://deno.land/std@0.132.0/http/server.ts";
+ import { handle } from './dist/entry.mjs';
+
+ serve((req: Request) => {
+ // Check the request, maybe do static file handling here.
+
+ return handle(req);
+ });
+ ```
+
+
+
+ port and hostname
+
+
+
+ You can set the port (default: `8085`) and hostname (default: `0.0.0.0`) for the deno server to use. If `start` is false, this has no effect; your own server must configure the port and hostname.
+
+ ```js
+ import { defineConfig } from 'astro/config';
+ import deno from '@astrojs/deno';
+
+ export default defineConfig({
+ adapter: deno({
+ port: 8081,
+ hostname: 'myhost'
+ })
+ });
+```
+
+
+## Examples
+
+The [Astro Deno](https://github.com/withastro/astro/tree/main/examples/deno) example includes a `preview:deno` command that runs the entry script directly. Run `npm run build` then `npm run preview:deno` to run the production deno server.
+
+## Troubleshooting
+
+## Contributing
+
+This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
+
+## Changelog
+
+[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/
diff --git a/packages/integrations/deno/readme.md b/packages/integrations/deno/readme.md
deleted file mode 100644
index 4b3dc959fa8d..000000000000
--- a/packages/integrations/deno/readme.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# @astrojs/deno
-
-A server-side rendering adapter for use with Deno targets. Write your code in Astro/Node and deploy to Deno servers.
-
-In your astro.config.mjs use:
-
-```js
-import { defineConfig } from 'astro/config';
-import deno from '@astrojs/deno';
-
-export default defineConfig({
- adapter: deno()
-});
-```
-
-After performing a build there will be a `dist/server/entry.mjs` module. You can start a server simply by importing this module:
-
-```js
-import './dist/entry.mjs';
-```
-
-## API
-
-### Adapter options
-
-This adapter automatically starts a server when it is imported. You can configure this through options:
-
-```js
-import { defineConfig } from 'astro/config';
-import deno from '@astrojs/deno';
-
-export default defineConfig({
- adapter: deno({
- start: false
- })
-});
-```
-
-If disabling start you need to write your own web server and use `handle` to render requests:
-
-```ts
-import { serve } from "https://deno.land/std@0.132.0/http/server.ts";
-import { handle } from './dist/entry.mjs';
-
-serve((req: Request) => {
- // Check the request, maybe do static file handling here.
-
- return handle(req);
-});
-```
-
-----
-
-You an also pass in a port/hostname to use:
-
-```js
-import { defineConfig } from 'astro/config';
-import deno from '@astrojs/deno';
-
-export default defineConfig({
- adapter: deno({
- port: 8081,
- hostname: 'myhost'
- })
-});
-```
diff --git a/packages/integrations/netlify/README.md b/packages/integrations/netlify/README.md
index dba81568ed82..a669227af8e8 100644
--- a/packages/integrations/netlify/README.md
+++ b/packages/integrations/netlify/README.md
@@ -1,8 +1,36 @@
# @astrojs/netlify
-Deploy your server-side rendered (SSR) Astro app to [Netlify](https://www.netlify.com/).
+This adapter allows Astro to deploy your SSR site to [Netlify](https://www.netlify.com/).
-Use this adapter in your Astro configuration file, alongside a valid deployment URL:
+- [Why Astro Netlify](#why-astro-netlify)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
+
+
+## Why Astro Netlify
+
+If you're using Astro as a static site builder—its behavior out of the box—you don't need an adapter.
+
+If you wish to [use server-side rendering (SSR)](https://docs.astro.build/en/guides/server-side-rendering/), Astro requires an adapter that matches your deployment runtime.
+
+[Netlify](https://www.netlify.com/) is a deployment platform that allows you to host your site by connecting directly to your GitHub repository. This adapter enhances the Astro build process to prepare your project for deployment through Netlify.
+
+
+## Installation
+
+First, install the `@astrojs/netlify` package using your package manager. If you're using npm or aren't sure, run this in the terminal:
+```sh
+npm install @astrojs/netlify
+```
+
+Then, install this adapter in your `astro.config.*` file using the `adapter` property. Note: there are two different adapters, one for Netlify Functions and one for Edge Functions. See [Edge Functions](#edge-functions) below on importing the latter.
+
+__astro.config.mjs__
```js
import { defineConfig } from 'astro/config';
@@ -13,15 +41,7 @@ export default defineConfig({
});
```
-After you build your site the `netlify/` folder will contain [Netlify Functions](https://docs.netlify.com/functions/overview/) in the `netlify/functions/` folder.
-
-Now you can deploy!
-
-```shell
-netlify deploy --build
-```
-
-## Edge Functions
+### Edge Functions
Netlify has two serverless platforms, Netlify Functions and Netlify Edge Functions. With Edge Functions your code is distributed closer to your users, lowering latency. You can use Edge Functions by changing the import in your astro configuration file:
@@ -34,12 +54,31 @@ export default defineConfig({
adapter: netlify(),
});
```
+## Usage
+
+[Read the full deployment guide here.](https://docs.astro.build/en/guides/deploy/vercel)
+
+After [performing a build](https://docs.astro.build/en/guides/deploy/#building-the-app) the `netlify/` folder will contain [Netlify Functions](https://docs.netlify.com/functions/overview/) in the `netlify/functions/` folder.
+
+Now you can deploy. Install the [Netlify CLI](https://docs.netlify.com/cli/get-started/) and run:
+
+```shell
+netlify deploy --build
+```
+
+The [Netlify Blog post on Astro](https://www.netlify.com/blog/how-to-deploy-astro/) and the [Netlify Documentation](https://docs.netlify.com/integrations/frameworks/astro/) provide more information on how to use this integration to deploy to Netlify.
+
## Configuration
-### dist
+To configure this adapter, pass an object to the `netlify()` function call in `astro.config.mjs` - there's only one possible configuration option:
-We build to a `dist` directory at the base of your project. To change this, use the `dist` option:
+
+ dist
+
+
+
+We build to the `dist` directory at the base of your project. To change this, use the `dist` option:
```js
import { defineConfig } from 'astro/config';
@@ -56,14 +95,19 @@ And then point to the dist in your `netlify.toml`:
```toml
[functions]
- directory = "dist/functions"
+directory = "dist/functions"
```
-### binaryMediaTypes
+
+
+
+
+ binaryMediaTypes
+
> This option is only needed for the Functions adapter and is not needed for Edge Functions.
-Netlify Functions sending binary data in the `body` need to be base64 encoded. The `@astrojs/netlify/functions` adapter handles this automatically based on the `Content-Type` header.
+Netlify Functions requires binary data in the `body` to be base64 encoded. The `@astrojs/netlify/functions` adapter handles this automatically based on the `Content-Type` header.
We check for common mime types for audio, image, and video files. To include specific mime types that should be treated as binary data, include the `binaryMediaTypes` option with a list of binary mime types.
@@ -82,3 +126,21 @@ export function get() {
});
}
```
+
+
+## Examples
+
+- The [Astro Netlify Edge Starter](https://github.com/sarahetter/astro-netlify-edge-starter) provides an example and a guide in the README.
+
+- [Browse Astro Netlify projects on GitHub](https://github.com/search?q=%22%40astrojs%2Fnetlify%22+filename%3Apackage.json&type=Code) for more examples!
+
+## Troubleshooting
+
+## Contributing
+
+This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
+
+## Changelog
+
+[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/
+
diff --git a/packages/integrations/node/README.md b/packages/integrations/node/README.md
new file mode 100644
index 000000000000..ad8629e1ad82
--- /dev/null
+++ b/packages/integrations/node/README.md
@@ -0,0 +1,109 @@
+# @astrojs/node 🔲
+
+This adapter allows Astro to deploy your SSR site to Node targets.
+
+- [Why Astro Node](#why-astro-node)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
+
+
+## Why Astro Node
+
+If you're using Astro as a static site builder—its behavior out of the box—you don't need an adapter.
+
+If you wish to [use server-side rendering (SSR)](https://docs.astro.build/en/guides/server-side-rendering/), Astro requires an adapter that matches your deployment runtime.
+
+[Node](https://nodejs.org/en/) is a JavaScript runtime for server-side code. Frameworks like [Express](https://expressjs.com/) are built on top of it and make it easier to write server applications in Node. This adapter provides access to Node's API and creates a script to run your Astro project that can be utilized in Node applications.
+
+## Installation
+
+First, install the `@astrojs/node` package using your package manager. If you're using npm or aren't sure, run this in the terminal:
+```sh
+npm install @astrojs/node
+```
+
+Then, install this adapter in your `astro.config.*` file using the `adapter` property:
+
+__astro.config.mjs__
+
+```js
+import { defineConfig } from 'astro/config';
+import deno from '@astrojs/node';
+
+export default defineConfig({
+ // ...
+ adapter: node()
+})
+```
+
+## Usage
+
+After [performing a build](https://docs.astro.build/en/guides/deploy/#building-the-app) there will be a `dist/server/entry.mjs` module that exposes a `handler` function. This works like a [middleware](https://expressjs.com/en/guide/using-middleware.html) function: it can handle incoming requests and respond accordingly.
+
+
+### Using a middleware framework
+You can use this `handler` with any framework that supports the Node `request` and `response` objects.
+
+For example, with Express:
+
+```js
+import express from 'express';
+import { handler as ssrHandler } from './dist/server/entry.mjs';
+
+const app = express();
+app.use(ssrHandler);
+
+app.listen(8080);
+```
+
+
+### Using `http`
+
+This output script does not require you use Express and can work with even the built-in `http` and `https` node modules. The handler does follow the convention calling an error function when either
+
+- A route is not found for the request.
+- There was an error rendering.
+
+You can use these to implement your own 404 behavior like so:
+
+```js
+import http from 'http';
+import { handler as ssrHandler } from './dist/server/entry.mjs';
+
+http.createServer(function(req, res) {
+ ssrHandler(req, res, err => {
+ if(err) {
+ res.writeHead(500);
+ res.end(err.toString());
+ } else {
+ // Serve your static assets here maybe?
+ // 404?
+ res.writeHead(404);
+ res.end();
+ }
+ });
+}).listen(8080);
+```
+
+
+
+## Configuration
+
+This adapter does not expose any configuration options.
+
+## Examples
+
+## Troubleshooting
+
+## Contributing
+
+This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
+
+## Changelog
+
+[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/
diff --git a/packages/integrations/node/readme.md b/packages/integrations/node/readme.md
deleted file mode 100644
index ffd4b6ffaf34..000000000000
--- a/packages/integrations/node/readme.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# @astrojs/node
-
-An experimental server-side rendering adapter for use with Node.js servers.
-
-In your astro.config.mjs use:
-
-```js
-import { defineConfig } from 'astro/config';
-import nodejs from '@astrojs/node';
-
-export default defineConfig({
- adapter: nodejs()
-})
-```
-
-After performing a build there will be a `dist/server/entry.mjs` module that works like a middleware function. You can use with any framework that supports the Node `request` and `response` objects. For example, with Express you can do:
-
-```js
-import express from 'express';
-import { handler as ssrHandler } from './dist/server/entry.mjs';
-
-const app = express();
-app.use(ssrHandler);
-
-app.listen(8080);
-```
-
-# Using `http`
-
-This adapter does not require you use Express and can work with even the `http` and `https` modules. The adapter does following the Expression convention of calling a function when either
-
-- A route is not found for the request.
-- There was an error rendering.
-
-You can use these to implement your own 404 behavior like so:
-
-```js
-import http from 'http';
-import { handler as ssrHandler } from './dist/server/entry.mjs';
-
-http.createServer(function(req, res) {
- ssrHandler(req, res, err => {
- if(err) {
- res.writeHead(500);
- res.end(err.toString());
- } else {
- // Serve your static assets here maybe?
- // 404?
- res.writeHead(404);
- res.end();
- }
- });
-}).listen(8080);
-```
diff --git a/packages/integrations/partytown/README.md b/packages/integrations/partytown/README.md
index 2c10f6af31e3..88c244aad4b0 100644
--- a/packages/integrations/partytown/README.md
+++ b/packages/integrations/partytown/README.md
@@ -2,55 +2,75 @@
This **[Astro integration][astro-integration]** enables [Partytown](https://partytown.builder.io/) in your Astro project.
-Partytown is a lazy-loaded library to help relocate resource intensive scripts into a [web worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API), and off of the [main thread](https://developer.mozilla.org/en-US/docs/Glossary/Main_thread).
-
-## Installation
-
-There are two ways to add integrations to your project. Let's try the most convenient option first!
-### (experimental) `astro add` command
+- [Why Astro Partytown](#why-astro-partytown)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
-Astro includes a CLI tool for adding first party integrations: `astro add`. This command will:
-1. (Optionally) Install all necessary dependencies and peer dependencies
-2. (Also optionally) Update your `astro.config.*` file to apply this integration
+## Why Astro Partytown
-To install `@astrojs/partytown`, run the following from your project directory and follow the prompts:
-
-```sh
-# Using NPM
-npx astro add partytown
-# Using Yarn
-yarn astro add partytown
-# Using PNPM
-pnpx astro add partytown
-```
+Partytown is a lazy-loaded library to help relocate resource intensive scripts into a [web worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API), and off of the [main thread](https://developer.mozilla.org/en-US/docs/Glossary/Main_thread).
-If you run into any hiccups, [feel free to log an issue on our GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
+If you're using third-party scripts for things like analytics or ads, Partytown is a great way to make sure that they don't slow down your site.
-### Install dependencies manually
+The Astro Partytown integration installs Partytown for you and makes sure it's enabled on all of your pages.
-First, install the `@astrojs/partytown` integration like so:
+## Installation
-```
+
+ Quick Install
+
+
+The experimental `astro add` command-line tool automates the installation for you. Run one of the following commands in a new terminal window. (If you aren't sure which package manager you're using, run the first command.) Then, follow the prompts, and type "y" in the terminal (meaning "yes") for each one.
+
+ ```sh
+ # Using NPM
+ npx astro add partytown
+ # Using Yarn
+ yarn astro add partytown
+ # Using PNPM
+ pnpx astro add partytown
+ ```
+
+Then, restart the dev server by typing `CTRL-C` and then `npm run astro dev` in the terminal window that was running Astro.
+
+Because this command is new, it might not properly set things up. If that happens, [feel free to log an issue on our GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
+
+
+
+ Manual Install
+
+
+
+First, install the `@astrojs/partytown` package using your package manager. If you're using npm or aren't sure, run this in the terminal:
+```sh
npm install @astrojs/partytown
```
-
Then, apply this integration to your `astro.config.*` file using the `integrations` property:
__astro.config.mjs__
```js
-import partytown from '@astrojs/partytown';
+import { defineConfig } from 'astro/config';
+import partytown from '@astrojs/sitemap';
-export default {
+export default defineConfig({
// ...
integrations: [partytown()],
-}
+})
```
+
+Then, restart the dev server.
+
-## Getting started
+## Usage
-Partytown should be ready-to-use with zero config. If you have an existing 3rd party script on your site, try adding the `type="text/partytown"` attribute:
+Partytown should be ready to go with zero config. If you have an existing 3rd party script on your site, try adding the `type="text/partytown"` attribute:
```diff
-
@@ -61,37 +81,81 @@ If you open the "Network" tab from [your browser's dev tools](https://developer.
## Configuration
-### config.debug
+To configure this integration, pass a 'config' object to the `partytown()` function call in `astro.config.mjs`.
+
+__astro.config.mjs__
+```js
+...
+export default defineConfig({
+ integrations: [partytown({
+ config: {
+ //options go here
+ }
+ })]
+});
+```
+
+This mirrors the [Partytown config object](https://partytown.builder.io/configuration), but only `debug` and `forward` are exposed by this integration.
+
+
+ config.debug
+
+
+
+ Partytown ships with a `debug` mode; enable or disable it by passing `true` or `false` to `config.debug`. If [`debug` mode](https://partytown.builder.io/debugging) is enabled, it will output detailed logs to the browser console.
-You can set debug mode using this integration's `config.debug` option. If `config.debug` is unset, it will fall back to `true` if the command is `dev`.
+ If this option isn't set, `debug` mode will be on by default in [dev](https://docs.astro.build/en/reference/cli-reference/#astro-dev) or [preview](https://docs.astro.build/en/reference/cli-reference/#astro-preview) mode.
+
+__astro.config.mjs__
```js
-// astro.config.mjs
-export default {
+export default defineConfig({
integrations: [partytown({
// Example: Disable debug mode.
config: { debug: false },
- })],
-}
+
+})
```
+
+
+
+ config.forward
+
+
+
+ Third-party scripts typically add variables to the `window` object so that you can communicate with them throughout your site. But when a script is loaded in a web-worker, it doesn't have access to that global `window` object.
-### config.forward
+ To solve this, Partytown can "patch" variables to the global window object and forward them to the appropriate script.
-Because we’re moving third-party scripts to a web worker, the main thread needs to know which variables to patch on window, and when these services are called, the data is correctly forwarded to the web worker. You can to set it on the `config.forward` option.
+ You can specify which variables to forward with the `config.forward` option. [Read more in Partytown's documentation.](https://partytown.builder.io/forwarding-events)
+
+
+__astro.config.mjs__
```js
-// astro.config.mjs
-export default {
+export default defineConfig ({
integrations: [partytown({
// Example: Add dataLayer.push as a forwarding-event.
- config: { forward: ["dataLayer.push"] },
+ config: {
+ forward: ["dataLayer.push"]
+ },
})],
-}
+})
```
+
+
+## Examples
+
+- The [integrations playground template](https://github.com/withastro/astro/tree/latest/examples/integrations-playground?on=github) comes with Astro Partytown installed, with a demo script that shows how Partytown moves intensive operations off of the main thread.
+
+- [Browse projects with Astro Partytown on GitHub](https://github.com/search?q=%22@astrojs/partytown%22+filename:package.json&type=Code) for more examples!
+
+## Troubleshooting
+
+## Contributing
-## Read more
+This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
-[Head to the Partytown docs](https://partytown.builder.io/configuration) for configuration options and more usage examples. You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
+## Changelog
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/
-[astro-ui-frameworks]: https://docs.astro.build/en/core-concepts/framework-components/#using-framework-components
diff --git a/packages/integrations/sitemap/README.md b/packages/integrations/sitemap/README.md
index e37a1ed86bb3..7fffe52e2c3f 100644
--- a/packages/integrations/sitemap/README.md
+++ b/packages/integrations/sitemap/README.md
@@ -1,72 +1,101 @@
# @astrojs/sitemap 🗺
-This **[Astro integration][astro-integration]** generates a sitemap for your Astro project.
+This **[Astro integration][astro-integration]** generates a sitemap based on your routes when you build your Astro project.
-Sitemaps outline all of the pages, videos, and files on your site. Search engines like Google read this file to crawl your site more efficiently. [See Google's own advice on sitemaps](https://developers.google.com/search/docs/advanced/sitemaps/overview) to learn more.
-## Installation
-
-There are two ways to add integrations to your project. Let's try the most convenient option first!
-
-### (experimental) `astro add` command
+- [Why Astro Sitemap](#why-astro-sitemap)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
-Astro includes a CLI tool for adding first party integrations: `astro add`. This command will:
-1. (Optionally) Install all necessary dependencies and peer dependencies
-2. (Also optionally) Update your `astro.config.*` file to apply this integration
+## Why Astro Sitemap
-To install `@astrojs/sitemap`, run the following from your project directory and follow the prompts:
+A Sitemap is an XML file that outlines all of the pages, videos, and files on your site. Search engines like Google read this file to crawl your site more efficiently. [See Google's own advice on sitemaps](https://developers.google.com/search/docs/advanced/sitemaps/overview) to learn more.
-```sh
-# Using NPM
-npx astro add sitemap
-# Using Yarn
-yarn astro add sitemap
-# Using PNPM
-pnpx astro add sitemap
-```
+A sitemap file is recommended for large multi-page sites. If you don't use a sitemap, most search engines will still be able to list your site's pages, but a sitemap is a great way to ensure that your site is as search engine friendly as possible.
-If you run into any hiccups, [feel free to log an issue on our GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
+With Astro Sitemap, you don't have to worry about creating this file: build your Astro site how you normally would, and the Astro Sitemap integration will crawl your routes and create the sitemap file.
-### Install dependencies manually
-
-First, install the `@astrojs/sitemap` integration like so:
+## Installation
-```
+
+ Quick Install
+
+
+The experimental `astro add` command-line tool automates the installation for you. Run one of the following commands in a new terminal window. (If you aren't sure which package manager you're using, run the first command.) Then, follow the prompts, and type "y" in the terminal (meaning "yes") for each one.
+
+ ```sh
+ # Using NPM
+ npx astro add sitemap
+ # Using Yarn
+ yarn astro add sitemap
+ # Using PNPM
+ pnpx astro add sitemap
+ ```
+
+Then, restart the dev server by typing `CTRL-C` and then `npm run astro dev` in the terminal window that was running Astro.
+
+Because this command is new, it might not properly set things up. If that happens, [feel free to log an issue on our GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
+
+
+
+ Manual Install
+
+
+
+First, install the `@astrojs/sitemap` package using your package manager. If you're using npm or aren't sure, run this in the terminal:
+```sh
npm install @astrojs/sitemap
```
-
Then, apply this integration to your `astro.config.*` file using the `integrations` property:
__astro.config.mjs__
```js
+import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
-export default {
+export default defineConfig({
// ...
integrations: [sitemap()],
-}
+})
```
+
+Then, restart the dev server.
+
-## Getting started
+## Usage
-`@astrojs/sitemap` requires a deployment / site URL for generation. Add your site's URL under your `astro.config.*` using the `site` property:
+`@astrojs/sitemap` requires a deployment / site URL for generation. Add your site's URL under your `astro.config.*` using the `site` property. This must begin with `http:` or `https:`.
__astro.config.mjs__
```js
+import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
-export default {
+export default defineConfig({
// ...
site: 'https://stargazers.club',
integrations: [sitemap()],
-}
+})
```
-Now, [build your site for production](https://docs.astro.build/en/reference/cli-reference/#astro-build) via the `astro build` command. You should find your _sitemap_ under `dist/sitemap-index.xml` and `dist/sitemap-0.xml`!
+Note that unlike other configuration options, `site` is set in the root `defineConfig` object, rather than inside the `sitemap()` call.
+
+Now, [build your site for production](https://docs.astro.build/en/reference/cli-reference/#astro-build) via the `astro build` command. You should find your sitemap under `dist/sitemap.xml`!
-Generated sitemap content for two pages website:
+> **Warning**
+> If you forget to add a `site`, you'll get a friendly warning when you build, and the `sitemap.xml` file won't be generated.
+
+
+
+Example of generated sitemap content for a two-page website:
+
**sitemap-index.xml**
@@ -93,76 +122,69 @@ Generated sitemap content for two pages website:
```
+
-You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
-## Configuration
-### filter
-All pages are included in your sitemap by default. By adding a custom `filter`, you can filter included pages by URL.
+## Configuration
-__astro.config.mjs__
+To configure this integration, pass an object to the `sitemap()` function call in `astro.config.mjs`.
+__astro.config.mjs__
```js
-import sitemap from '@astrojs/sitemap';
-
-export default {
- site: 'https://stargazers.club',
- integrations: [
- sitemap({
- filter: (page) => page !== 'https://stargazers.club/secret-vip-lounge'
- }),
- ],
-}
+...
+export default defineConfig({
+ integrations: [sitemap({
+ filter: ...
+ })]
+});
```
-The `page` function parameter is the full URL of your rendered page, including your `site` domain. Return `true` to include a page in your sitemap, and `false` to remove it.
-
-### customPages
-
-You may have custom routes to add to your sitemap. To append these to your sitemap, pass an array of valid URLs including the base origin:
+
+ filter
+
+
+
+ All pages are included in your sitemap by default. By adding a custom `filter` function, you can filter included pages by URL.
__astro.config.mjs__
```js
-import sitemap from '@astrojs/sitemap';
-
-export default {
- site: 'https://stargazers.club',
- integrations: [
+...
sitemap({
- customPages: ['https://stargazers.biz/careers'],
+ filter: (page) => page !== 'https://stargazers.club/secret-vip-lounge'
}),
- ],
-}
```
-💡 You should also use `customPages` to manually list sitemap pages when using an SSR adapter. Currently, we cannot detect your site's pages unless you are building statically. To avoid an empty sitemap, list all pages (including the base origin) with this configuration option!
-
-### canonicalURL
+The function will be called for every page on your site. The `page` function parameter is the full URL of the page currently under considering, including your `site` domain. Return `true` to include the page in your sitemap, and `false` to leave it out.
+
+
-If present, we use the `site` config option as the base for all sitemap URLs. Use `canonicalURL` to override this.
+
+ customPages
+
+
+
+ In some cases, a page might be part of your deployed site but not part of your Astro project.
+ If you'd like to include a page in your sitemap that _isn't_ created by Astro, you can use this option.
__astro.config.mjs__
```js
-import sitemap from '@astrojs/sitemap';
-
-export default {
- site: 'https://stargazers.club',
- integrations: [
+...
sitemap({
- // https://astronaut.party will be used for all sitemap URLs instead
- canonicalURL: 'https://astronaut.party',
+ customPages: ['https://stargazers.club/external-page', 'https://stargazers.club/external-page2']
}),
- ],
-}
```
+
-### entryLimit
+
+
+ entryLimit
+
-Non-negative `Number` of entries per sitemap file. Default value is 45000. A sitemap index and multiple sitemaps are created if you have more entries. See explanation about large sitemaps on [Google](https://developers.google.com/search/docs/advanced/sitemaps/large-sitemaps).
+The maximum number entries per sitemap file. The default value is 45000. A sitemap index and multiple sitemaps are created if you have more entries. See this [explanation of splitting up a large sitemap](https://developers.google.com/search/docs/advanced/sitemaps/large-sitemaps).
__astro.config.mjs__
@@ -178,21 +200,20 @@ export default {
],
}
```
+
-### changefreq, lastmod, priority
-`changefreq` - How frequently the page is likely to change. Available values: `always` \| `hourly` \| `daily` \| `weekly` \| `monthly` \| `yearly` \| `never`.
+
+
+ changefreq, lastmod, and priority
+
-`priority` - The priority of this URL relative to other URLs on your site. Valid values range from 0.0 to 1.0.
+These options correspond to the ``, ``, and `` tags in the [Sitemap XML specification.](https://www.sitemaps.org/protocol.html)
-`lastmod` - The date of page last modification.
+Note that `changefreq` and `priority` are ignored by Google.
-The `changefreq` and `priority` are ignored by Google.
-
-See detailed explanation of sitemap specific options on [sitemap.org](https://www.sitemaps.org/protocol.html).
-
-
-:exclamation: This integration uses 'astro:build:done' hook. The hook exposes generated page paths only. So with present version of Astro the integration has no abilities to analyze a page source, frontmatter etc. The integration can add `changefreq`, `lastmod` and `priority` attributes only in a batch or nothing.
+> **Note**
+> Due to limitations of Astro's [Integration API](https://docs.astro.build/en/reference/integrations-reference/), this integration can't analyze a given page's source code. This configuration option can set `changefreq`, `lastmod` and `priority` on a _site-wide_ basis; see the next option **serialize** for how you can set these values on a per-page basis.
__astro.config.mjs__
@@ -211,20 +232,29 @@ export default {
}
```
-### serialize
+
-Async or sync function called for each sitemap entry just before writing to a disk.
+
+
+ serialize
+
-It receives as parameter a `SitemapItem` object which consists of `url` (required, absolute page URL) and optional `changefreq`, `lastmod` (ISO formatted date, `String` type), `priority` and `links` properties.
+A function called for each sitemap entry just before writing to a disk. This function can be asynchronous.
-Optional `links` property contains the `LinkItem` list of alternate pages including a parent page.
-The `LinkItem` type has two required fields: `url` (the fully-qualified URL for the version of this page for the specified language) and `lang` (a supported language code targeted by this version of the page).
+It receives as its parameter a `SitemapItem` object that can have these properties:
+ - `url` (absolute page URL). This is the only property that is guaranteed to be on `SitemapItem`.
+ - `changefreq`
+ - `lastmod` (ISO formatted date, `String` type)
+ - `priority`
+ - `links`.
-The `serialize` function should return `SitemapItem`, touched or not.
+This `links` property contains a `LinkItem` list of alternate pages including a parent page.
-To exclude the passed entry from sitemap it should return `undefined`.
+The `LinkItem` type has two fields: `url` (the fully-qualified URL for the version of this page for the specified language) and `lang` (a supported language code targeted by this version of the page).
-The example below shows the ability to exclude certain entries and add the sitemap specific properties individually.
+The `serialize` function should return `SitemapItem`, touched or not.
+
+The example below shows the ability to add sitemap specific properties individually.
__astro.config.mjs__
@@ -251,17 +281,24 @@ export default {
}
```
-### i18n
-To localize a sitemap you should supply the integration config with the `i18n` option. The integration will check generated page paths on presence of locale keys in paths.
+
+
+
+
+ i18n
+
-`i18n` object has two required properties:
+To localize a sitemap, pass an object to this `i18n` option.
+
+This object has two required properties:
- `defaultLocale`: `String`. Its value must exist as one of `locales` keys.
-- `locales`: `Record`, key/value - pairs. The key is used to look for a locale part in a page path. The value is a language attribute, only English alphabet and hyphen allowed. See more about language attribute on [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang).
+- `locales`: `Record`, key/value - pairs. The key is used to look for a locale part in a page path. The value is a language attribute, only English alphabet and hyphen allowed.
+[Read more about language attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang).
-Read more about localization on Google in [Advanced SEO](https://developers.google.com/search/docs/advanced/crawling/localized-versions#all-method-guidelines).
+[Read more about localization](https://developers.google.com/search/docs/advanced/crawling/localized-versions#all-method-guidelines).
__astro.config.mjs__
@@ -283,11 +320,10 @@ export default {
}),
],
};
-...
-
```
-The sitemap content will be:
+
+ The resulting sitemap looks like this
```xml
...
@@ -318,5 +354,21 @@ The sitemap content will be:
...
```
+
+
+
+## Examples
+- The official Astro website uses Astro Sitemap to generate [its sitemap](https://astro.build/sitemap.xml).
+- The [integrations playground template](https://github.com/withastro/astro/tree/latest/examples/integrations-playground?on=github) comes with Astro Sitemap installed. Try adding a route and building the project!
+- [Browse projects with Astro Sitemap on GitHub](https://github.com/search?q=%22@astrojs/sitemap%22+filename:package.json&type=Code) for more examples!
+
+## Troubleshooting
+
+## Contributing
+
+This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
+
+## Changelog
+
+
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/
-[astro-ui-frameworks]: https://docs.astro.build/en/core-concepts/framework-components/#using-framework-components
diff --git a/packages/integrations/sitemap/src/index.ts b/packages/integrations/sitemap/src/index.ts
index 6c661905f8fa..b548ba4e4380 100644
--- a/packages/integrations/sitemap/src/index.ts
+++ b/packages/integrations/sitemap/src/index.ts
@@ -23,7 +23,6 @@ export type SitemapOptions =
| {
filter?(page: string): boolean;
customPages?: string[];
- canonicalURL?: string;
i18n?: {
defaultLocale: string;
@@ -66,18 +65,16 @@ const createPlugin = (options?: SitemapOptions): AstroIntegration => {
try {
const opts = validateOptions(config.site, options);
- const { filter, customPages, canonicalURL, serialize, entryLimit } = opts;
+ const { filter, customPages, serialize, entryLimit } = opts;
let finalSiteUrl: URL;
- if (canonicalURL) {
- finalSiteUrl = new URL(canonicalURL);
- if (!finalSiteUrl.pathname.endsWith('/')) {
- finalSiteUrl.pathname += '/'; // normalizes the final url since it's provided by user
- }
- } else {
- // `validateOptions` forces to provide `canonicalURL` or `config.site` at least.
- // So step to check on empty values of `canonicalURL` and `config.site` is dropped.
+ if (config.site) {
finalSiteUrl = new URL(config.base, config.site);
+ } else {
+ console.warn(
+ 'The Sitemap integration requires the `site` astro.config option. Skipping.'
+ );
+ return;
}
let pageUrls = pages.map((p) => {
diff --git a/packages/integrations/vercel/README.md b/packages/integrations/vercel/README.md
index 3545774cfe46..dd7d0679dec6 100644
--- a/packages/integrations/vercel/README.md
+++ b/packages/integrations/vercel/README.md
@@ -1,8 +1,34 @@
# @astrojs/vercel
-Deploy your server-side rendered (SSR) Astro app to [Vercel](https://www.vercel.com/).
+This adapter allows Astro to deploy your SSR site to [Vercel](https://www.vercel.com/).
-Use this integration in your Astro configuration file:
+- [Why Astro Vercel](#why-astro-vercel)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
+
+## Why Astro Vercel
+
+If you're using Astro as a static site builder—its behavior out of the box—you don't need an adapter.
+
+If you wish to [use server-side rendering (SSR)](https://docs.astro.build/en/guides/server-side-rendering/), Astro requires an adapter that matches your deployment runtime.
+
+[Vercel](https://www.netlify.com/) is a deployment platform that allows you to host your site by connecting directly to your GitHub repository. This adapter enhances the Astro build process to prepare your project for deployment through Vercel.
+
+## Installation
+
+First, install the `@astrojs/vercel` package using your package manager. If you're using npm or aren't sure, run this in the terminal:
+```sh
+npm install @astrojs/vercel
+```
+
+Then, install this adapter in your `astro.config.*` file using the `adapter` property (note the import from `@astrojs/vercel/serverless` - see [targets](#targets)).
+
+ __astro.config.mjs__
```js
import { defineConfig } from 'astro/config';
@@ -13,9 +39,27 @@ export default defineConfig({
});
```
-When you build your project, Astro will know to use the `.vercel/output` folder format that Vercel expects.
+### Targets
+
+You can deploy to different targes:
+
+- `edge`: SSR inside an [Edge function](https://vercel.com/docs/concepts/functions/edge-functions).
+- `serverless`: SSR inside a [Node.js function](https://vercel.com/docs/concepts/functions/serverless-functions).
+- `static`: generates a static website following Vercel's output formats, redirects, etc.
+
+> **Note**: deploying to the Edge has [its limitations](https://vercel.com/docs/concepts/functions/edge-functions#known-limitations). An edge function can't be more than 1 MB in size and they don't support native Node.js APIs, among others.
+
+You can change where to target by changing the import:
+
+```js
+import vercel from '@astrojs/vercel/edge';
+import vercel from '@astrojs/vercel/serverless';
+import vercel from '@astrojs/vercel/static';
+```
+
+## Usage
-## Deploying
+📚 **[Read the full deployment guide here.](https://docs.astro.build/en/guides/deploy/vercel)**
You can deploy by CLI (`vercel deploy`) or by connecting your new repo in the [Vercel Dashboard](https://vercel.com/). Alternatively, you can create a production build locally:
@@ -24,8 +68,6 @@ ENABLE_VC_BUILD=1 astro build
vercel deploy --prebuilt
```
-## Requirements
-
**Vercel's [Build Output API](https://vercel.com/docs/build-output-api/v3) must be enabled.** You must enable it yourself by setting the environment variable: `ENABLE_VC_BUILD=1`.
```js
@@ -41,24 +83,20 @@ vercel deploy --prebuilt
[Learn more about setting enviroment variables in Vercel](https://vercel.com/docs/concepts/projects/environment-variables).
-## Targets
+## Configuration
-You can deploy to different targes:
+This adapter does not expose any configuration options.
-- `edge`: SSR inside a [Edge function](https://vercel.com/docs/concepts/functions/edge-functions).
-- `serverless`: SSR inside a [Node.js function](https://vercel.com/docs/concepts/functions/serverless-functions).
-- `static`: generates a static website following Vercel's output formats, redirects, etc.
+## Examples
-> **Note**: deploying to the Edge has [its limitations](https://vercel.com/docs/concepts/functions/edge-functions#known-limitations) — they can't be more than 1 MB in size and they don't support native Node.js APIs, among others.
+## Troubleshooting
-You can change where to target by changing the import:
+**A few known complex packages (example: [puppeteer](https://github.com/puppeteer/puppeteer)) do not support bundling and therefore will not work properly with this adapter.** By default, Vercel doesn't include npm installed files & packages from your project's `./node_modules` folder. To address this, the `@astrojs/vercel` adapter automatically bundles your final build output using `esbuild`.
-```js
-import vercel from '@astrojs/vercel/edge';
-import vercel from '@astrojs/vercel/serverless';
-import vercel from '@astrojs/vercel/static';
-```
+## Contributing
-## Limitations
+This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
-**A few known complex packages (example: [puppeteer](https://github.com/puppeteer/puppeteer)) do not support bundling and therefore will not work properly with this adapter.** By default, Vercel doesn't include npm installed files & packages from your project's `./node_modules` folder. To address this, the `@astrojs/vercel` adapter automatically bundles your final build output using `esbuild`.
+## Changelog
+
+[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/
diff --git a/packages/telemetry/README.md b/packages/telemetry/README.md
index 9c0999e1af2e..6adc8b96f465 100644
--- a/packages/telemetry/README.md
+++ b/packages/telemetry/README.md
@@ -1,6 +1,6 @@
# Astro Telemetry
-This package is used to collect anonymous telemetry data within the Astro CLI. Telemetry data does not contain any personal identifying information and can be disabled via:
+This package is used to collect anonymous telemetry data within the Astro CLI. It is enabled by default. Telemetry data does not contain any personal identifying information and can be disabled via:
```shell
astro telemetry disable