diff --git a/packages/integrations/lit/README.md b/packages/integrations/lit/README.md new file mode 100644 index 000000000..f8dd0349a --- /dev/null +++ b/packages/integrations/lit/README.md @@ -0,0 +1,119 @@ +# @astrojs/lit ๐Ÿ”ฅ + +This **[Astro integration][astro-integration]** enables server-side rendering and client-side hydration for your [Lit](https://lit.dev/) custom elements. + +## Installation + +There are two ways to add integrations to your project. Let's try the most convenient option first! + +### (experimental) `astro add` command + +Astro includes a CLI tool for adding first party integrations: `astro add`. This command will: +1. (Optionally) Install all necessary dependencies and peer dependencies +2. (Also optionally) Update your `astro.config.*` file to apply this integration + +To install `@astrojs/lit`, run the following from your project directory and follow the prompts: + +```sh +# Using NPM +npx astro add lit +# Using Yarn +yarn astro add lit +# Using PNPM +pnpx astro add lit +``` + +If you run into any hiccups, [feel free to log an issue on our GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below. + +### Install dependencies manually + +First, install the `@astrojs/lit` integration like so: + +``` +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: + +__astro.config.mjs__ + +```js +import lit from '@astrojs/lit'; + +export default { + // ... + 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 + +However, there's a key difference with Lit _custom elements_ over conventional _components_: you can use the element tag name directly. + +Astro needs to know which tag is associated with which component script. We expose this through exporting a `tagName` variable from the component script. It looks like this: + +__src/components/my-element.js__ + +```js +import { LitElement, html } from 'lit'; + +export const tagName = 'my-element'; + +class MyElement extends LitElement { + render() { + return html`

Hello world! From my-element

