Skip to content

Commit

Permalink
[docs] minimal integration READMEs (#9479)
Browse files Browse the repository at this point in the history
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>
4 people authored Dec 21, 2023

Unverified

This user has not yet uploaded their public signing key.
1 parent f9c4bbf commit 1baf0b0
Showing 15 changed files with 324 additions and 2,944 deletions.
18 changes: 18 additions & 0 deletions .changeset/soft-sheep-glow.md
Original file line number Diff line number Diff line change
@@ -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
116 changes: 22 additions & 94 deletions packages/integrations/alpinejs/README.md
Original file line number Diff line number Diff line change
@@ -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.
- Submit bug reports and feature requests as [GitHub issues][issues].

### 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!
## Contributing

You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
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:

## Contributing
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]

This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
## License

## Changelog
MIT

See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration.
Copyright (c) 2023–present [Astro][astro]

[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
[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/
163 changes: 22 additions & 141 deletions packages/integrations/lit/README.md
Original file line number Diff line number Diff line change
@@ -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:
- Submit bug reports and feature requests as [GitHub issues][issues].

```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:
## Contributing

```ini
# .npmrc
public-hoist-pattern[]=*lit*
```
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:

### Limitations
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]

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.
## License

## Contributing
MIT

This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
Copyright (c) 2023–present [Astro][astro]

[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
[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/
524 changes: 22 additions & 502 deletions packages/integrations/markdoc/README.md

Large diffs are not rendered by default.

264 changes: 22 additions & 242 deletions packages/integrations/mdx/README.md
Original file line number Diff line number Diff line change
@@ -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.
- Submit bug reports and feature requests as [GitHub issues][issues].

```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!
## Contributing

You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
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:

## Contributing
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]

This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
## License

## Changelog
MIT

See [CHANGELOG.md](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/CHANGELOG.md) for a history of changes to this integration.
Copyright (c) 2023–present [Astro][astro]

[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
[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/
243 changes: 22 additions & 221 deletions packages/integrations/node/README.md
Original file line number Diff line number Diff line change
@@ -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
- Submit bug reports and feature requests as [GitHub issues][issues].

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!
## Contributing

You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
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:

## Contributing
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]

This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
## License

## Changelog
MIT

See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration.
Copyright (c) 2023–present [Astro][astro]

[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/
[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/
158 changes: 22 additions & 136 deletions packages/integrations/partytown/README.md
Original file line number Diff line number Diff line change
@@ -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
- Submit bug reports and feature requests as [GitHub issues][issues].

### 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!
## Contributing

You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
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:

## Contributing
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]

This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
## License

## Changelog
MIT

See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration.
Copyright (c) 2023–present [Astro][astro]

[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/
[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/
181 changes: 22 additions & 159 deletions packages/integrations/preact/README.md
Original file line number Diff line number Diff line change
@@ -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
- Submit bug reports and feature requests as [GitHub issues][issues].

### 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!
## Contributing

You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
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:

## Contributing
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]

This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
## License

## Changelog
MIT

See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration.
Copyright (c) 2023–present [Astro][astro]

[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
[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/
156 changes: 22 additions & 134 deletions packages/integrations/react/README.md
Original file line number Diff line number Diff line change
@@ -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:
- Submit bug reports and feature requests as [GitHub issues][issues].

```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,
}),
],
});
```
## Contributing

## Troubleshooting
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:

For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]

You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
## License

## Contributing
MIT

This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
Copyright (c) 2023–present [Astro][astro]

[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
[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/
365 changes: 22 additions & 343 deletions packages/integrations/sitemap/README.md
Original file line number Diff line number Diff line change
@@ -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/).
- Submit bug reports and feature requests as [GitHub issues][issues].

## 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!
## Contributing

You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
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:

## Contributing
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]

This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
## License

## Changelog
MIT

See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration.
Copyright (c) 2023–present [Astro][astro]

[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/
[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/
118 changes: 22 additions & 96 deletions packages/integrations/solid/README.md
Original file line number Diff line number Diff line change
@@ -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:
- Submit bug reports and feature requests as [GitHub issues][issues].

```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/*'],
}),
],
});
```
## Contributing

## Troubleshooting
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:

For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]

You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
## License

## Contributing
MIT

This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
Copyright (c) 2023–present [Astro][astro]

[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
[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 changes: 21 additions & 115 deletions packages/integrations/svelte/README.md
Original file line number Diff line number Diff line change
@@ -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!

[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

## Options

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.

### Default options

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

**Added in:** `@astrojs/svelte@2.0.0`
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]

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.
## License

```js
// svelte.config.js
import { vitePreprocess } from '@astrojs/svelte';
MIT

export default {
preprocess: vitePreprocess(),
};
```
Copyright (c) 2023–present [Astro][astro]

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/
232 changes: 22 additions & 210 deletions packages/integrations/tailwind/README.md
Original file line number Diff line number Diff line change
@@ -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.
- Submit bug reports and feature requests as [GitHub issues][issues].

## 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!
## Contributing

You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.
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]

## Contributing
## License

This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
MIT

## Changelog
Copyright (c) 2023–present [Astro][astro]

See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration.
[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/
430 changes: 22 additions & 408 deletions packages/integrations/vercel/README.md

Large diffs are not rendered by default.

164 changes: 21 additions & 143 deletions packages/integrations/vue/README.md
Original file line number Diff line number Diff line change
@@ -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!

[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

## Options

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.

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';

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`.
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:

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';
- [Contributor Manual][contributing]
- [Code of Conduct][coc]
- [Community Guide][community]

export default defineConfig({
integrations: [vue({ jsx: true })],
});
```
## License

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.
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({
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/

0 comments on commit 1baf0b0

Please sign in to comment.