ContextQMD
Back to Withastro

@astrojs/alpinejs

src/content/docs/en/guides/integrations-guide/alpinejs.mdx

latest4.5 KB
Original Source

import PackageManagerTabs from '/components/tabs/PackageManagerTabs.astro'; import Since from '/components/Since.astro';

This Astro integration adds Alpine.js to your project so that you can use Alpine.js anywhere on your page.

Installation

Astro includes an astro add command to automate the setup of official integrations. If you prefer, you can install integrations manually instead.

To install @astrojs/alpinejs, run the following from your project directory and follow the prompts:

<PackageManagerTabs> <Fragment slot="npm"> ```sh npx astro add alpinejs ``` </Fragment> <Fragment slot="pnpm"> ```sh pnpm astro add alpinejs ``` </Fragment> <Fragment slot="yarn"> ```sh yarn astro add alpinejs ``` </Fragment> </PackageManagerTabs>

If you run into any issues, feel free to report them to us on GitHub and try the manual installation steps below.

Manual Install

First, install the @astrojs/alpinejs package.

<PackageManagerTabs> <Fragment slot="npm"> ```sh npm install @astrojs/alpinejs ``` </Fragment> <Fragment slot="pnpm"> ```sh pnpm add @astrojs/alpinejs ``` </Fragment> <Fragment slot="yarn"> ```sh yarn add @astrojs/alpinejs ``` </Fragment> </PackageManagerTabs>

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:

<PackageManagerTabs> <Fragment slot="npm"> ```sh npm install alpinejs @types/alpinejs ``` </Fragment> <Fragment slot="pnpm"> ```sh pnpm add alpinejs @types/alpinejs ``` </Fragment> <Fragment slot="yarn"> ```sh yarn add alpinejs @types/alpinejs ``` </Fragment> </PackageManagerTabs>

Then, apply the integration to your astro.config.* file using the integrations property:

js
import { defineConfig } from 'astro/config';
import alpinejs from '@astrojs/alpinejs';

export default defineConfig({
  // ...
  integrations: [alpinejs()],
});

Configuration Options

entrypoint

<p>

Type: string

<Since v="0.4.0" pkg="@astrojs/alpinejs" /> </p>

You can extend Alpine by setting the entrypoint option to a root-relative import specifier (e.g. entrypoint: "/src/entrypoint").

The default export of this file should be a function that accepts an Alpine instance prior to starting. This allows the use of custom directives, plugins and other customizations for advanced use cases.

js
import { defineConfig } from 'astro/config';
import alpinejs from '@astrojs/alpinejs';

export default defineConfig({
  // ...
  integrations: [alpinejs({ entrypoint: '/src/entrypoint' })],
});
js
import type { Alpine } from 'alpinejs'
import intersect from '@alpinejs/intersect'

export default (Alpine: Alpine) => {
    Alpine.plugin(intersect)
}

Usage

Once the integration is installed, you can use Alpine.js directives and syntax inside any Astro component. The Alpine.js script is automatically added and enabled on every page of your website so no client directives are needed. Add plugin scripts to the page <head>.

The following example adds Alpine's Collapse plugin to expand and collapse paragraph text:

astro
---
---
<html>
	<head>
		<!-- ... -->
		<script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/[email protected]/dist/cdn.min.js"></script>
	</head>
	<body>
    <!-- ... -->
		<div x-data="{ expanded: false }">
			<button @click="expanded = ! expanded">Toggle Content</button>

			<p id="foo" x-show="expanded" x-collapse>
        Lorem ipsum
			</p>
		</div>
	</body>
</html>

Intellisense for TypeScript

The @astrojs/alpine integration adds Alpine to the global window object. For IDE autocompletion, add the following to your src/env.d.ts:

ts
interface Window {
  Alpine: import('alpinejs').Alpine;
}

Examples