From 7310e8a1780dff2ffb57f8a6cfd3d021d019f6b8 Mon Sep 17 00:00:00 2001 From: "Fred K. Schott" Date: Mon, 22 Aug 2022 11:25:57 -0700 Subject: [PATCH] add an alpine integration and update example (#4406) --- .changeset/purple-guests-fetch.md | 5 + examples/framework-alpine/astro.config.mjs | 4 +- examples/framework-alpine/package.json | 6 +- .../framework-alpine/src/pages/index.astro | 6 - packages/integrations/alpinejs/README.md | 108 ++++++++++++++++++ packages/integrations/alpinejs/package.json | 38 ++++++ packages/integrations/alpinejs/src/index.ts | 17 +++ packages/integrations/alpinejs/tsconfig.json | 10 ++ pnpm-lock.yaml | 19 ++- 9 files changed, 197 insertions(+), 16 deletions(-) create mode 100644 .changeset/purple-guests-fetch.md create mode 100644 packages/integrations/alpinejs/README.md create mode 100644 packages/integrations/alpinejs/package.json create mode 100644 packages/integrations/alpinejs/src/index.ts create mode 100644 packages/integrations/alpinejs/tsconfig.json diff --git a/.changeset/purple-guests-fetch.md b/.changeset/purple-guests-fetch.md new file mode 100644 index 000000000000..590dff82a1be --- /dev/null +++ b/.changeset/purple-guests-fetch.md @@ -0,0 +1,5 @@ +--- +'@astrojs/alpinejs': minor +--- + +Add new official Alpine.js integration diff --git a/examples/framework-alpine/astro.config.mjs b/examples/framework-alpine/astro.config.mjs index ade2c1278fd7..60bfc7d45d92 100644 --- a/examples/framework-alpine/astro.config.mjs +++ b/examples/framework-alpine/astro.config.mjs @@ -1,7 +1,7 @@ import { defineConfig } from 'astro/config'; +import alpine from '@astrojs/alpinejs'; // https://astro.build/config export default defineConfig({ - // No integrations are needed for AlpineJS support, just use Astro components! - integrations: [], + integrations: [alpine()], }); diff --git a/examples/framework-alpine/package.json b/examples/framework-alpine/package.json index 1832c35f4847..0841c8395e93 100644 --- a/examples/framework-alpine/package.json +++ b/examples/framework-alpine/package.json @@ -10,10 +10,10 @@ "astro": "astro" }, "devDependencies": { + "@astrojs/alpinejs": "^0.0.1", "@types/alpinejs": "^3.7.0", + "alpinejs": "^3.10.2", "astro": "^1.0.6" }, - "dependencies": { - "alpinejs": "^3.10.2" - } + "dependencies": {} } diff --git a/examples/framework-alpine/src/pages/index.astro b/examples/framework-alpine/src/pages/index.astro index 701ab551c3c2..ecfc8499c4b7 100644 --- a/examples/framework-alpine/src/pages/index.astro +++ b/examples/framework-alpine/src/pages/index.astro @@ -22,12 +22,6 @@ import Counter from '../components/Counter.astro'; padding: 2rem; } - - -
diff --git a/packages/integrations/alpinejs/README.md b/packages/integrations/alpinejs/README.md new file mode 100644 index 000000000000..63aadf9b17fb --- /dev/null +++ b/packages/integrations/alpinejs/README.md @@ -0,0 +1,108 @@ +# @astrojs/alpinejs ⚛️ + +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. + +- [Installation](#installation) +- [Usage](#usage) +- [Configuration](#configuration) +- [Examples](#examples) +- [Troubleshooting](#troubleshooting) +- [Contributing](#contributing) +- [Changelog](#changelog) + +## 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 +npm run astro add alpinejs +# Using Yarn +yarn astro add alpinejs +# Using PNPM +pnpm astro add alpinejs +``` + +Then, restart the dev server by typing `CTRL-C` and then `npm run astro dev` in the terminal window that was running Astro. + +### 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. Still, if you see a "Cannot find package 'alpinejs'" (or similar) warning when you start up Astro, you'll need to install Alpine.js yourself: + +```sh +npm install alpinejs @types/alpinejs +``` + +Then, apply this integration to your `astro.config.*` file using the `integrations` property: + +__`astro.config.mjs`__ + +```js +import { defineConfig } from 'astro/config'; +import alpine from '@astrojs/alpinejs'; + +export default defineConfig({ + // ... + integrations: [alpine()], +}); +``` + +Finally, restart the dev server. + +## Usage + +Once the integration is installed, you can use [Alpine.js](https://alpinejs.dev/) directivers 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 Apline.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 ` +``` + +## Configuration + +The Apline.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-threads` 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. + +## Contributing + +This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! + +## Changelog + +See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration. + +[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/alpinejs/package.json b/packages/integrations/alpinejs/package.json new file mode 100644 index 000000000000..7bbd2449c501 --- /dev/null +++ b/packages/integrations/alpinejs/package.json @@ -0,0 +1,38 @@ +{ + "name": "@astrojs/alpinejs", + "description": "The official Alpine.js integration for Astro.", + "version": "0.0.1", + "type": "module", + "types": "./dist/index.d.ts", + "author": "withastro", + "license": "MIT", + "repository": { + "type": "git", + "url": "https://github.com/withastro/astro.git", + "directory": "packages/integrations/alpinejs" + }, + "keywords": [ + "astro-integration", + "astro-component", + "performance" + ], + "bugs": "https://github.com/withastro/astro/issues", + "homepage": "https://astro.build", + "exports": { + ".": "./dist/index.js", + "./package.json": "./package.json" + }, + "scripts": { + "build": "astro-scripts build \"src/**/*.ts\" && tsc", + "build:ci": "astro-scripts build \"src/**/*.ts\"", + "dev": "astro-scripts dev \"src/**/*.ts\"" + }, + "peerDependencies": { + "@types/alpinejs": "^3.0.0", + "alpinejs": "^3.0.0" + }, + "devDependencies": { + "astro": "workspace:*", + "astro-scripts": "workspace:*" + } +} diff --git a/packages/integrations/alpinejs/src/index.ts b/packages/integrations/alpinejs/src/index.ts new file mode 100644 index 000000000000..4a296b8c1f50 --- /dev/null +++ b/packages/integrations/alpinejs/src/index.ts @@ -0,0 +1,17 @@ +import type { AstroIntegration } from 'astro'; + +export default function createPlugin(): AstroIntegration { + return { + name: '@astrojs/alpinejs', + hooks: { + 'astro:config:setup': ({ injectScript }) => { + // This gets injected into the user's page, so the import will pull + // from the project's version of Alpine.js in their package.json. + injectScript( + 'page', + `import Alpine from 'alpinejs'; window.Alpine = Alpine; Alpine.start();` + ); + }, + }, + }; +} diff --git a/packages/integrations/alpinejs/tsconfig.json b/packages/integrations/alpinejs/tsconfig.json new file mode 100644 index 000000000000..44baf375c882 --- /dev/null +++ b/packages/integrations/alpinejs/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../../tsconfig.base.json", + "include": ["src"], + "compilerOptions": { + "allowJs": true, + "module": "ES2020", + "outDir": "./dist", + "target": "ES2020" + } +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index aa901b7098d3..479f96f997d9 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -122,13 +122,14 @@ importers: examples/framework-alpine: specifiers: + '@astrojs/alpinejs': ^0.0.1 '@types/alpinejs': ^3.7.0 alpinejs: ^3.10.2 astro: ^1.0.6 - dependencies: - alpinejs: 3.10.3 devDependencies: + '@astrojs/alpinejs': link:../../packages/integrations/alpinejs '@types/alpinejs': 3.7.0 + alpinejs: 3.10.3 astro: link:../../packages/astro examples/framework-lit: @@ -2111,6 +2112,14 @@ importers: mocha: 9.2.2 uvu: 0.5.6 + packages/integrations/alpinejs: + specifiers: + astro: workspace:* + astro-scripts: workspace:* + devDependencies: + astro: link:../../astro + astro-scripts: link:../../../scripts + packages/integrations/cloudflare: specifiers: astro: workspace:* @@ -9163,7 +9172,7 @@ packages: resolution: {integrity: sha512-1tdfLmNjWG6t/CsPldh+foumYFo3cpyCHgBYQ34ylaMsJ+SNHQ1kApMIa8jN+i593zQuaw3AdWH0nJTARzCFhg==} dependencies: '@vue/shared': 3.1.5 - dev: false + dev: true /@vue/reactivity/3.2.37: resolution: {integrity: sha512-/7WRafBOshOc6m3F7plwzPeCu/RCVv9uMpOwa/5PiY1Zz+WLVRWiy0MYKwmg19KBdGtFWsmZ4cD+LOdVPcs52A==} @@ -9194,7 +9203,7 @@ packages: /@vue/shared/3.1.5: resolution: {integrity: sha512-oJ4F3TnvpXaQwZJNF3ZK+kLPHKarDmJjJ6jyzVNDKH9md1dptjC7lWR//jrGuLdek/U6iltWxqAnYOu8gCiOvA==} - dev: false + dev: true /@vue/shared/3.2.37: resolution: {integrity: sha512-4rSJemR2NQIo9Klm1vabqWjD8rs/ZaJSzMxkMNeJS6lHiUjjUeYFbooN19NgFjztubEKh3WlZUeOLVdbbUWHsw==} @@ -9317,7 +9326,7 @@ packages: resolution: {integrity: sha512-nt/w4hLq9pPaexCsHmO5zV5Alvq4yu9n0Iclti6aV0HmiqLWH/axUb0pn8z3XVuVNcj8EOXOQw+WpwPzMzLBWg==} dependencies: '@vue/reactivity': 3.1.5 - dev: false + dev: true /ansi-align/3.0.1: resolution: {integrity: sha512-IOfwwBF5iczOjp/WeY4YxyjqAFMQoZufdQWDd19SEExbVLNXqvpzSJ/M7Za4/sCPmQ0+GRquoA7bGcINcxew6w==}