Infrastructure/astro
0
Fork 0
mirror of https://github.com/withastro/astro.git synced 2024-12-30 22:03:56 -05:00
Code Issues Activity

[docs] minimal integration READMEs (#9479)

Browse source 
Co-authored-by: Emanuele Stoppa <602478+ematipico@users.noreply.github.com>
Co-authored-by: Elian <15145918+ElianCodes@users.noreply.github.com>
Co-authored-by: Alexander Niebuhr <45965090+alexanderniebuhr@users.noreply.github.com>
This commit is contained in:
Sarah Rainsberger 2023-12-21 16:35:11 -04:00 committed by GitHub
parent f9c4bbf200
commit 1baf0b0d3c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
15 changed files with 343 additions and 2963 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
.changeset/soft-sheep-glow.md Normal file
View file

@ -0,0 +1,18 @@
---
'@astrojs/alpinejs': patch
'@astrojs/lit': patch
'@astrojs/markdoc': patch
'@astrojs/mdx': patch
'@astrojs/node': patch
'@astrojs/partytown': patch
'@astrojs/preact': patch
'@astrojs/react': patch
'@astrojs/sitemap': patch
'@astrojs/solid-js': patch
'@astrojs/svelte': patch
'@astrojs/tailwind': patch
'@astrojs/vercel': patch
'@astrojs/vue': patch
---
Updates README

118
packages/integrations/alpinejs/README.md
View file

@ -2,109 +2,37 @@
This **[Astro integration][astro-integration]** adds [Alpine.js](https://alpinejs.dev/) to your project so that you can use Alpine.js anywhere on your page.
- <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>
## Documentation
## Installation
Read the [`@astrojs/alpinejs` docs][docs]
### Quick Install
## Support
The `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.
- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more!
```sh
# Using NPM
npx astro add alpinejs
# Using Yarn
yarn astro add alpinejs
# Using PNPM
pnpm astro add alpinejs
```
- Check our [Astro Integration Documentation][astro-integration] for more on integrations.
If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
### Manual Install
First, install the `@astrojs/alpinejs` package using your package manager. If you're using npm or aren't sure, run this in the terminal:
```sh
npm install @astrojs/alpinejs
```
Most package managers will install associated peer dependencies as well. However, if you see a "Cannot find package 'alpinejs'" (or similar) warning when you start up Astro, you'll need to manually install Alpine.js yourself:
```sh
npm install alpinejs @types/alpinejs
```
Then, apply this integration to your `astro.config.*` file using the `integrations` property:
```diff lang="js" "alpine()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import alpine from '@astrojs/alpinejs';
export default defineConfig({
// ...
integrations: [alpine()],
// ^^^^^^^^
});
```
## Usage
Once the integration is installed, you can use [Alpine.js](https://alpinejs.dev/) directives and syntax inside any Astro component. The Alpine.js script is automatically added and enabled on every page of your website.
Check our [Astro Integration Documentation][astro-integration] for more on integrations.
## Limitations
The Alpine.js integration does not give you control over how the script is loaded or initialized. If you require this control, consider [installing and using Alpine.js manually](https://alpinejs.dev/essentials/installation). Astro supports all officially documented Alpine.js manual setup instructions, using `<script>` tags inside of an Astro component.
**It is not currently possible to [extend Alpine.js](https://alpinejs.dev/advanced/extending) when using this component.** If you need this feature, consider following [the manual Alpine.js setup](https://alpinejs.dev/essentials/installation) instead using an Astro script tag:
```astro
---
// src/pages/index.astro
---
<!-- Example: Load AlpineJS on a single page. -->
<script>
import Alpine from 'alpinejs';
// Optional: Extend Alpine.js
// Alpine.directive('foo', ...)
window.Alpine = Alpine;
Alpine.start();
</script>
```
## Configuration
The Alpine.js integration does not support any custom configuration at this time.
## Examples
- The [Astro Alpine.js example](https://github.com/withastro/astro/tree/latest/examples/framework-alpine) shows how to use Alpine.js in an Astro project.
## Troubleshooting
For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
- Submit bug reports and feature requests as [GitHub issues][issues].
## Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started:
## Changelog
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]
See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration.
## License
[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
MIT
Copyright (c) 2023–present [Astro][astro]
[astro]: https://astro.build/
[docs]: https://docs.astro.build/en/guides/integrations-guide/alpinejs/
[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md
[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
[discord]: https://astro.build/chat/
[issues]: https://github.com/withastro/astro/issues
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/

169
packages/integrations/lit/README.md
View file

@ -2,156 +2,37 @@
This **[Astro integration][astro-integration]** enables server-side rendering and client-side hydration for your [Lit](https://lit.dev/) custom elements.
## Installation
## Documentation
There are two ways to add integrations to your project. Let's try the most convenient option first!
Read the [`@astrojs/lit` docs][docs]
### `astro add` command
## Support
Astro includes a CLI tool for adding first party integrations: `astro add`. This command will:
- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more!
1. (Optionally) Install all necessary dependencies and peer dependencies
2. (Also optionally) Update your `astro.config.*` file to apply this integration
- Check our [Astro Integration Documentation][astro-integration] for more on integrations.
To install `@astrojs/lit`, run the following from your project directory and follow the prompts:
```sh
# Using NPM
npx astro add lit
# Using Yarn
yarn astro add lit
# Using PNPM
pnpm astro add lit
```
If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
### Install dependencies manually
First, install the `@astrojs/lit` integration like so:
```sh
npm install @astrojs/lit
```
Most package managers will install associated peer dependencies as well. Still, if you see a "Cannot find package 'lit'" (or similar) warning when you start up Astro, you'll need to install `lit` and `@webcomponents/template-shadowroot`:
```sh
npm install lit @webcomponents/template-shadowroot
```
Now, apply this integration to your `astro.config.*` file using the `integrations` property:
```diff lang="js" "lit()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import lit from '@astrojs/lit';
export default defineConfig({
// ...
integrations: [lit()],
// ^^^^^
});
```
## Getting started
To use your first Lit component in Astro, head to our [UI framework documentation][astro-ui-frameworks]. This explains:
- 📦 how framework components are loaded,
- 💧 client-side hydration options, and
- 🤝 opportunities to mix and nest frameworks together
Writing and importing a Lit component in Astro looks like this:
```js
// src/components/my-element.js
import { LitElement, html } from 'lit';
export class MyElement extends LitElement {
render() {
return html` <p>Hello world! From my-element</p> `;
}
}
customElements.define('my-element', MyElement);
```
Now, the component is ready to be imported via the Astro frontmatter:
```astro
---
// src/pages/index.astro
import { MyElement } from '../components/my-element.js';
---
<MyElement />
```
> Note that Lit requires browser globals such as `HTMLElement` and `customElements` to be present. For this reason the Lit renderer shims the server with these globals so Lit can run. You _might_ run into libraries that work incorrectly because of this.
### Polyfills & Hydration
The renderer automatically handles adding appropriate polyfills for support in browsers that don't have Declarative Shadow DOM. The polyfill is about _1.5kB_. If the browser does support Declarative Shadow DOM then less than 250 bytes are loaded (to feature detect support).
Hydration is also handled automatically. You can use the same hydration directives such as `client:load`, `client:idle` and `client:visible` as you can with other libraries that Astro supports.
```astro
---
import { MyElement } from '../components/my-element.js';
---
<MyElement client:visible />
```
The above will only load the element's JavaScript when the user has scrolled it into view. Since it is server rendered they will not see any jank; it will load and hydrate transparently.
## Troubleshooting
For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
Common issues are listed below:
### Browser globals
The Lit integration's SSR works by adding a few browser global properties to the global environment. Some of the properties it adds includes `window`, `document`, and `location`.
These globals _can_ interfere with other libraries that might use the existence of these variables to detect that they are running in the browser, when they are actually running in the server. This can cause bugs with these libraries.
Because of this, the Lit integration might not be compatible with these types of libraries. One thing that can help is changing the order of integrations when Lit is interfering with other integrations:
```diff lang="js"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';
import lit from '@astrojs/lit';
export default defineConfig({
- integrations: [vue(), lit()]
+ integrations: [lit(), vue()]
});
```
The correct order might be different depending on the underlying cause of the problem. This is not guaranteed to fix every issue however, and some libraries cannot be used if you are using the Lit integration because of this.
### Strict package managers
When using a [strict package manager](https://pnpm.io/pnpm-vs-npm#npms-flat-tree) like `pnpm`, you may get an error such as `ReferenceError: module is not defined` when running your site. To fix this, hoist Lit dependencies with an `.npmrc` file:
```ini
# .npmrc
public-hoist-pattern[]=*lit*
```
### Limitations
The Lit integration is powered by `@lit-labs/ssr` which has some limitations. See their [limitations documentation](https://www.npmjs.com/package/@lit-labs/ssr#user-content-notes-and-limitations) to learn more.
- Submit bug reports and feature requests as [GitHub issues][issues].
## Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started:
[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
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]
## License
MIT
Copyright (c) 2023–present [Astro][astro]
[astro]: https://astro.build/
[docs]: https://docs.astro.build/en/guides/integrations-guide/lit/
[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md
[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
[discord]: https://astro.build/chat/
[issues]: https://github.com/withastro/astro/issues
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/

526
packages/integrations/markdoc/README.md
View file

@ -2,517 +2,37 @@
This **[Astro integration][astro-integration]** enables the usage of [Markdoc](https://markdoc.dev/) to create components, pages, and content collection entries.
- <strong>[Why Markdoc?](#why-markdoc)</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>
## Documentation
## Why Markdoc?
Read the [`@astrojs/markdoc` docs][docs]
Markdoc allows you to enhance your Markdown with [Astro components][astro-components]. If you have existing content authored in Markdoc, this integration allows you to bring those files to your Astro project using content collections.
## Support
## Installation
- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more!
### Quick Install
- Check our [Astro Integration Documentation][astro-integration] for more on integrations.
The `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 markdoc
# Using Yarn
yarn astro add markdoc
# Using PNPM
pnpm astro add markdoc
```
If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
### Manual Install
First, install the `@astrojs/markdoc` package using your package manager. If you're using npm or aren't sure, run this in the terminal:
```sh
npm install @astrojs/markdoc
```
Then, apply this integration to your `astro.config.*` file using the `integrations` property:
```diff lang="js" "markdoc()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import markdoc from '@astrojs/markdoc';
export default defineConfig({
// ...
integrations: [markdoc()],
// ^^^^^^^^^
});
```
### Editor Integration
[VS Code](https://code.visualstudio.com/) supports Markdown by default. However, for Markdoc editor support, you may wish to add the following setting in your VSCode config. This ensures authoring Markdoc files provides a Markdown-like editor experience.
```json title=".vscode/settings.json"
{
"files.associations": {
"*.mdoc": "markdown"
}
}
```
## Usage
Markdoc files can only be used within content collections. Add entries to any content collection using the `.mdoc` extension:
```sh
src/content/docs/
why-markdoc.mdoc
quick-start.mdoc
```
Then, query your collection using the [Content Collection APIs](https://docs.astro.build/en/guides/content-collections/#querying-collections):
```astro
---
import { getEntryBySlug } from 'astro:content';
const entry = await getEntryBySlug('docs', 'why-markdoc');
const { Content } = await entry.render();
---
<!--Access frontmatter properties with `data`-->
<h1>{entry.data.title}</h1>
<!--Render Markdoc contents with the Content component-->
<Content />
```
📚 See the [Astro Content Collection docs][astro-content-collections] for more information.
## Markdoc config
`@astrojs/markdoc` offers configuration options to use all of Markdoc's features and connect UI components to your content.
### Use Astro components as Markdoc tags
You can configure [Markdoc tags][markdoc-tags] that map to `.astro` components. You can add a new tag by creating a `markdoc.config.mjs|ts` file at the root of your project and configuring the `tag` attribute.
This example renders an `Aside` component, and allows a `type` prop to be passed as a string:
```js
// markdoc.config.mjs
import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
tags: {
aside: {
render: component('./src/components/Aside.astro'),
attributes: {
// Markdoc requires type defs for each attribute.
// These should mirror the `Props` type of the component
// you are rendering.
// See Markdoc's documentation on defining attributes
// https://markdoc.dev/docs/attributes#defining-attributes
type: { type: String },
},
},
},
});
```
This component can now be used in your Markdoc files with the `{% aside %}` tag. Children will be passed to your component's default slot:
```md
# Welcome to Markdoc 👋
{% aside type="tip" %}
Use tags like this fancy "aside" to add some _flair_ to your docs.
{% /aside %}
```
### Use Astro components from npm packages and TypeScript files
You may need to use Astro components exposed as named exports from TypeScript or JavaScript files. This is common when using npm packages and design systems.
You can pass the import name as the second argument to the `component()` function:
```js
// markdoc.config.mjs
import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
tags: {
tabs: {
render: component('@astrojs/starlight/components', 'Tabs'),
},
},
});
```
This generates the following import statement internally:
```ts
import { Tabs } from '@astrojs/starlight/components';
```
### Custom headings
`@astrojs/markdoc` automatically adds anchor links to your headings, and [generates a list of `headings` via the content collections API](https://docs.astro.build/en/guides/content-collections/#rendering-content-to-html). To further customize how headings are rendered, you can apply an Astro component [as a Markdoc node][markdoc-nodes].
This example renders a `Heading.astro` component using the `render` property:
```js
// markdoc.config.mjs
import { defineMarkdocConfig, nodes, component } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
nodes: {
heading: {
...nodes.heading, // Preserve default anchor link generation
render: component('./src/components/Heading.astro'),
},
},
});
```
All Markdown headings will render the `Heading.astro` component and pass the following `attributes` as component props:
- `level: number` The heading level 1 - 6
- `id: string` An `id` generated from the heading's text contents. This corresponds to the `slug` generated by the [content `render()` function](https://docs.astro.build/en/guides/content-collections/#rendering-content-to-html).
For example, the heading `### Level 3 heading!` will pass `level: 3` and `id: 'level-3-heading'` as component props.
### Syntax highlighting
`@astrojs/markdoc` provides [Shiki](https://github.com/shikijs/shiki) and [Prism](https://github.com/PrismJS) extensions to highlight your code blocks.
#### Shiki
Apply the `shiki()` extension to your Markdoc config using the `extends` property. You can optionally pass a shiki configuration object:
```js
// markdoc.config.mjs
import { defineMarkdocConfig } from '@astrojs/markdoc/config';
import shiki from '@astrojs/markdoc/shiki';
export default defineMarkdocConfig({
extends: [
shiki({
// Choose from Shiki's built-in themes (or add your own)
// Default: 'github-dark'
// https://github.com/shikijs/shiki/blob/main/docs/themes.md
theme: 'dracula',
// Enable word wrap to prevent horizontal scrolling
// Default: false
wrap: true,
// Pass custom languages
// Note: Shiki has countless langs built-in, including `.astro`!
// https://github.com/shikijs/shiki/blob/main/docs/languages.md
langs: [],
}),
],
});
```
#### Prism
Apply the `prism()` extension to your Markdoc config using the `extends` property.
```js
// markdoc.config.mjs
import { defineMarkdocConfig } from '@astrojs/markdoc/config';
import prism from '@astrojs/markdoc/prism';
export default defineMarkdocConfig({
extends: [prism()],
});
```
📚 To learn about configuring Prism stylesheets, [see our syntax highlighting guide](https://docs.astro.build/en/guides/markdown-content/#prism-configuration).
### Set the root HTML element
Markdoc wraps documents with an `<article>` tag by default. This can be changed from the `document` Markdoc node. This accepts an HTML element name or `null` if you prefer to remove the wrapper element:
```js
// markdoc.config.mjs
import { defineMarkdocConfig, nodes } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
nodes: {
document: {
...nodes.document, // Apply defaults for other options
render: null, // default 'article'
},
},
});
```
### Custom Markdoc nodes / elements
You may want to render standard Markdown elements, such as paragraphs and bolded text, as Astro components. For this, you can configure a [Markdoc node][markdoc-nodes]. If a given node receives attributes, they will be available as component props.
This example renders blockquotes with a custom `Quote.astro` component:
```js
// markdoc.config.mjs
import { defineMarkdocConfig, nodes, component } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
nodes: {
blockquote: {
...nodes.blockquote, // Apply Markdoc's defaults for other options
render: component('./src/components/Quote.astro'),
},
},
});
```
📚 [Find all of Markdoc's built-in nodes and node attributes on their documentation.](https://markdoc.dev/docs/nodes#built-in-nodes)
### Use client-side UI components
Tags and nodes are restricted to `.astro` files. To embed client-side UI components in Markdoc, [use a wrapper `.astro` component that renders a framework component](https://docs.astro.build/en/core-concepts/framework-components/#nesting-framework-components) with your desired `client:` directive.
This example wraps a React `Aside.tsx` component with a `ClientAside.astro` component:
```astro
---
// src/components/ClientAside.astro
import Aside from './Aside';
---
<Aside {...Astro.props} client:load />
```
This Astro component can now be passed to the `render` prop for any [tag][markdoc-tags] or [node][markdoc-nodes] in your config:
```js
// markdoc.config.mjs
import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
tags: {
aside: {
render: component('./src/components/ClientAside.astro'),
attributes: {
type: { type: String },
},
},
},
});
```
### Markdoc config
The `markdoc.config.mjs|ts` file accepts [all Markdoc configuration options](https://markdoc.dev/docs/config), including [tags](https://markdoc.dev/docs/tags) and [functions](https://markdoc.dev/docs/functions).
You can pass these options from the default export in your `markdoc.config.mjs|ts` file:
```js
// markdoc.config.mjs
import { defineMarkdocConfig } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
functions: {
getCountryEmoji: {
transform(parameters) {
const [country] = Object.values(parameters);
const countryToEmojiMap = {
japan: '🇯🇵',
spain: '🇪🇸',
france: '🇫🇷',
};
return countryToEmojiMap[country] ?? '🏳';
},
},
},
});
```
Now, you can call this function from any Markdoc content entry:
```md
¡Hola {% getCountryEmoji("spain") %}!
```
📚 [See the Markdoc documentation](https://markdoc.dev/docs/functions#creating-a-custom-function) for more on using variables or functions in your content.
### Markdoc Language Server
If you are using VS Code, there is an official [Markdoc language extension](https://marketplace.visualstudio.com/items?itemName=Stripe.markdoc-language-support) that includes syntax highlighting and autocomplete for configured tags. [See the language server on GitHub](https://github.com/markdoc/language-server.git) for more information.
To set up the extension, create a `markdoc.config.json` file into the project root with following content:
```json
[
{
"id": "my-site",
"path": "src/content",
"schema": {
"path": "markdoc.config.mjs",
"type": "esm",
"property": "default",
"watch": true
}
}
]
```
The `schema` property contains all information to configure the language server for Astro content collections. It accepts following properties:
- `path`: The path to the configuration file.
- `type`: The type of module your configuration file uses (`esm` allows `import` syntax).
- `property`: The exported property name that contains the configuration object.
- `watch`: Tell the server to watch for changes in the configuration.
The top-level `path` property tells the server where content is located. Since Markdoc is specific to content collections, you can use `src/content`.
### Pass Markdoc variables
You may need to pass [variables][markdoc-variables] to your content. This is useful when passing SSR parameters like A/B tests.
Variables can be passed as props via the `Content` component:
```astro
---
import { getEntryBySlug } from 'astro:content';
const entry = await getEntryBySlug('docs', 'why-markdoc');
const { Content } = await entry.render();
---
<!--Pass the `abTest` param as a variable-->
<Content abTestGroup={Astro.params.abTestGroup} />
```
Now, `abTestGroup` is available as a variable in `docs/why-markdoc.mdoc`:
```md
{% if $abTestGroup === 'image-optimization-lover' %}
Let me tell you about image optimization...
{% /if %}
```
To make a variable global to all Markdoc files, you can use the `variables` attribute from your `markdoc.config.mjs|ts`:
```js
import { defineMarkdocConfig } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
variables: {
environment: process.env.IS_PROD ? 'prod' : 'dev',
},
});
```
### Access frontmatter from your Markdoc content
To access frontmatter, you can pass the entry `data` property [as a variable](#pass-markdoc-variables) where you render your content:
```astro
---
import { getEntry } from 'astro:content';
const entry = await getEntry('docs', 'why-markdoc');
const { Content } = await entry.render();
---
<Content frontmatter={entry.data} />
```
This can now be accessed as `$frontmatter` in your Markdoc.
## Integration config options
The Astro Markdoc integration handles configuring Markdoc options and capabilities that are not available through the `markdoc.config.js` file.
### `allowHTML`
Enables writing HTML markup alongside Markdoc tags and nodes.
By default, Markdoc will not recognize HTML markup as semantic content.
To achieve a more Markdown-like experience, where HTML elements can be included alongside your content, set `allowHTML:true` as a `markdoc` integration option. This will enable HTML parsing in Markdoc markup.
```diff lang="js" "allowHTML: true"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import markdoc from '@astrojs/markdoc';
export default defineConfig({
// ...
+ integrations: [markdoc({ allowHTML: true })],
// ^^^^^^^^^^^^^^^
});
```
> **Warning**
> When `allowHTML` is enabled, HTML markup inside Markdoc documents will be rendered as actual HTML elements (including `<script>`), making attack vectors like XSS possible. Ensure that any HTML markup comes from trusted sources.
### `ignoreIndentation`
By default, any content that is indented by four spaces is treated as a code block. Unfortunately, this behavior makes it difficult to use arbitrary levels of indentation to improve the readability of documents with complex structure.
When using nested tags in Markdoc, it can be helpful to indent the content inside of tags so that the level of depth is clear. To support arbitrary indentation, we have to disable the indent-based code blocks and modify several other markdown-it parsing rules that account for indent-based code blocks. These changes can be applied by enabling the ignoreIndentation option.
```diff lang="js" "ignoreIndentation: true"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import markdoc from '@astrojs/markdoc';
export default defineConfig({
// ...
+ integrations: [markdoc({ ignoreIndentation: true })],
// ^^^^^^^^^^^^^^^^^^^^^^^
});
```
```md
# Welcome to Markdoc with indented tags 👋
# Note: Can use either spaces or tabs for indentation
{% custom-tag %}
{% custom-tag %} ### Tags can be indented for better readability
{% another-custom-tag %}
This is easier to follow when there is a lot of nesting
{% /another-custom-tag %}
{% /custom-tag %}
{% /custom-tag %}
```
## Examples
- The [Astro Markdoc starter template](https://github.com/withastro/astro/tree/latest/examples/with-markdoc) shows how to use Markdoc files in your Astro project.
## Troubleshooting
For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
- Submit bug reports and feature requests as [GitHub issues][issues].
## Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started:
## Changelog
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]
See [CHANGELOG.md](https://github.com/withastro/astro/tree/main/packages/integrations/markdoc/CHANGELOG.md) for a history of changes to this integration.
## License
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/
[astro-components]: https://docs.astro.build/en/core-concepts/astro-components/
[astro-content-collections]: https://docs.astro.build/en/guides/content-collections/
[markdoc-tags]: https://markdoc.dev/docs/tags
[markdoc-nodes]: https://markdoc.dev/docs/nodes
[markdoc-variables]: https://markdoc.dev/docs/variables
MIT
Copyright (c) 2023–present [Astro][astro]
[astro]: https://astro.build/
[docs]: https://docs.astro.build/en/guides/integrations-guide/markdoc/
[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md
[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
[discord]: https://astro.build/chat/
[issues]: https://github.com/withastro/astro/issues
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/

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

@ -2,257 +2,37 @@
This **[Astro integration][astro-integration]** enables the usage of [MDX](https://mdxjs.com/) components and allows you to create pages as `.mdx` files.
- <strong>[Why MDX?](#why-mdx)</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>
## Documentation
## Why MDX?
Read the [`@astrojs/mdx` docs][docs]
MDX allows you to [use variables, JSX expressions and components within Markdown content](https://docs.astro.build/en/guides/markdown-content/#mdx-only-features) in Astro. If you have existing content authored in MDX, this integration allows you to bring those files to your Astro project.
## Support
## Installation
- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more!
### Quick Install
- Check our [Astro Integration Documentation][astro-integration] for more on integrations.
The `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 mdx
# Using Yarn
yarn astro add mdx
# Using PNPM
pnpm astro add mdx
```
If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
### Manual Install
First, install the `@astrojs/mdx` package using your package manager. If you're using npm or aren't sure, run this in the terminal:
```sh
npm install @astrojs/mdx
```
Then, apply this integration to your `astro.config.*` file using the `integrations` property:
```diff lang="js" "mdx()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import mdx from '@astrojs/mdx';
export default defineConfig({
// ...
integrations: [mdx()],
// ^^^^^
});
```
### Editor Integration
For editor support in [VS Code](https://code.visualstudio.com/), install the [official MDX extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx).
For other editors, use the [MDX language server](https://github.com/mdx-js/mdx-analyzer/tree/main/packages/language-server).
## Usage
With the Astro MDX integration, you can [add MDX pages to your project](https://docs.astro.build/en/guides/markdown-content/#markdown-and-mdx-pages) by adding `.mdx` files within your `src/pages/` directory. You can also [import `.mdx` files](https://docs.astro.build/en/guides/markdown-content/#importing-markdown) into `.astro` files.
Astro's MDX integration adds extra features to standard MDX, including Markdown-style frontmatter. This allows you to use most of Astro's built-in Markdown features like a [special frontmatter `layout` property](https://docs.astro.build/en/guides/markdown-content/#frontmatter-layout).
See how MDX works in Astro with examples in our [Markdown & MDX guide](https://docs.astro.build/en/guides/markdown-content/).
Visit the [MDX docs](https://mdxjs.com/docs/what-is-mdx/) to learn about using standard MDX features.
## Configuration
Once the MDX integration is installed, no configuration is necessary to use `.mdx` files in your Astro project.
You can configure how your MDX is rendered with the following options:
- [Options inherited from Markdown config](#options-inherited-from-markdown-config)
- [`extendMarkdownConfig`](#extendmarkdownconfig)
- [`recmaPlugins`](#recmaplugins)
- [`optimize`](#optimize)
### Options inherited from Markdown config
All [`markdown` configuration options](https://docs.astro.build/en/reference/configuration-reference/#markdown-options) can be configured separately in the MDX integration. This includes remark and rehype plugins, syntax highlighting, and more. Options will default to those in your Markdown config ([see the `extendMarkdownConfig` option](#extendmarkdownconfig) to modify this).
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypeMinifyHtml from 'rehype-minify-html';
export default defineConfig({
integrations: [
mdx({
syntaxHighlight: 'shiki',
shikiConfig: { theme: 'dracula' },
remarkPlugins: [remarkToc],
rehypePlugins: [rehypeMinifyHtml],
remarkRehype: { footnoteLabel: 'Footnotes' },
gfm: false,
}),
],
});
```
:::caution
MDX does not support passing remark and rehype plugins as a string. You should install, import, and apply the plugin function instead.
:::
📚 See the [Markdown Options reference](https://docs.astro.build/en/reference/configuration-reference/#markdown-options) for a complete list of options.
### `extendMarkdownConfig`
- **Type:** `boolean`
- **Default:** `true`
MDX will extend [your project's existing Markdown configuration](https://docs.astro.build/en/reference/configuration-reference/#markdown-options) by default. To override individual options, you can specify their equivalent in your MDX configuration.
For example, say you need to disable GitHub-Flavored Markdown and apply a different set of remark plugins for MDX files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
markdown: {
syntaxHighlight: 'prism',
remarkPlugins: [remarkPlugin1],
gfm: true,
},
integrations: [
mdx({
// `syntaxHighlight` inherited from Markdown
// Markdown `remarkPlugins` ignored,
// only `remarkPlugin2` applied.
remarkPlugins: [remarkPlugin2],
// `gfm` overridden to `false`
gfm: false,
}),
],
});
```
You may also need to disable `markdown` config extension in MDX. For this, set `extendMarkdownConfig` to `false`:
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
markdown: {
remarkPlugins: [remarkPlugin1],
},
integrations: [
mdx({
// Markdown config now ignored
extendMarkdownConfig: false,
// No `remarkPlugins` applied
}),
],
});
```
### `recmaPlugins`
These are plugins that modify the output [estree](https://github.com/estree/estree) directly. This is useful for modifying or injecting JavaScript variables in your MDX files.
We suggest [using AST Explorer](https://astexplorer.net/) to play with estree outputs, and trying [`estree-util-visit`](https://unifiedjs.com/explore/package/estree-util-visit/) for searching across JavaScript nodes.
### `optimize`
- **Type:** `boolean | { customComponentNames?: string[] }`
This is an optional configuration setting to optimize the MDX output for faster builds and rendering via an internal rehype plugin. This may be useful if you have many MDX files and notice slow builds. However, this option may generate some unescaped HTML, so make sure your site's interactive parts still work correctly after enabling it.
This is disabled by default. To enable MDX optimization, add the following to your MDX integration configuration:
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
integrations: [
mdx({
optimize: true,
}),
],
});
```
#### `customComponentNames`
- **Type:** `string[]`
An optional property of `optimize` to prevent the MDX optimizer from handling any [custom components passed to imported MDX content via the components prop](https://docs.astro.build/en/guides/markdown-content/#custom-components-with-imported-mdx).
You will need to exclude these components from optimization as the optimizer eagerly converts content into a static string, which will break custom components that needs to be dynamically rendered.
For example, the intended MDX output of the following is `<Heading>...</Heading>` in place of every `"<h1>...</h1>"`:
```astro
---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---
<Content components={{ ...components, h1: Heading }} />
```
To configure optimization for this using the `customComponentNames` property, specify an array of HTML element names that should be treated as custom components:
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
integrations: [
mdx({
optimize: {
// Prevent the optimizer from handling `h1` elements
// These will be treated as custom components
customComponentNames: ['h1'],
},
}),
],
});
```
Note that if your MDX file [configures custom components using `export const components = { ... }`](https://docs.astro.build/en/guides/markdown-content/#assigning-custom-components-to-html-elements), then you do not need to manually configure this option. The optimizer will automatically detect them.
## Examples
- The [Astro MDX starter template](https://github.com/withastro/astro/tree/latest/examples/with-mdx) shows how to use MDX files in your Astro project.
## Troubleshooting
For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
- Submit bug reports and feature requests as [GitHub issues][issues].
## Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started:
## Changelog
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]
See [CHANGELOG.md](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/CHANGELOG.md) for a history of changes to this integration.
## License
[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
MIT
Copyright (c) 2023–present [Astro][astro]
[astro]: https://astro.build/
[docs]: https://docs.astro.build/en/guides/integrations-guide/mdx/
[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md
[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
[discord]: https://astro.build/chat/
[issues]: https://github.com/withastro/astro/issues
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/

245
packages/integrations/node/README.md
View file

@ -2,236 +2,37 @@
This adapter allows Astro to deploy your SSR site to Node targets.
- <strong>[Why Astro Node.js](#why-astro-nodejs)</strong>
- <strong>[Installation](#installation)</strong>
- <strong>[Configuration](#configuration)</strong>
- <strong>[Usage](#usage)</strong>
- <strong>[Troubleshooting](#troubleshooting)</strong>
- <strong>[Contributing](#contributing)</strong>
- <strong>[Changelog](#changelog)</strong>
## Documentation
## Why Astro Node.js
Read the [`@astrojs/node` docs][docs]
If you're using Astro as a static site builder—its behavior out of the box—you don't need an adapter.
## Support
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.
- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more!
[Node.js](https://nodejs.org/en/) is a JavaScript runtime for server-side code. @astrojs/node can be used either in standalone mode or as middleware for other http servers, such as [Express](https://expressjs.com/).
- Check our [Astro Integration Documentation][astro-integration] for more on integrations.
## Installation
Add the Node adapter to enable SSR in your Astro project 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.
```sh
# Using NPM
npx astro add node
# Using Yarn
yarn astro add node
# Using PNPM
pnpm astro add node
```
### Add dependencies manually
If you prefer to install the adapter manually instead, complete the following two steps:
1. Install the Node adapter to your project’s dependencies using your preferred package manager. If you’re using npm or aren’t sure, run this in the terminal:
```bash
npm install @astrojs/node
```
1. Add two new lines to your `astro.config.mjs` project configuration file.
```diff lang="js"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import node from '@astrojs/node';
export default defineConfig({
+ output: 'server',
+ adapter: node({
+ mode: 'standalone',
+ }),
});
```
## Configuration
@astrojs/node can be configured by passing options into the adapter function. The following options are available:
### Mode
Controls whether the adapter builds to `middleware` or `standalone` mode.
- `middleware` mode allows the built output to be used as middleware for another Node.js server, like Express.js or Fastify.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
export default defineConfig({
output: 'server',
adapter: node({
mode: 'middleware',
}),
});
```
- `standalone` mode builds to server that automatically starts with the entry module is run. This allows you to more easily deploy your build to a host without any additional code.
## Usage
First, [performing a build](https://docs.astro.build/en/guides/deploy/#building-your-site-locally). Depending on which `mode` selected (see above) follow the appropriate steps below:
### Middleware
The server entrypoint is built to `./dist/server/entry.mjs` by default. This module exports a `handler` function that can be used with any framework that supports the Node `request` and `response` objects.
For example, with Express:
```js
// run-server.mjs
import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';
const app = express();
// Change this based on your astro.config.mjs, `base` option.
// They should match. The default value is "/".
const base = '/';
app.use(base, express.static('dist/client/'));
app.use(ssrHandler);
app.listen(8080);
```
Or, with Fastify (>4):
```js
// run-server.mjs
import Fastify from 'fastify';
import fastifyMiddie from '@fastify/middie';
import fastifyStatic from '@fastify/static';
import { fileURLToPath } from 'node:url';
import { handler as ssrHandler } from './dist/server/entry.mjs';
const app = Fastify({ logger: true });
await app
.register(fastifyStatic, {
root: fileURLToPath(new URL('./dist/client', import.meta.url)),
})
.register(fastifyMiddie);
app.use(ssrHandler);
app.listen({ port: 8080 });
```
Additionally, you can also pass in an object to be accessed with `Astro.locals` or in Astro middleware:
```js
// run-server.mjs
import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';
const app = express();
app.use(express.static('dist/client/'));
app.use((req, res, next) => {
const locals = {
title: 'New title',
};
ssrHandler(req, res, next, locals);
});
app.listen(8080);
```
Note that middleware mode does not do file serving. You'll need to configure your HTTP framework to do that for you. By default the client assets are written to `./dist/client/`.
### Standalone
In standalone mode a server starts when the server entrypoint is run. By default it is built to `./dist/server/entry.mjs`. You can run it with:
```shell
node ./dist/server/entry.mjs
```
For standalone mode the server handles file serving in addition to the page and API routes.
#### Custom host and port
You can override the host and port the standalone server runs on by passing them as environment variables at runtime:
```shell
HOST=0.0.0.0 PORT=4321 node ./dist/server/entry.mjs
```
#### HTTPS
By default the standalone server uses HTTP. This works well if you have a proxy server in front of it that does HTTPS. If you need the standalone server to run HTTPS itself you need to provide your SSL key and certificate.
You can pass the path to your key and certification via the environment variables `SERVER_CERT_PATH` and `SERVER_KEY_PATH`. This is how you might pass them in bash:
```bash
SERVER_KEY_PATH=./private/key.pem SERVER_CERT_PATH=./private/cert.pem node ./dist/server/entry.mjs
```
#### Runtime environment variables
If an `.env` file containing environment variables is present when the build process is run, these values will be hard-coded in the output, just as when generating a static website.
During the build, the runtime variables must be absent from the `.env` file, and you must provide Astro with every environment variable to expect at run-time: `VARIABLE_1=placeholder astro build`. This signals to Astro that the actual value will be available when the built application is run. The placeholder value will be ignored by the build process, and Astro will use the value provided at run-time.
In the case of multiple run-time variables, store them in a seperate file (e.g. `.env.runtime`) from `.env`. Start the build with the following command:
```sh
export $(cat .env.runtime) && astro build
```
#### Assets
In standalone mode, assets in your `dist/client/` folder are served via the standalone server. You might be deploying these assets to a CDN, in which case the server will never actually be serving them. But in some cases, such as intranet sites, it's fine to serve static assets directly from the application server.
Assets in the `dist/client/_astro/` folder are the ones that Astro has built. These assets are all named with a hash and therefore can be given long cache headers. Internally the adapter adds this header for these assets:
```
Cache-Control: public, max-age=31536000, immutable
```
## Troubleshooting
### SyntaxError: Named export 'compile' not found
You may see this when running the entry script if it was built with npm or Yarn. This is a known issue that may be fixed in a future release. As a workaround, add `"path-to-regexp"` to the `noExternal` array:
```diff lang="js"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
export default defineConfig({
output: 'server',
adapter: node(),
+ vite: {
+ ssr: {
+ noExternal: ['path-to-regexp'],
+ },
+ },
});
```
For more help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
- Submit bug reports and feature requests as [GitHub issues][issues].
## Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started:
## Changelog
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]
See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration.
## License
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/
MIT
Copyright (c) 2023–present [Astro][astro]
[astro]: https://astro.build/
[docs]: https://docs.astro.build/en/guides/integrations-guide/node/
[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md
[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
[discord]: https://astro.build/chat/
[issues]: https://github.com/withastro/astro/issues
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/

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

@ -2,151 +2,37 @@
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>
## Documentation
## Why Astro Partytown
Read the [`@astrojs/partytown` docs][docs]
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).
## Support
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.
- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more!
The Astro Partytown integration installs Partytown for you and makes sure it's enabled on all of your pages.
- Check our [Astro Integration Documentation][astro-integration] for more on integrations.
## Installation
### Quick Install
The `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
pnpm astro add partytown
```
If you run into any issues, [feel free to report them to us on 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:
```diff lang="js" "partytown()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import partytown from '@astrojs/partytown';
export default defineConfig({
// ...
integrations: [partytown()],
// ^^^^^^^^^^^
});
```
## 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 lang="html"
- <script src="fancy-analytics.js"></script>
+ <script type="text/partytown" src="fancy-analytics.js"></script>
```
If you open the "Network" tab from [your browser's dev tools](https://developer.chrome.com/docs/devtools/open/), you should see the `partytown` proxy intercepting this request.
## Configuration
To configure this integration, pass a 'config' object to the `partytown()` function call in `astro.config.mjs`.
```js
// astro.config.mjs
// ...
export default defineConfig({
integrations: [
partytown({
config: {
// options go here
},
}),
],
});
```
This mirrors the [Partytown config object](https://partytown.builder.io/configuration).
### 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.
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.
```js
// astro.config.mjs
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.
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)
```js
// astro.config.mjs
export default defineConfig({
integrations: [
partytown({
// Example: Add dataLayer.push as a forwarding-event.
config: {
forward: ['dataLayer.push'],
},
}),
],
});
```
## Examples
- [Browse projects with Astro Partytown on GitHub](https://github.com/search?q=%22%40astrojs%2Fpartytown%22+path%3A**%2Fpackage.json&type=code) for more examples!
## Troubleshooting
- If you're getting a `Failed to fetch` error, make sure you're not using any browser extensions that are blocking the script.
For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
- Submit bug reports and feature requests as [GitHub issues][issues].
## Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started:
## Changelog
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]
See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration.
## License
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/
MIT
Copyright (c) 2023–present [Astro][astro]
[astro]: https://astro.build/
[docs]: https://docs.astro.build/en/guides/integrations-guide/partytown/
[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md
[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
[discord]: https://astro.build/chat/
[issues]: https://github.com/withastro/astro/issues
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/

183
packages/integrations/preact/README.md
View file

@ -2,174 +2,37 @@
This **[Astro integration][astro-integration]** enables server-side rendering and client-side hydration for your [Preact](https://preactjs.com/) components.
- <strong>[Why Preact?](#why-preact)</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>
## Documentation
## Why Preact?
Read the [`@astrojs/preact` docs][docs]
Preact is a library that lets you build interactive UI components for the web. If you want to build interactive features on your site using JavaScript, you may prefer using its component format instead of using browser APIs directly.
## Support
Preact is also a great choice if you have previously used React. Preact provides the same API as React, but in a much smaller 3kB package. It even supports rendering many React components using the `compat` configuration option (see below).
- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more!
**Want to learn more about Preact before using this integration?**
Check out [“Learn Preact in 10 minutes”](https://preactjs.com/tutorial), an interactive tutorial on their website.
- Check our [Astro Integration Documentation][astro-integration] for more on integrations.
## Installation
### Quick Install
The `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 preact
# Using Yarn
yarn astro add preact
# Using PNPM
pnpm astro add preact
```
If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
### Manual Install
First, install the `@astrojs/preact` package using your package manager. If you're using npm or aren't sure, run this in the terminal:
```sh
npm install @astrojs/preact
```
Most package managers will install associated peer dependencies as well. Still, if you see a "Cannot find package 'preact'" (or similar) warning when you start up Astro, you'll need to install Preact:
```sh
npm install preact
```
Then, apply this integration to your `astro.config.*` file using the `integrations` property:
```diff lang="js" "preact()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import preact from '@astrojs/preact';
export default defineConfig({
// ...
integrations: [preact()],
// ^^^^^^^^
});
```
## Usage
To use your first Preact component in Astro, head to our [UI framework documentation][astro-ui-frameworks]. You'll explore:
- 📦 how framework components are loaded,
- 💧 client-side hydration options, and
- 🤝 opportunities to mix and nest frameworks together
Also check our [Astro Integration Documentation][astro-integration] for more on integrations.
## Configuration
The Astro Preact integration handles how Preact components are rendered and it has its own options. Change these in the `astro.config.mjs` file which is where your project's integration settings live.
For basic usage, you do not need to configure the Preact integration.
### compat
You can enable `preact/compat`, Preact’s compatibility layer for rendering React components without needing to install or ship React’s larger libraries to your users’ web browsers.
To do so, pass an object to the Preact integration and set `compat: true`.
```js "compat: true"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
export default defineConfig({
integrations: [preact({ compat: true })],
// ^^^^^^^^^^^^
});
```
With the `compat` option enabled, the Preact integration will render React components as well as Preact components in your project and also allow you to import React components inside Preact components. Read more in [“Switching to Preact (from React)”](https://preactjs.com/guide/v10/switching-to-preact) on the Preact website.
When importing React component libraries, in order to swap out the `react` and `react-dom` dependencies as `preact/compat`, you can use [`overrides`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides) to do so.
```json title="package.json"
{
"overrides": {
"react": "npm:@preact/compat@latest",
"react-dom": "npm:@preact/compat@latest"
}
}
```
Check out the [`pnpm` overrides](https://pnpm.io/package_json#pnpmoverrides) and [`yarn` resolutions](https://yarnpkg.com/configuration/manifest#resolutions) docs for their respective overrides features.
> **Note**
> Currently, the `compat` option only works for React libraries that export code as ESM. If an error happens during build-time, try adding the library to `vite.ssr.noExternal: ['the-react-library']` in your `astro.config.mjs` file.
## Options
### Combining multiple JSX frameworks
When you are using multiple JSX frameworks (React, Preact, Solid) in the same project, Astro needs to determine which JSX framework-specific transformations should be used for each of your components. If you have only added one JSX framework integration to your project, no extra configuration is needed.
Use the `include` (required) and `exclude` (optional) configuration options to specify which files belong to which framework. Provide an array of files and/or folders to `include` for each framework you are using. Wildcards may be used to include multiple file paths.
We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required:
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';
export default defineConfig({
// Enable many frameworks to support all different kinds of components.
// No `include` is needed if you are only using a single JSX framework!
integrations: [
preact({
include: ['**/preact/*'],
}),
react({
include: ['**/react/*'],
}),
solid({
include: ['**/solid/*'],
}),
],
});
```
## Examples
- The [Astro Preact example](https://github.com/withastro/astro/tree/latest/examples/framework-preact) shows how to use an interactive Preact component in an Astro project.
- The [Astro Nanostores example](https://github.com/withastro/astro/tree/latest/examples/with-nanostores) shows how to share state between different components — and even different frameworks! — in an Astro project.
## Troubleshooting
For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
- Submit bug reports and feature requests as [GitHub issues][issues].
## Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started:
## Changelog
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]
See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration.
## License
[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
MIT
Copyright (c) 2023–present [Astro][astro]
[astro]: https://astro.build/
[docs]: https://docs.astro.build/en/guides/integrations-guide/preact/
[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md
[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
[discord]: https://astro.build/chat/
[issues]: https://github.com/withastro/astro/issues
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/

162
packages/integrations/react/README.md
View file

@ -2,149 +2,37 @@
This **[Astro integration][astro-integration]** enables server-side rendering and client-side hydration for your [React](https://react.dev/) components.
## Installation
## Documentation
There are two ways to add integrations to your project. Let's try the most convenient option first!
Read the [`@astrojs/react` docs][docs]
### `astro add` command
## Support
Astro includes a CLI tool for adding first party integrations: `astro add`. This command will:
- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more!
1. (Optionally) Install all necessary dependencies and peer dependencies
2. (Also optionally) Update your `astro.config.*` file to apply this integration
- Check our [Astro Integration Documentation][astro-integration] for more on integrations.
To install `@astrojs/react`, run the following from your project directory and follow the prompts:
```sh
# Using NPM
npx astro add react
# Using Yarn
yarn astro add react
# Using PNPM
pnpm astro add react
```
If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
### Install dependencies manually
First, install the `@astrojs/react` integration like so:
```sh
npm install @astrojs/react
```
Most package managers will install associated peer dependencies as well. Still, if you see a "Cannot find package 'react'" (or similar) warning when you start up Astro, you'll need to install `react` and `react-dom`:
```sh
npm install react react-dom
```
Now, apply this integration to your `astro.config.*` file using the `integrations` property:
```diff lang="js" "react()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import react from '@astrojs/react';
export default defineConfig({
// ...
integrations: [react()],
// ^^^^^^^
});
```
## Getting started
To use your first React component in Astro, head to our [UI framework documentation][astro-ui-frameworks]. You'll explore:
- 📦 how framework components are loaded,
- 💧 client-side hydration options, and
- 🤝 opportunities to mix and nest frameworks together
## Options
### Combining multiple JSX frameworks
When you are using multiple JSX frameworks (React, Preact, Solid) in the same project, Astro needs to determine which JSX framework-specific transformations should be used for each of your components. If you have only added one JSX framework integration to your project, no extra configuration is needed.
Use the `include` (required) and `exclude` (optional) configuration options to specify which files belong to which framework. Provide an array of files and/or folders to `include` for each framework you are using. Wildcards may be used to include multiple file paths.
We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required:
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';
export default defineConfig({
// Enable many frameworks to support all different kinds of components.
// No `include` is needed if you are only using a single JSX framework!
integrations: [
preact({
include: ['**/preact/*'],
}),
react({
include: ['**/react/*'],
}),
solid({
include: ['**/solid/*'],
}),
],
});
```
### Children parsing
Children passed into a React component from an Astro component are parsed as plain strings, not React nodes.
For example, the `<ReactComponent />` below will only receive a single child element:
```astro
---
import ReactComponent from './ReactComponent';
---
<ReactComponent>
<div>one</div>
<div>two</div>
</ReactComponent>
```
If you are using a library that _expects_ more than one child element to be passed, for example so that it can slot certain elements in different places, you might find this to be a blocker.
You can set the experimental flag `experimentalReactChildren` to tell Astro to always pass children to React as React vnodes. There is some runtime cost to this, but it can help with compatibility.
You can enable this option in the configuration for the React integration:
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
export default defineConfig({
// ...
integrations: [
react({
experimentalReactChildren: true,
}),
],
});
```
## Troubleshooting
For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
- Submit bug reports and feature requests as [GitHub issues][issues].
## Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started:
[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
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]
## License
MIT
Copyright (c) 2023–present [Astro][astro]
[astro]: https://astro.build/
[docs]: https://docs.astro.build/en/guides/integrations-guide/react/
[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md
[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
[discord]: https://astro.build/chat/
[issues]: https://github.com/withastro/astro/issues
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/

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

@ -2,358 +2,37 @@
This **[Astro integration][astro-integration]** generates a sitemap based on your pages when you build your Astro project.
- <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>
## Documentation
## Why Astro Sitemap
Read the [`@astrojs/sitemap` docs][docs]
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.
## Support
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.
- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more!
With Astro Sitemap, you don't have to worry about creating this XML file yourself: the Astro Sitemap integration will crawl your statically-generated routes and create the sitemap file, including [dynamic routes](https://docs.astro.build/en/core-concepts/routing/#dynamic-routes) like `[...slug]` or `src/pages/[lang]/[version]/info.astro` generated by `getStaticPaths()`.
- Check our [Astro Integration Documentation][astro-integration] for more on integrations.
This integration cannot generate sitemap entries for dynamic routes in [SSR mode](https://docs.astro.build/en/guides/server-side-rendering/).
## Installation
### Quick Install
The `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
pnpm astro add sitemap
```
If you run into any issues, [feel free to report them to us on 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:
```diff lang="js" "sitemap()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import sitemap from '@astrojs/sitemap';
export default defineConfig({
// ...
integrations: [sitemap()],
// ^^^^^^^^^
});
```
## 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:`.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
export default defineConfig({
// ...
site: 'https://stargazers.club',
integrations: [sitemap()],
});
```
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 will find both `sitemap-index.xml` and `sitemap-0.xml` in the `dist/` folder (or your custom [output directory](https://docs.astro.build/en/reference/configuration-reference/#outdir) if set).
> **Warning**
> If you forget to add a `site`, you'll get a friendly warning when you build, and the `sitemap-index.xml` file won't be generated.
After verifying that the sitemaps are built, you can add them to your site's `<head>` and the `robots.txt` file for crawlers to pick up.
```diff lang="html"
<!-- src/layouts/Layout.astro -->
<head>
+ <link rel="sitemap" href="/sitemap-index.xml" />
</head>
```
```diff
# public/robots.txt
User-agent: *
Allow: /
+ Sitemap: https://<YOUR SITE>/sitemap-index.xml
```
### Example of generated files for a two-page website
```xml title="sitemap-index.xml"
<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<sitemap>
<loc>https://stargazers.club/sitemap-0.xml</loc>
</sitemap>
</sitemapindex>
```
```xml title="sitemap-0.xml"
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">
<url>
<loc>https://stargazers.club/</loc>
</url>
<url>
<loc>https://stargazers.club/second-page/</loc>
</url>
</urlset>
```
## Configuration
To configure this integration, pass an object to the `sitemap()` function call in `astro.config.mjs`.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
export default defineConfig({
integrations: [
sitemap({
// configuration options
}),
],
});
```
### filter
All pages are included in your sitemap by default. By adding a custom `filter` function, you can filter included pages by URL.
```js
// astro.config.mjs
// ...
sitemap({
filter: (page) => page !== 'https://stargazers.club/secret-vip-lounge/',
});
```
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.
To filter multiple pages, add arguments with target URLs.
```js
// astro.config.mjs
// ...
sitemap({
filter: (page) =>
page !== 'https://stargazers.club/secret-vip-lounge-1/' &&
page !== 'https://stargazers.club/secret-vip-lounge-2/' &&
page !== 'https://stargazers.club/secret-vip-lounge-3/' &&
page !== 'https://stargazers.club/secret-vip-lounge-4/',
});
```
### 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.
```js
// astro.config.mjs
// ...
sitemap({
customPages: ['https://stargazers.club/external-page', 'https://stargazers.club/external-page2'],
});
```
### entryLimit
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).
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
export default defineConfig({
site: 'https://stargazers.club',
integrations: [
sitemap({
entryLimit: 10000,
}),
],
});
```
### changefreq, lastmod, and priority
These options correspond to the `<changefreq>`, `<lastmod>`, and `<priority>` 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.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
export default defineConfig({
site: 'https://stargazers.club',
integrations: [
sitemap({
changefreq: 'weekly',
priority: 0.7,
lastmod: new Date('2022-02-24'),
}),
],
});
```
### serialize
A function called for each sitemap entry just before writing to a disk. This function can be asynchronous.
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.
The example below shows the ability to add sitemap specific properties individually.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
export default defineConfig({
site: 'https://stargazers.club',
integrations: [
sitemap({
serialize(item) {
if (/exclude-from-sitemap/.test(item.url)) {
return undefined;
}
if (/your-special-page/.test(item.url)) {
item.changefreq = 'daily';
item.lastmod = new Date();
item.priority = 0.9;
}
return item;
},
}),
],
});
```
### i18n
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.
[Read more about language attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang).
[Read more about localization](https://developers.google.com/search/docs/advanced/crawling/localized-versions#all-method-guidelines).
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
export default defineConfig({
site: 'https://stargazers.club',
integrations: [
sitemap({
i18n: {
defaultLocale: 'en', // All urls that don't contain `es` or `fr` after `https://stargazers.club/` will be treated as default locale, i.e. `en`
locales: {
en: 'en-US', // The `defaultLocale` value must present in `locales` keys
es: 'es-ES',
fr: 'fr-CA',
},
},
}),
],
});
```
The resulting sitemap looks like this:
```xml
...
<url>
<loc>https://stargazers.club/</loc>
<xhtml:link rel="alternate" hreflang="en-US" href="https://stargazers.club/"/>
<xhtml:link rel="alternate" hreflang="es-ES" href="https://stargazers.club/es/"/>
<xhtml:link rel="alternate" hreflang="fr-CA" href="https://stargazers.club/fr/"/>
</url>
<url>
<loc>https://stargazers.club/es/</loc>
<xhtml:link rel="alternate" hreflang="en-US" href="https://stargazers.club/"/>
<xhtml:link rel="alternate" hreflang="es-ES" href="https://stargazers.club/es/"/>
<xhtml:link rel="alternate" hreflang="fr-CA" href="https://stargazers.club/fr/"/>
</url>
<url>
<loc>https://stargazers.club/fr/</loc>
<xhtml:link rel="alternate" hreflang="en-US" href="https://stargazers.club/"/>
<xhtml:link rel="alternate" hreflang="es-ES" href="https://stargazers.club/es/"/>
<xhtml:link rel="alternate" hreflang="fr-CA" href="https://stargazers.club/fr/"/>
</url>
<url>
<loc>https://stargazers.club/es/second-page/</loc>
<xhtml:link rel="alternate" hreflang="es-ES" href="https://stargazers.club/es/second-page/"/>
<xhtml:link rel="alternate" hreflang="fr-CA" href="https://stargazers.club/fr/second-page/"/>
<xhtml:link rel="alternate" hreflang="en-US" href="https://stargazers.club/second-page/"/>
</url>
...
```
## Examples
- The official Astro website uses Astro Sitemap to generate [its sitemap](https://astro.build/sitemap-index.xml).
- [Browse projects with Astro Sitemap on GitHub](https://github.com/search?q=%22%40astrojs%2Fsitemap%22+path%3Apackage.json&type=Code) for more examples!
## Troubleshooting
For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
- Submit bug reports and feature requests as [GitHub issues][issues].
## Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started:
## Changelog
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]
See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration.
## License
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/
MIT
Copyright (c) 2023–present [Astro][astro]
[astro]: https://astro.build/
[docs]: https://docs.astro.build/en/guides/integrations-guide/sitemap/
[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md
[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
[discord]: https://astro.build/chat/
[issues]: https://github.com/withastro/astro/issues
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/

124
packages/integrations/solid/README.md
View file

@ -2,111 +2,37 @@
This **[Astro integration][astro-integration]** enables server-side rendering and client-side hydration for your [SolidJS](https://www.solidjs.com/) components.
## Installation
## Documentation
There are two ways to add integrations to your project. Let's try the most convenient option first!
Read the [`@astrojs/solid-js` docs][docs]
### `astro add` command
## Support
Astro includes a CLI tool for adding first party integrations: `astro add`. This command will:
- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more!
1. (Optionally) Install all necessary dependencies and peer dependencies
2. (Also optionally) Update your `astro.config.*` file to apply this integration
- Check our [Astro Integration Documentation][astro-integration] for more on integrations.
To install `@astrojs/solid-js`, run the following from your project directory and follow the prompts:
```sh
# Using NPM
npx astro add solid
# Using Yarn
yarn astro add solid
# Using PNPM
pnpm astro add solid
```
If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
### Install dependencies manually
First, install the `@astrojs/solid-js` integration like so:
```sh
npm install @astrojs/solid-js
```
Most package managers will install associated peer dependencies as well. Still, if you see a "Cannot find package 'solid-js'" (or similar) warning when you start up Astro, you'll need to install SolidJS:
```sh
npm install solid-js
```
Now, apply this integration to your `astro.config.*` file using the `integrations` property:
```diff lang="js" "solid()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import solid from '@astrojs/solid-js';
export default defineConfig({
// ...
integrations: [solid()],
// ^^^^^^^
});
```
## Getting started
To use your first SolidJS component in Astro, head to our [UI framework documentation][astro-ui-frameworks]. You'll explore:
- 📦 how framework components are loaded,
- 💧 client-side hydration options, and
- 🤝 opportunities to mix and nest frameworks together
## Options
### Combining multiple JSX frameworks
When you are using multiple JSX frameworks (React, Preact, Solid) in the same project, Astro needs to determine which JSX framework-specific transformations should be used for each of your components. If you have only added one JSX framework integration to your project, no extra configuration is needed.
Use the `include` (required) and `exclude` (optional) configuration options to specify which files belong to which framework. Provide an array of files and/or folders to `include` for each framework you are using. Wildcards may be used to include multiple file paths.
We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required:
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';
export default defineConfig({
// Enable many frameworks to support all different kinds of components.
// No `include` is needed if you are only using a single JSX framework!
integrations: [
preact({
include: ['**/preact/*'],
}),
react({
include: ['**/react/*'],
}),
solid({
include: ['**/solid/*'],
}),
],
});
```
## Troubleshooting
For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
- Submit bug reports and feature requests as [GitHub issues][issues].
## Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started:
[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
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]
## License
MIT
Copyright (c) 2023–present [Astro][astro]
[astro]: https://astro.build/
[docs]: https://docs.astro.build/en/guides/integrations-guide/solid-js/
[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md
[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
[discord]: https://astro.build/chat/
[issues]: https://github.com/withastro/astro/issues
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/

136
packages/integrations/svelte/README.md
View file

@ -2,131 +2,37 @@
This **[Astro integration][astro-integration]** enables server-side rendering and client-side hydration for your [Svelte](https://svelte.dev/) components. It supports Svelte 3, 4, and 5 (experimental).
## Installation
## Documentation
There are two ways to add integrations to your project. Let's try the most convenient option first!
Read the [`@astrojs/svelte` docs][docs]
### `astro add` command
## Support
Astro includes a CLI tool for adding first party integrations: `astro add`. This command will:
- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more!
1. (Optionally) Install all necessary dependencies and peer dependencies
2. (Also optionally) Update your `astro.config.*` file to apply this integration
- Check our [Astro Integration Documentation][astro-integration] for more on integrations.
To install `@astrojs/svelte`, run the following from your project directory and follow the prompts:
```sh
# Using NPM
npx astro add svelte
# Using Yarn
yarn astro add svelte
# Using PNPM
pnpm astro add svelte
```
If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
### Install dependencies manually
First, install the `@astrojs/svelte` integration like so:
```sh
npm install @astrojs/svelte
```
Most package managers will install associated peer dependencies as well. Still, if you see a "Cannot find package 'svelte'" (or similar) warning when you start up Astro, you'll need to install Svelte:
```sh
npm install svelte
```
Now, apply this integration to your `astro.config.*` file using the `integrations` property:
```diff lang="js" "svelte()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import svelte from '@astrojs/svelte';
export default defineConfig({
// ...
integrations: [svelte()],
// ^^^^^^^^
});
```
## Getting started
To use your first Svelte component in Astro, head to our [UI framework documentation][astro-ui-frameworks]. You'll explore:
- 📦 how framework components are loaded,
- 💧 client-side hydration options, and
- 🤝 opportunities to mix and nest frameworks together
## Troubleshooting
For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
- Submit bug reports and feature requests as [GitHub issues][issues].
## Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started:
[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
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]
## Options
## License
This integration is powered by `@sveltejs/vite-plugin-svelte`. To customize the Svelte compiler, options can be provided to the integration. See the [`@sveltejs/vite-plugin-svelte` docs](https://github.com/sveltejs/vite-plugin-svelte/blob/HEAD/docs/config.md) for more details.
MIT
### Default options
Copyright (c) 2023–present [Astro][astro]
This integration passes the following default options to the Svelte compiler:
```js
const defaultOptions = {
emitCss: true,
compilerOptions: { dev: isDev, hydratable: true },
preprocess: vitePreprocess(),
};
```
These `emitCss`, `compilerOptions.dev`, and `compilerOptions.hydratable` values are required to build properly for Astro and cannot be overridden.
Providing your own `preprocess` options **will** override the [`vitePreprocess()`](https://github.com/sveltejs/vite-plugin-svelte/blob/HEAD/docs/preprocess.md) default. Make sure to enable the preprocessor flags needed for your project.
You can set options either by passing them to the `svelte` integration in `astro.config.mjs` or in `svelte.config.js`. Either of these would override the default `preprocess` setting:
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import svelte from '@astrojs/svelte';
export default defineConfig({
integrations: [svelte({ preprocess: [] })],
});
```
```js
// svelte.config.js
export default {
preprocess: [],
};
```
## Intellisense for TypeScript
**Added in:** `@astrojs/svelte@2.0.0`
If you're using a preprocessor like TypeScript or SCSS in your Svelte files, you can create a `svelte.config.js` file so that the Svelte IDE extension can correctly parse the Svelte files.
```js
// svelte.config.js
import { vitePreprocess } from '@astrojs/svelte';
export default {
preprocess: vitePreprocess(),
};
```
This config file will be automatically added for you when you run `astro add svelte`.
[astro]: https://astro.build/
[docs]: https://docs.astro.build/en/guides/integrations-guide/svelte/
[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md
[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
[discord]: https://astro.build/chat/
[issues]: https://github.com/withastro/astro/issues
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/

236
packages/integrations/tailwind/README.md
View file

@ -2,225 +2,37 @@
This **[Astro integration][astro-integration]** brings [Tailwind's](https://tailwindcss.com/) utility CSS classes to every `.astro` file and [framework component](https://docs.astro.build/en/core-concepts/framework-components/) in your project, along with support for the Tailwind configuration file.
- <strong>[Why Tailwind](#why-tailwind)</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>
## Documentation
## Why Tailwind?
Read the [`@astrojs/tailwind` docs][docs]
Tailwind lets you use utility classes instead of writing CSS. These utility classes are mostly one-to-one with a certain CSS property setting: for example, adding the `text-lg` to an element is equivalent to setting `font-size: 1.125rem` in CSS. You might find it easier to write and maintain your styles using these predefined utility classes!
## Support
If you don't like those predefined settings, you can [customize the Tailwind configuration file](https://tailwindcss.com/docs/configuration) to your project's design requirements. For example, if the "large text" in your design is actually `2rem`, you can [change the `lg` fontSize setting](https://tailwindcss.com/docs/font-size#customizing-your-theme) to `2rem`.
- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more!
Tailwind is also a great choice to add styles to React, Preact, or Solid components, which don't support a `<style>` tag in the component file.
- Check our [Astro Integration Documentation][astro-integration] for more on integrations.
Note: it's generally discouraged to use both Tailwind and another styling method (e.g. Styled Components) in the same file.
## Installation
https://user-images.githubusercontent.com/4033662/197398760-8fd30eff-4d13-449d-a598-00a6a1ac4644.mp4
### Quick Install
The `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 tailwind
# Using Yarn
yarn astro add tailwind
# Using PNPM
pnpm astro add tailwind
```
If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
### Manual Install
First, install the `@astrojs/tailwind` and `tailwindcss` packages using your package manager. If you're using npm or aren't sure, run this in the terminal:
```sh
npm install @astrojs/tailwind tailwindcss
```
Then, apply this integration to your `astro.config.*` file using the `integrations` property:
```diff lang="js" "tailwind()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import tailwind from '@astrojs/tailwind';
export default defineConfig({
// ...
integrations: [tailwind()],
// ^^^^^^^^^^
});
```
Then, create a `tailwind.config.cjs` file in your project's root directory. You can use the following command to generate a basic configuration file for you:
```sh
npx tailwindcss init
```
Finally, add this basic configuration to your `tailwind.config.cjs` file:
```diff lang="js" "content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}']"
// tailwind.config.cjs
/** @type {import('tailwindcss').Config} */
module.exports = {
+ content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
theme: {
extend: {},
},
plugins: [],
};
```
## Usage
When you install the integration, Tailwind's utility classes should be ready to go right away. Head to the [Tailwind docs](https://tailwindcss.com/docs/utility-first) to learn how to use Tailwind, and if you see a utility class you want to try, add it to any HTML element to your project!
[Autoprefixer](https://github.com/postcss/autoprefixer) is also set up automatically when working in dev mode, and for production builds, so Tailwind classes will work in older browsers.
https://user-images.githubusercontent.com/4033662/169918388-8ed153b2-0ba0-4b24-b861-d6e1cc800b6c.mp4
## Configuration
### Configuring Tailwind
If you used the Quick Install instructions and said yes to each prompt, you'll see a `tailwind.config.mjs` file in your project's root directory. Use this file for your Tailwind configuration changes. You can learn how to customize Tailwind using this file [in the Tailwind docs](https://tailwindcss.com/docs/configuration).
If it isn't there, you add your own `tailwind.config.(js|cjs|mjs)` file to the root directory and the integration will use its configurations. This can be great if you already have Tailwind configured in another project and want to bring those settings over to this one.
### Configuring the Integration
The Astro Tailwind integration handles the communication between Astro and Tailwind and it has its own options. Change these in the `astro.config.mjs` file (_not_ the Tailwind configuration file) which is where your project's integration settings live.
#### configFile
Previously known as `config.path` in `@astrojs/tailwind` v3. See the [v4 changelog](https://github.com/withastro/astro/blob/main/packages/integrations/tailwind/CHANGELOG.md#400) for updating your config.
If you want to use a different Tailwind configuration file instead of the default `tailwind.config.(js|cjs|mjs)`, specify that file's location using this integration's `configFile` option. If `configFile` is relative, it will be resolved relative to the current working directory.
> **Warning**
> Changing this isn't recommended since it can cause problems with other tools that integrate with Tailwind, like the official Tailwind VSCode extension.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';
export default defineConfig({
integrations: [
tailwind({
// Example: Provide a custom path to a Tailwind config file
configFile: './custom-config.cjs',
}),
],
});
```
#### applyBaseStyles
Previously known as `config.applyBaseStyles` in `@astrojs/tailwind` v3. See the [v4 changelog](https://github.com/withastro/astro/blob/main/packages/integrations/tailwind/CHANGELOG.md#400) for updating your config.
By default, the integration imports a basic `base.css` file on every page of your project. This basic CSS file includes the three main `@tailwind` directives:
```css
/* The integration's default injected base.css file */
@tailwind base;
@tailwind components;
@tailwind utilities;
```
To disable this default behavior, set `applyBaseStyles` to `false`. This can be useful if you need to define your own `base.css` file (to include a [`@layer` directive](https://tailwindcss.com/docs/functions-and-directives#layer), for example). This can also be useful if you do not want `base.css` to be imported on every page of your project.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
integrations: [
tailwind({
// Example: Disable injecting a basic `base.css` import on every page.
// Useful if you need to define and/or import your own custom `base.css`.
applyBaseStyles: false,
}),
],
});
```
You can now [import your own `base.css` as a local stylesheet](https://docs.astro.build/en/guides/styling/#import-a-local-stylesheet).
## Examples
- The [Astro Tailwind Starter](https://github.com/withastro/astro/tree/latest/examples/with-tailwindcss?on=github) gets you up and running with a base for your project that uses Tailwind for styling
- Astro's homepage uses Tailwind. Check out its [Tailwind configuration file](https://github.com/withastro/astro.build/blob/main/tailwind.config.ts) or an [example component](https://github.com/withastro/astro.build/blob/main/src/components/Checkbox.astro)
- The [Astro Ink](https://github.com/one-aalam/astro-ink), [Sarissa Blog](https://github.com/iozcelik/SarissaBlogAstroStarter), and [Creek](https://github.com/robertguss/Astro-Theme-Creek) themes use Tailwind for styling
- [Browse Astro Tailwind projects on GitHub](https://github.com/search?q=%22%40astrojs%2Ftailwind%22%3A+path%3A%2Fpackage.json&type=code) for more examples!
## Troubleshooting
### Class does not exist with `@apply` directives
When using the `@apply` directive in an Astro, Vue, Svelte, or another component integration's `<style>` tag, it may generate errors about your custom Tailwind class not existing and cause your build to fail.
```sh
error The `text-special` class does not exist. If `text-special` is a custom class, make sure it is defined within a `@layer` directive.
```
[Instead of using `@layer` directives in a global stylesheet](https://tailwindcss.com/docs/functions-and-directives#using-apply-with-per-component-css), define your custom styles by adding a plugin to your Tailwind config to fix it:
```js
// tailwind.config.mjs
export default {
// ...
plugins: [
function ({ addComponents, theme }) {
addComponents({
'.btn': {
padding: theme('spacing.4'),
margin: 'auto',
},
});
},
],
};
```
### Class-based modifiers do not work with `@apply` directives
Certain Tailwind classes with modifiers rely on combining classes across multiple elements. For example, `group-hover:text-gray` compiles to `.group:hover .text-gray`. When this is used with the `@apply` directive in Astro `<style>` tags, the compiled styles are removed from the build output because they do not match any markup in the `.astro` file. The same issue may also happen in framework components that support scoped styles like Vue and Svelte.
To fix this, you can use inline classes instead:
```html
<p class="text-black group-hover:text-gray">Astro</p>
```
### Others
- If your installation doesn't seem to be working, try restarting the dev server.
- If you edit and save a file and don't see your site update accordingly, try refreshing the page.
- If refreshing the page doesn't update your preview, or if a new installation doesn't seem to be working, then restart the dev server.
For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
[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
- Submit bug reports and feature requests as [GitHub issues][issues].
## Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started:
## Changelog
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]
See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration.
## License
MIT
Copyright (c) 2023–present [Astro][astro]
[astro]: https://astro.build/
[docs]: https://docs.astro.build/en/guides/integrations-guide/tailwind/
[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md
[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
[discord]: https://astro.build/chat/
[issues]: https://github.com/withastro/astro/issues
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/

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

@ -2,423 +2,37 @@
This adapter allows Astro to deploy your SSR site to [Vercel](https://www.vercel.com/).
Learn how to deploy your Astro site in our [Vercel deployment guide](https://docs.astro.build/en/guides/deploy/vercel/).
## Documentation
- <strong>[Why Astro Vercel](#why-astro-vercel)</strong>
- <strong>[Installation](#installation)</strong>
- <strong>[Usage](#usage)</strong>
- <strong>[Configuration](#configuration)</strong>
- <strong>[Troubleshooting](#troubleshooting)</strong>
- <strong>[Contributing](#contributing)</strong>
- <strong>[Changelog](#changelog)</strong>
Read the [`@astrojs/vercel` docs][docs]
## Why Astro Vercel
## Support
If you're using Astro as a static site builder — its behavior out of the box — you don't need an adapter.
- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more!
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.
- Check our [Astro Integration Documentation][astro-integration] for more on integrations.
[Vercel](https://www.vercel.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
Add the Vercel adapter to enable SSR in your Astro project 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.
```sh
# Using NPM
npx astro add vercel
# Using Yarn
yarn astro add vercel
# Using PNPM
pnpm astro add vercel
```
### Add dependencies manually
If you prefer to install the adapter manually instead, complete the following two steps:
1. Install the Vercel adapter to your project’s dependencies using your preferred package manager. If you’re using npm or aren’t sure, run this in the terminal:
```bash
npm install @astrojs/vercel
```
1. Add two new lines to your `astro.config.mjs` project configuration file.
```diff lang="js"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import vercel from '@astrojs/vercel/serverless';
export default defineConfig({
+ output: 'server',
+ adapter: vercel(),
});
```
### Targets
You can deploy to different targets:
- `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.
You can change where to target by changing the import:
```js
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:
```sh
astro build
vercel deploy --prebuilt
```
## Configuration
To configure this adapter, pass an object to the `vercel()` function call in `astro.config.mjs`:
### Web Analytics
**Type:** `VercelWebAnalyticsConfig`<br>
**Available for:** Serverless, Static<br>
**Added in:** `@astrojs/vercel@3.8.0`
You can enable [Vercel Web Analytics](https://vercel.com/docs/concepts/analytics) by setting `webAnalytics: { enabled: true }`. This will inject Vercel’s tracking scripts into all of your pages.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';
export default defineConfig({
output: 'server',
adapter: vercel({
webAnalytics: {
enabled: true,
},
}),
});
```
### Speed Insights
You can enable [Vercel Speed Insights](https://vercel.com/docs/concepts/speed-insights) by setting `speedInsights: { enabled: true }`. This will collect and send Web Vital data to Vercel.
**Type:** `VercelSpeedInsightsConfig`<br>
**Available for:** Serverless, Static<br>
**Added in:** `@astrojs/vercel@3.8.0`
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';
export default defineConfig({
output: 'server',
adapter: vercel({
speedInsights: {
enabled: true,
},
}),
});
```
### imagesConfig
**Type:** `VercelImageConfig`<br>
**Available for:** Serverless, Static
**Added in:** `@astrojs/vercel@3.3.0`
Configuration options for [Vercel's Image Optimization API](https://vercel.com/docs/concepts/image-optimization). See [Vercel's image configuration documentation](https://vercel.com/docs/build-output-api/v3/configuration#images) for a complete list of supported parameters.
The `domains` and `remotePatterns` properties will automatically be filled using [the Astro corresponding `image` settings](https://docs.astro.build/en/reference/configuration-reference/#image-options).
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/static';
export default defineConfig({
output: 'static',
adapter: vercel({
imagesConfig: {
sizes: [320, 640, 1280],
},
}),
});
```
### imageService
**Type:** `boolean`<br>
**Available for:** Serverless, Static
**Added in:** `@astrojs/vercel@3.3.0`
When enabled, an [Image Service](https://docs.astro.build/en/reference/image-service-reference/) powered by the Vercel Image Optimization API will be automatically configured and used in production. In development, the image service specified by [`devImageService`](#devimageservice) will be used instead.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/static';
export default defineConfig({
output: 'static',
adapter: vercel({
imageService: true,
}),
});
```
```astro
---
import { Image } from 'astro:assets';
import astroLogo from '../assets/logo.png';
---
<!-- This component -->
<Image src={astroLogo} alt="My super logo!" />
<!-- will become the following HTML -->
<img
src="/_vercel/image?url=_astro/logo.hash.png&w=...&q=..."
alt="My super logo!"
loading="lazy"
decoding="async"
width="..."
height="..."
/>
```
### devImageService
**Type:** `'sharp' | 'squoosh' | string`<br>
**Available for:** Serverless, Static
**Added in:** `@astrojs/vercel@3.3.0`
**Default**: 'sharp'
Allows you to configure which image service to use in development when [imageService](#imageservice) is enabled. This can be useful if you cannot install Sharp's dependencies on your development machine, but using another image service like Squoosh would allow you to preview images in your dev environment. Build is unaffected and will always use Vercel's Image Optimization.
It can also be set to any arbitrary value in order to use a custom image service instead of Astro's built-in ones.
```js
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';
export default defineConfig({
output: 'server',
adapter: vercel({
imageService: true,
devImageService: 'squoosh',
}),
});
```
### includeFiles
**Type:** `string[]`<br>
**Available for:** Serverless
Use this property to force files to be bundled with your function. This is helpful when you notice missing files.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';
export default defineConfig({
output: 'server',
adapter: vercel({
includeFiles: ['./my-data.json'],
}),
});
```
### excludeFiles
**Type:** `string[]`<br>
**Available for:** Serverless
Use this property to exclude any files from the bundling process that would otherwise be included.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';
export default defineConfig({
output: 'server',
adapter: vercel({
excludeFiles: ['./src/some_big_file.jpg'],
}),
});
```
### maxDuration
**Type:** `number`<br>
**Available for:** Serverless
Use this property to extend or limit the maximum duration (in seconds) that Serverless Functions can run before timing out. See the [Vercel documentation](https://vercel.com/docs/functions/serverless-functions/runtimes#maxduration) for the default and maximum limit for your account plan.
```diff lang="js"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';
export default defineConfig({
output: "server",
adapter: vercel({
+ maxDuration: 60
}),
});
```
### Function bundling configuration
The Vercel adapter combines all of your routes into a single function by default.
You also have the option to split builds into a separate function for each route using the `functionPerRoute` option. This reduces the size of each function, meaning you are less likely to exceed the size limit for an individual function. Also, code starts are faster.
Verify that your Vercel plan includes an appropriate number of functions before enabling `functionPerRoute`. For example, Vercel's free tier limits each deployment to no more than 12 functions. If your Vercel plan is insufficient for the number of routes in your project, you will receive an error message during deployment.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';
export default defineConfig({
output: 'server',
adapter: vercel({
functionPerRoute: true,
}),
});
```
### Vercel Edge Middleware
You can use Vercel Edge middleware to intercept a request and redirect before sending a response. Vercel middleware can run for Edge, SSR, and Static deployments. You may not need to install this package for your middleware. `@vercel/edge` is only required to use some middleware features such as geolocation. For more information see [Vercel’s middleware documentation](https://vercel.com/docs/concepts/functions/edge-middleware).
1. Add a `middleware.js` file to the root of your project:
```js
// middleware.js
export const config = {
// Only run the middleware on the admin route
matcher: '/admin',
};
export default function middleware(request) {
const url = new URL(request.url);
// You can retrieve IP location or cookies here.
if (url.pathname === '/admin') {
url.pathname = '/';
}
return Response.redirect(url);
}
```
1. While developing locally, you can run `vercel dev` to run middleware. In production, Vercel will handle this for you.
<!-- prettier-ignore -->
> **Warning**
> **Trying to rewrite?** Currently rewriting a request with middleware only works for static files.
### Vercel Edge Middleware with Astro middleware
The `@astrojs/vercel/serverless` adapter can automatically create the Vercel Edge middleware from an Astro middleware in your code base.
This is an opt-in feature, and the `edgeMiddleware` option needs to be set to `true`:
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';
export default defineConfig({
output: 'server',
adapter: vercel({
edgeMiddleware: true,
}),
});
```
Optionally, you can create a file recognized by the adapter named `vercel-edge-middleware.(js|ts)` in the [`srcDir`](https://docs.astro.build/en/reference/configuration-reference/#srcdir) folder to create [`Astro.locals`](https://docs.astro.build/en/reference/api-reference/#astrolocals).
Typings requires the [`@vercel/edge`](https://www.npmjs.com/package/@vercel/edge) package.
```js
// src/vercel-edge-middleware.js
/**
*
* @param options.request {Request}
* @param options.context {import("@vercel/edge").RequestContext}
* @returns {object}
*/
export default function ({ request, context }) {
// do something with request and context
return {
title: "Spider-man's blog",
};
}
```
If you use TypeScript, you can type the function as follows:
```ts
// src/vercel-edge-middleware.ts
import type { RequestContext } from '@vercel/edge';
export default function ({ request, context }: { request: Request; context: RequestContext }) {
// do something with request and context
return {
title: "Spider-man's blog",
};
}
```
The data returned by this function will be passed to Astro middleware.
The function:
- must export a **default** function;
- must **return** an `object`;
- accepts an object with a `request` and `context` as properties;
- `request` is typed as [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request);
- `context` is typed as [`RequestContext`](https://vercel.com/docs/concepts/functions/edge-functions/vercel-edge-package#requestcontext);
#### Limitations and constraints
When you opt in to this feature, there are few constraints to note:
- The Vercel Edge middleware will always be the **first** function to receive the `Request` and the last function to receive `Response`. This an architectural constraint that follows the [boundaries set by Vercel](https://vercel.com/docs/concepts/functions/edge-middleware).
- Only `request` and `context` may be used to produce an `Astro.locals` object. Operations like redirects, etc. should be delegated to Astro middleware.
- `Astro.locals` **must be serializable**. Failing to do so will result in a **runtime error**. This means that you **cannot** store complex types like `Map`, `function`, `Set`, etc.
### Node.js Version Support
The `@astrojs/vercel` adapter supports specific Node.js versions for deploying your Astro project on Vercel. To view the supported Node.js versions on Vercel, click on the settings tab for a project and scroll down to "Node.js Version" section.
Check out the [Vercel documentation](https://vercel.com/docs/functions/serverless-functions/runtimes/node-js#default-and-available-versions) to learn more.
## 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`.
For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
- Submit bug reports and feature requests as [GitHub issues][issues].
## Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started:
## Changelog
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]
See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration.
## License
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/
MIT
Copyright (c) 2023–present [Astro][astro]
[astro]: https://astro.build/
[docs]: https://docs.astro.build/en/guides/integrations-guide/vercel/
[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md
[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
[discord]: https://astro.build/chat/
[issues]: https://github.com/withastro/astro/issues
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/

164
packages/integrations/vue/README.md
View file

@ -2,159 +2,37 @@
This **[Astro integration][astro-integration]** enables server-side rendering and client-side hydration for your [Vue 3](https://vuejs.org/) components.
## Installation
## Documentation
There are two ways to add integrations to your project. Let's try the most convenient option first!
Read the [`@astrojs/vue` docs][docs]
### `astro add` command
## Support
Astro includes a CLI tool for adding first party integrations: `astro add`. This command will:
- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more!
1. (Optionally) Install all necessary dependencies and peer dependencies
2. (Also optionally) Update your `astro.config.*` file to apply this integration
- Check our [Astro Integration Documentation][astro-integration] for more on integrations.
To install `@astrojs/vue`, run the following from your project directory and follow the prompts:
```sh
# Using NPM
npx astro add vue
# Using Yarn
yarn astro add vue
# Using PNPM
pnpm astro add vue
```
If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
### Install dependencies manually
First, install the `@astrojs/vue` integration like so:
```sh
npm install @astrojs/vue
```
Most package managers will install associated peer dependencies as well. Still, if you see a "Cannot find package 'vue'" (or similar) warning when you start up Astro, you'll need to install Vue:
```sh
npm install vue
```
Now, apply this integration to your `astro.config.*` file using the `integrations` property:
```diff lang="js" "vue()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import vue from '@astrojs/vue';
export default defineConfig({
// ...
integrations: [vue()],
// ^^^^^
});
```
## Getting started
To use your first Vue component in Astro, head to our [UI framework documentation][astro-ui-frameworks]. You'll explore:
- 📦 how framework components are loaded,
- 💧 client-side hydration options, and
- 🤝 opportunities to mix and nest frameworks together
## Troubleshooting
For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
- Submit bug reports and feature requests as [GitHub issues][issues].
## Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started:
[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
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]
## Options
## License
This integration is powered by `@vitejs/plugin-vue`. To customize the Vue compiler, options can be provided to the integration. See the `@vitejs/plugin-vue` [docs](https://www.npmjs.com/package/@vitejs/plugin-vue) for more details.
MIT
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';
Copyright (c) 2023–present [Astro][astro]
export default defineConfig({
// ...
integrations: [
vue({
template: {
compilerOptions: {
// treat any tag that starts with ion- as custom elements
isCustomElement: (tag) => tag.startsWith('ion-'),
},
},
// ...
}),
],
});
```
### appEntrypoint
You can extend the Vue `app` instance setting the `appEntrypoint` option to a root-relative import specifier (for example, `appEntrypoint: "/src/pages/_app"`).
The default export of this file should be a function that accepts a Vue `App` instance prior to rendering, allowing the use of [custom Vue plugins](https://vuejs.org/guide/reusability/plugins.html), `app.use`, and other customizations for advanced use cases.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';
export default defineConfig({
integrations: [vue({ appEntrypoint: '/src/pages/_app' })],
});
```
```ts
// src/pages/_app.ts
import type { App } from 'vue';
import i18nPlugin from 'my-vue-i18n-plugin';
export default (app: App) => {
app.use(i18nPlugin);
};
```
### jsx
You can use Vue JSX by setting `jsx: true`.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';
export default defineConfig({
integrations: [vue({ jsx: true })],
});
```
This will enable rendering for both Vue and Vue JSX components. To customize the Vue JSX compiler, pass an options object instead of a boolean. See the `@vitejs/plugin-vue-jsx` [docs](https://www.npmjs.com/package/@vitejs/plugin-vue-jsx) for more details.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';
export default defineConfig({
integrations: [
vue({
jsx: {
// treat any tag that starts with ion- as custom elements
isCustomElement: (tag) => tag.startsWith('ion-'),
},
}),
],
});
```
[astro]: https://astro.build/
[docs]: https://docs.astro.build/en/guides/integrations-guide/vue/
[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md
[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
[discord]: https://astro.build/chat/
[issues]: https://github.com/withastro/astro/issues
[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/