diff --git a/BUNDLERS.md b/BUNDLERS.md index c88bf1f..d83b179 100644 --- a/BUNDLERS.md +++ b/BUNDLERS.md @@ -2,11 +2,11 @@ This project has non-ESM dependencies, which unfortunately cannot be *bundled* in with your other app code. Modern bundlers unfortunately don't out-of-the-box support configurations that can handle such a situation. -As such, this project provides plugins for Vite and Webpack, to take care of the various steps needed to get these non-ESM dependencies into an otherwise bundled web app built by those tools. +As such, this project provides plugins for Astro, Vite, and Webpack, to take care of the various steps needed to get these non-ESM dependencies into an otherwise bundled web app built by those tools. ## Bundler Plugins -The plugins for Vite and Webpack are included in the `bundler-plugins/` directory. They should handle all necessary steps to load the dependencies. +The plugins for Astro, Vite, and Webpack are included in the `bundler-plugins/` directory. They should handle all necessary steps to load the dependencies. **Note:** You should not need to manually copy any files out of the `dist/bundlers/` directory, as the plugins access the `qr-data-sync` dependency (in `node_modules`) directly to pull the files needed. But for reference, the files these plugins access are: @@ -22,9 +22,38 @@ The plugins for Vite and Webpack are included in the `bundler-plugins/` director - `dist/auto/external/qrcode.js` +### Astro Plugin (aka Integration) + +If using Astro 4+, it's strongly suggested to import this library's Astro-plugin to manage the loading of its non-ESM dependencies. Add something like the following to your `astro.config.mjs` file: + +```js +import { defineConfig } from "astro/config"; + +import QRDS from "@lo-fi/qr-data-sync/bundlers/astro"; + +export default defineConfig({ + // .. + + integrations: [ QRDS(), ], + + vite: { + plugins: [ + // pulls in some necessary bits of QRDS's vite plugin + QRDS.vite(), + ], + }, + + // .. +}); +``` + +In all cases, it copies the `dist/bundlers/qrds-external-bundle.js` file into the `public/` directory of your project root, as well as the `dist/` directory when running a build. It also injects an inline ``. +An unfortunate gotcha of some tools that wrap Vite (e.g., Nuxt, etc) and do SSR (server-side rendering) is that they *break* a key assumption/behavior of this module's Vite plugin: the HTML injection of ``. As such, you'll likely need to manually add that `