michael/astro
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Integration Docs Next Steps (#3677)

Browse source 
* sitemap readme skeleton + first sections

* Revert "sitemap readme skeleton + first sections"

This reverts commit cc55b312b6.

* sitemap readme skeleton + first sections

* remove canonicalURL option from sitemap

* add customPages option to readme

* sitemap examples

* partytown

* deno run command

* reference deno example

* node readme

* netlify & vercel readmes

* note that telemetry is installed

* telemetry is *enabled*, not installed

* Update packages/integrations/vercel/README.md

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

* Update packages/integrations/vercel/README.md

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

* readme -> README

* Update packages/integrations/deno/readme.md

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

* Update packages/integrations/deno/readme.md

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

* qualify they

* Update packages/integrations/sitemap/README.md

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

* Uppercase README names

* Update packages/integrations/partytown/README.md

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

* imports -> import typo

* update changeset

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
This commit is contained in:
Dan Jutan 2022-06-30 12:02:39 -04:00 committed by GitHub
parent 75ffab7009
commit 8045c8ade1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
11 changed files with 675 additions and 323 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
.changeset/yellow-cameras-ring.md Normal file
View file

@ -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

139
packages/integrations/deno/README.md Normal file
View file

@ -0,0 +1,139 @@
# @astrojs/deno 🦖
This adapter allows Astro to deploy your SSR site to Deno targets.
- <strong>[Why Astro Deno](#why-astro-deno)</strong>
- <strong>[Installation](#installation)</strong>
- <strong>[Usage](#usage)</strong>
- <strong>[Configuration](#configuration)</strong>
- <strong>[Examples](#examples)</strong>
- <strong>[Troubleshooting](#troubleshooting)</strong>
- <strong>[Contributing](#contributing)</strong>
- <strong>[Changelog](#changelog)</strong>
## 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
})
});
```
<details>
<summary><strong>start</strong></summary>
<br/>
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);
});
```
</details>
<details>
<summary><strong>port</strong> and <strong>hostname</strong></summary>
<br/>
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'
})
});
```
</details>
## 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/

66
packages/integrations/deno/readme.md
View file

@ -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'
})
});
```

94
packages/integrations/netlify/README.md
View file

@ -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:
- <strong>[Why Astro Netlify](#why-astro-netlify)</strong>
- <strong>[Installation](#installation)</strong>
- <strong>[Usage](#usage)</strong>
- <strong>[Configuration](#configuration)</strong>
- <strong>[Examples](#examples)</strong>
- <strong>[Troubleshooting](#troubleshooting)</strong>
- <strong>[Contributing](#contributing)</strong>
- <strong>[Changelog](#changelog)</strong>
## 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:
<details>
<summary><strong>dist</strong></summary>
<br/>
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
</details>
<details>
<summary>
<strong>binaryMediaTypes</strong>
</summary>
> 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() {
});
}
```
</details>
## 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/

109
packages/integrations/node/README.md Normal file
View file

@ -0,0 +1,109 @@
# @astrojs/node 🔲
This adapter allows Astro to deploy your SSR site to Node targets.
- <strong>[Why Astro Node](#why-astro-node)</strong>
- <strong>[Installation](#installation)</strong>
- <strong>[Usage](#usage)</strong>
- <strong>[Configuration](#configuration)</strong>
- <strong>[Examples](#examples)</strong>
- <strong>[Troubleshooting](#troubleshooting)</strong>
- <strong>[Contributing](#contributing)</strong>
- <strong>[Changelog](#changelog)</strong>
## 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/

54
packages/integrations/node/readme.md
View file

@ -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);
```

148
packages/integrations/partytown/README.md
View file

@ -2,55 +2,75 @@
This **[Astro integration][astro-integration]** enables [Partytown](https://partytown.builder.io/) in your Astro project.
- <strong>[Why Astro Partytown](#why-astro-partytown)</strong>
- <strong>[Installation](#installation)</strong>
- <strong>[Usage](#usage)</strong>
- <strong>[Configuration](#configuration)</strong>
- <strong>[Examples](#examples)</strong>
- <strong>[Troubleshooting](#troubleshooting)</strong>
- <strong>[Contributing](#contributing)</strong>
- <strong>[Changelog](#changelog)</strong>
## Why Astro 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'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.
The Astro Partytown integration installs Partytown for you and makes sure it's enabled on all of your pages.
## Installation
There are two ways to add integrations to your project. Let's try the most convenient option first!
<details>
<summary>Quick Install</summary>
<br/>
### (experimental) `astro add` command
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.
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
```sh
# Using NPM
npx astro add partytown
# Using Yarn
yarn astro add partytown
# Using PNPM
pnpx astro add partytown
```
To install `@astrojs/partytown`, run the following from your project directory and follow the prompts:
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.
</details>
<details>
<summary>Manual Install</summary>
<br/>
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
# Using NPM
npx astro add partytown
# Using Yarn
yarn astro add partytown
# Using PNPM
pnpx astro add partytown
```
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.
### Install dependencies manually
First, install the `@astrojs/partytown` integration like so:
```
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()],
}
})
```
## Getting started
Then, restart the dev server.
</details>
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:
## Usage
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
- <script src="fancy-analytics.js"></script>
@ -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`.
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`.
__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.
<details>
<summary><strong>config.debug</strong></summary>
<br/>
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.
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 },
})],
}
})
```
</details>
### config.forward
<details>
<summary><strong>config.forward</strong></summary>
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.
<br/>
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.
To solve this, Partytown can "patch" variables to the global window object and forward them to the appropriate script.
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"]
},
})],
}
})
```
</details>
## Read more
## Examples
[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.
- 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
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

266
packages/integrations/sitemap/README.md
View file

@ -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.
- <strong>[Why Astro Sitemap](#why-astro-sitemap)</strong>
- <strong>[Installation](#installation)</strong>
- <strong>[Usage](#usage)</strong>
- <strong>[Configuration](#configuration)</strong>
- <strong>[Examples](#examples)</strong>
- <strong>[Troubleshooting](#troubleshooting)</strong>
- <strong>[Contributing](#contributing)</strong>
- <strong>[Changelog](#changelog)</strong>
## Why Astro Sitemap
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.
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.
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.
## Installation
There are two ways to add integrations to your project. Let's try the most convenient option first!
<details>
<summary>Quick Install</summary>
<br/>
### (experimental) `astro add` command
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.
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
```sh
# Using NPM
npx astro add sitemap
# Using Yarn
yarn astro add sitemap
# Using PNPM
pnpx astro add sitemap
```
To install `@astrojs/sitemap`, run the following from your project directory and follow the prompts:
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.
</details>
<details>
<summary>Manual Install</summary>
<br/>
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
# Using NPM
npx astro add sitemap
# Using Yarn
yarn astro add sitemap
# Using PNPM
pnpx astro add sitemap
```
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.
### Install dependencies manually
First, install the `@astrojs/sitemap` integration like so:
```
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()],
}
})
```
## Getting started
Then, restart the dev server.
</details>
`@astrojs/sitemap` requires a deployment / site URL for generation. Add your site's URL under your `astro.config.*` using the `site` property:
## Usage
`@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.
Generated sitemap content for two pages website:
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`!
> **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.
<details>
<summary>
Example of generated sitemap content for a two-page website:
</summary>
**sitemap-index.xml**
@ -93,76 +122,69 @@ Generated sitemap content for two pages website:
</url>
</urlset>
```
</details>
You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
## Configuration
### filter
To configure this integration, pass an object to the `sitemap()` function call in `astro.config.mjs`.
All pages are included in your sitemap by default. By adding a custom `filter`, you can filter included pages by URL.
__astro.config.mjs__
```js
...
export default defineConfig({
integrations: [sitemap({
filter: ...
})]
});
```
<details>
<summary><strong>filter</strong></summary>
<br/>
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({
filter: (page) => page !== 'https://stargazers.club/secret-vip-lounge'
}),
],
}
```
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.
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.
### customPages
</details>
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:
<details>
<summary><strong>customPages</strong></summary>
<br/>
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({
customPages: ['https://stargazers.biz/careers'],
customPages: ['https://stargazers.club/external-page', 'https://stargazers.club/external-page2']
}),
],
}
```
</details>
💡 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!
<details>
<summary>
entryLimit
</summary>
### canonicalURL
If present, we use the `site` config option as the base for all sitemap URLs. Use `canonicalURL` to override this.
__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',
}),
],
}
```
### 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`.
`priority` - The priority of this URL relative to other URLs on your site. Valid values range from 0.0 to 1.0.
`lastmod` - The date of page last modification.
The `changefreq` and `priority` are ignored by Google.
See detailed explanation of sitemap specific options on [sitemap.org](https://www.sitemaps.org/protocol.html).
</details>
: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.
<details>
<summary>
<strong>changefreq</strong>, <strong>lastmod</strong>, and <strong>priority</strong>
</summary>
These options correspond to the `<changefreq>`, `<lastmod>`, and `<priortity>` tags in the [Sitemap XML specification.](https://www.sitemaps.org/protocol.html)
Note that `changefreq` and `priority` are ignored by Google.
> **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
</details>
Async or sync function called for each sitemap entry just before writing to a disk.
<details>
<summary>
<strong>serialize</strong>
</summary>
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`.
This `links` property contains a `LinkItem` list of alternate pages including a parent page.
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 `serialize` function should return `SitemapItem`, touched or not.
To exclude the passed entry from sitemap it should return `undefined`.
The example below shows the ability to exclude certain entries and add the sitemap specific properties individually.
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.
</details>
`i18n` object has two required properties:
<details>
<summary>
<strong>i18n</strong>
</summary>
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<String, String>`, 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<String, String>`, 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:
<details>
<summary>The resulting sitemap looks like this</summary>
```xml
...
@ -318,5 +354,21 @@ The sitemap content will be:
...
```
</details>
</details>
## 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

17
packages/integrations/sitemap/src/index.ts
View file

@ -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) => {

82
packages/integrations/vercel/README.md
View file

@ -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:
- <strong>[Why Astro Vercel](#why-astro-vercel)</strong>
- <strong>[Installation](#installation)</strong>
- <strong>[Usage](#usage)</strong>
- <strong>[Configuration](#configuration)</strong>
- <strong>[Examples](#examples)</strong>
- <strong>[Troubleshooting](#troubleshooting)</strong>
- <strong>[Contributing](#contributing)</strong>
- <strong>[Changelog](#changelog)</strong>
## 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
## Deploying
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
📚 **[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.
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';
```
## Limitations
## Troubleshooting
**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`.
## 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/

2
packages/telemetry/README.md
View file

@ -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