`; + } +} + +customElements.define(tagName, MyElement); +``` + +> Note that exporting the `tagName` is __required__ if you want to use the tag name in your templates. Otherwise you can export and use the constructor, like with non custom element frameworks. + +In your Astro template import this component as a side-effect and use the element. + +__src/pages/index.astro__ + +```astro +--- +import '../components/my-element.js'; +--- + + +``` + +> 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 '../components/my-element.js'; +--- + + +``` + +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. + +### More documentation + +Check our [Astro Integration Documentation][astro-integration] for more on integrations. + +[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/ +[astro-ui-frameworks]: https://docs.astro.build/en/core-concepts/framework-components/#using-framework-components diff --git a/packages/integrations/preact/README.md b/packages/integrations/preact/README.md new file mode 100644 index 000000000..ccae01b83 --- /dev/null +++ b/packages/integrations/preact/README.md @@ -0,0 +1,65 @@ +# @astrojs/preact โš›๏ธ + +This **[Astro integration][astro-integration]** enables server-side rendering and client-side hydration for your [Preact](https://preactjs.com/) components. + +## Installation + +There are two ways to add integrations to your project. Let's try the most convenient option first! + +### (experimental) `astro add` command + +Astro includes a CLI tool for adding first party integrations: `astro add`. This command will: +1. (Optionally) Install all necessary dependencies and peer dependencies +2. (Also optionally) Update your `astro.config.*` file to apply this integration + +To install `@astrojs/preact`, run the following from your project directory and follow the prompts: + +```sh +# Using NPM +npx astro add preact +# Using Yarn +yarn astro add preact +# Using PNPM +pnpx astro add preact +``` + +If you run into any hiccups, [feel free to log an issue on our GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below. + +### Install dependencies manually + +First, install the `@astrojs/preact` integration like so: + +``` +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 +``` + +Now, apply this integration to your `astro.config.*` file using the `integrations` property: + +__astro.config.mjs__ + +```js +import preact from '@astrojs/preact'; + +export default { + // ... + integrations: [preact()], +} +``` + +## Getting started + +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. + +[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/ +[astro-ui-frameworks]: https://docs.astro.build/en/core-concepts/framework-components/#using-framework-components diff --git a/packages/integrations/react/README.md b/packages/integrations/react/README.md new file mode 100644 index 000000000..ee2244d44 --- /dev/null +++ b/packages/integrations/react/README.md @@ -0,0 +1,65 @@ +# @astrojs/react โš›๏ธ + +This **[Astro integration][astro-integration]** enables server-side rendering and client-side hydration for your [React](https://reactjs.org/) components. + +## Installation + +There are two ways to add integrations to your project. Let's try the most convenient option first! + +### (experimental) `astro add` command + +Astro includes a CLI tool for adding first party integrations: `astro add`. This command will: +1. (Optionally) Install all necessary dependencies and peer dependencies +2. (Also optionally) Update your `astro.config.*` file to apply this integration + +To install `@astrojs/react`, run the following from your project directory and follow the prompts: + +```sh +# Using NPM +npx astro add react +# Using Yarn +yarn astro add react +# Using PNPM +pnpx astro add react +``` + +If you run into any hiccups, [feel free to log an issue on our GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below. + +### Install dependencies manually + +First, install the `@astrojs/react` integration like so: + +``` +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: + +__astro.config.mjs__ + +```js +import react from '@astrojs/react'; + +export default { + // ... + 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 + +Also check our [Astro Integration Documentation][astro-integration] for more on integrations. + +[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/ +[astro-ui-frameworks]: https://docs.astro.build/en/core-concepts/framework-components/#using-framework-components \ No newline at end of file diff --git a/packages/integrations/solid/README.md b/packages/integrations/solid/README.md new file mode 100644 index 000000000..bb8c6b848 --- /dev/null +++ b/packages/integrations/solid/README.md @@ -0,0 +1,65 @@ +# @astrojs/solid ๐Ÿ’™ + +This **[Astro integration][astro-integration]** enables server-side rendering and client-side hydration for your [SolidJS](https://www.solidjs.com/) components. + +## Installation + +There are two ways to add integrations to your project. Let's try the most convenient option first! + +### (experimental) `astro add` command + +Astro includes a CLI tool for adding first party integrations: `astro add`. This command will: +1. (Optionally) Install all necessary dependencies and peer dependencies +2. (Also optionally) Update your `astro.config.*` file to apply this integration + +To install `@astrojs/solid`, run the following from your project directory and follow the prompts: + +```sh +# Using NPM +npx astro add solid +# Using Yarn +yarn astro add solid +# Using PNPM +pnpx astro add solid +``` + +If you run into any hiccups, [feel free to log an issue on our GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below. + +### Install dependencies manually + +First, install the `@astrojs/solid` integration like so: + +``` +npm install @astrojs/solid +``` + +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: + +__astro.config.mjs__ + +```js +import solid from '@astrojs/solid'; + +export default { + // ... + 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 + +Also check our [Astro Integration Documentation][astro-integration] for more on integrations. + +[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/ +[astro-ui-frameworks]: https://docs.astro.build/en/core-concepts/framework-components/#using-framework-components \ No newline at end of file diff --git a/packages/integrations/svelte/README.md b/packages/integrations/svelte/README.md new file mode 100644 index 000000000..e5bce561a --- /dev/null +++ b/packages/integrations/svelte/README.md @@ -0,0 +1,65 @@ +# @astrojs/svelte ๐Ÿงก + +This **[Astro integration][astro-integration]** enables server-side rendering and client-side hydration for your [Svelte](https://svelte.dev/) components. + +## Installation + +There are two ways to add integrations to your project. Let's try the most convenient option first! + +### (experimental) `astro add` command + +Astro includes a CLI tool for adding first party integrations: `astro add`. This command will: +1. (Optionally) Install all necessary dependencies and peer dependencies +2. (Also optionally) Update your `astro.config.*` file to apply this integration + +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 +pnpx astro add svelte +``` + +If you run into any hiccups, [feel free to log an issue on our GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below. + +### Install dependencies manually + +First, install the `@astrojs/svelte` integration like so: + +``` +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: + +__astro.config.mjs__ + +```js +import svelte from '@astrojs/svelte'; + +export default { + // ... + 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 + +Also check our [Astro Integration Documentation][astro-integration] for more on integrations. + +[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/ +[astro-ui-frameworks]: https://docs.astro.build/en/core-concepts/framework-components/#using-framework-components diff --git a/packages/integrations/vue/README.md b/packages/integrations/vue/README.md new file mode 100644 index 000000000..e9a55d3da --- /dev/null +++ b/packages/integrations/vue/README.md @@ -0,0 +1,65 @@ +# @astrojs/vue ๐Ÿ’š + +This **[Astro integration][astro-integration]** enables server-side rendering and client-side hydration for your [Vue 3](https://vuejs.org/) components. + +## Installation + +There are two ways to add integrations to your project. Let's try the most convenient option first! + +### (experimental) `astro add` command + +Astro includes a CLI tool for adding first party integrations: `astro add`. This command will: +1. (Optionally) Install all necessary dependencies and peer dependencies +2. (Also optionally) Update your `astro.config.*` file to apply this integration + +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 +pnpx astro add vue +``` + +If you run into any hiccups, [feel free to log an issue on our GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below. + +### Install dependencies manually + +First, install the `@astrojs/vue` integration like so: + +``` +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: + +__astro.config.mjs__ + +```js +import vue from '@astrojs/vue'; + +export default { + // ... + 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 + +Also check our [Astro Integration Documentation][astro-integration] for more on integrations. + +[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/ +[astro-ui-frameworks]: https://docs.astro.build/en/core-concepts/framework-components/#using-framework-components