@datocms/astro 0.1.13 → 0.2.1

package/README.md

@@ -1,54 +1,66 @@
-# Astro Starter Kit: Basics
+<!--datocms-autoinclude-header start-->
 
-```sh
-npm create astro@latest -- --template basics
-```
+<a href="https://www.datocms.com/"><img src="https://www.datocms.com/images/full_logo.svg" height="60"></a>
+
+👉 [Visit the DatoCMS homepage](https://www.datocms.com) or see [What is DatoCMS?](#what-is-datocms)
+
+<!--datocms-autoinclude-header end-->
+
+# @datocms/astro
+
+[![MIT](https://img.shields.io/npm/l/@datocms/astro?style=for-the-badge)](https://github.com/datocms/astro-datocms/blob/master/LICENSE) [![NPM](https://img.shields.io/npm/v/@datocms/astro?style=for-the-badge)](https://www.npmjs.com/package/@datocms/astro)
+
+A set of TypeScript-ready components and utilities to work faster with [DatoCMS](https://www.datocms.com/) in Astro project. Integrates seamlessly with [DatoCMS's GraphQL Content Delivery API](https://www.datocms.com/docs/content-delivery-api).
 
-[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/astro/tree/latest/examples/basics)
-[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/astro/tree/latest/examples/basics)
-[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/withastro/astro?devcontainer_path=.devcontainer/basics/devcontainer.json)
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+- [Features](#features)
+- [Installation](#installation)
+- [What is DatoCMS?](#what-is-datocms)
 
-![just-the-basics](https://github.com/withastro/astro/assets/2244813/a0a5533c-a856-4198-8470-2d67b1d7c554)
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## 🚀 Project Structure
+## Features
 
-Inside of your Astro project, you'll see the following folders and files:
+`@datocms/astro` contains ready-to-use Astro components and helpers:
 
-```text
-/
-├── public/
-│   └── favicon.svg
-├── src/
-│   ├── components/
-│   │   └── Card.astro
-│   ├── layouts/
-│   │   └── Layout.astro
-│   └── pages/
-│       └── index.astro
-└── package.json
+- [`<Image />`](src/Image)
+- [`<Seo />`](src/Seo)
+- [`<StructuredText />`](src/StructuredText)
+- [`<QueryListener />`](src/QueryListener)
+
+## Installation
+
+```
+npm install @datocms/astro
 ```
 
-Astro looks for `.astro` or `.md` files in the `src/pages/` directory. Each page is exposed as a route based on its file name.
+<!--datocms-autoinclude-footer start-->
+
+# What is DatoCMS?
+
+<a href="https://www.datocms.com/"><img src="https://www.datocms.com/images/full_logo.svg" height="60"></a>
+
+[DatoCMS](https://www.datocms.com/) is the REST & GraphQL Headless CMS for the modern web.
 
-There's nothing special about `src/components/`, but that's where we like to put any Astro/React/Vue/Svelte/Preact components.
+Trusted by over 25,000 enterprise businesses, agency partners, and individuals across the world, DatoCMS users create online content at scale from a central hub and distribute it via API. We ❤️ our [developers](https://www.datocms.com/team/best-cms-for-developers), [content editors](https://www.datocms.com/team/content-creators) and [marketers](https://www.datocms.com/team/cms-digital-marketing)!
 
-Any static assets, like images, can be placed in the `public/` directory.
+**Quick links:**
 
-## 🧞 Commands
+- ⚡️ Get started with a [free DatoCMS account](https://dashboard.datocms.com/signup)
+- 🔖 Go through the [docs](https://www.datocms.com/docs)
+- ⚙️ Get [support from us and the community](https://community.datocms.com/)
+- 🆕 Stay up to date on new features and fixes on the [changelog](https://www.datocms.com/product-updates)
 
-All commands are run from the root of the project, from a terminal:
+**Our featured repos:**
 
-| Command                   | Action                                           |
-| :------------------------ | :----------------------------------------------- |
-| `npm install`             | Installs dependencies                            |
-| `npm run dev`             | Starts local dev server at `localhost:4321`      |
-| `npm run build`           | Build your production site to `./dist/`          |
-| `npm run preview`         | Preview your build locally, before deploying     |
-| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
-| `npm run astro -- --help` | Get help using the Astro CLI                     |
+- [datocms/react-datocms](https://github.com/datocms/react-datocms): React helper components for images, Structured Text rendering, and more
+- [datocms/js-rest-api-clients](https://github.com/datocms/js-rest-api-clients): Node and browser JavaScript clients for updating and administering your content. For frontend fetches, we recommend using our [GraphQL Content Delivery API](https://www.datocms.com/docs/content-delivery-api) instead.
+- [datocms/cli](https://github.com/datocms/cli): Command-line interface that includes our [Contentful importer](https://github.com/datocms/cli/tree/main/packages/cli-plugin-contentful) and [Wordpress importer](https://github.com/datocms/cli/tree/main/packages/cli-plugin-wordpress)
+- [datocms/plugins](https://github.com/datocms/plugins): Example plugins we've made that extend the editor/admin dashboard
+- [DatoCMS Starters](https://www.datocms.com/marketplace/starters) has examples for various Javascript frontend frameworks
 
-## 👀 Want to learn more?
+Or see [all our public repos](https://github.com/orgs/datocms/repositories?q=&type=public&language=&sort=stargazers)
 
-Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat).
+<!--datocms-autoinclude-footer end-->

package/package.json

@@ -1,52 +1,65 @@
 {
-	"name": "@datocms/astro",
-	"description": "A set of components and utilities to work faster with DatoCMS in Astro projects.",
-	"type": "module",
-	"version": "0.1.13",
-	"sideEffects": false,
-	"repository": {
-		"type": "git",
-		"url": "git://github.com/datocms/astro-datocms.git"
-	},
-	"homepage": "https://github.com/datocms/astro-datocms",
-	"license": "MIT",
-	"author": "Stefano Verna <s.verna@datocms.com>",
-	"contributors": ["Silvano Stralla <silvano@datocms.com>"],
-	"keywords": [
-		"astro",
-		"withastro",
-		"astro-component",
-		"datocms",
-		"typescript",
-		"ui"
-	],
-	"exports": {
-		"./useVideoPlayer": "./src/useVideoPlayer/index.ts",
-		"./VideoPlayer": "./src/VideoPlayer/index.ts",
-		"./Image": "./src/Image/index.ts",
-		"./StructuredText": "./src/StructuredText/index.ts",
-		"./Seo": "./src/Seo/index.ts"
-	},
-	"engines": {
-		"node": ">=18.0.0"
-	},
-	"files": ["src"],
-	"dependencies": {
-		"@mux/playback-core": "^0.25.1",
-		"datocms-structured-text-utils": "^4.0.1",
-		"typescript": "^5.5.4"
-	},
-	"peerDependencies": {
-		"@mux/mux-player": "*",
-		"astro": "*"
-	},
-	"peerDependenciesMeta": {
-		"@mux/mux-player": {
-			"optional": true
-		}
-	},
-	"devDependencies": {
-		"@mux/mux-player": "*",
-		"astro": "^4.13.1"
-	}
+  "name": "@datocms/astro",
+  "description": "A set of components and utilities to work faster with DatoCMS in Astro projects.",
+  "type": "module",
+  "version": "0.2.1",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/datocms/astro-datocms.git"
+  },
+  "homepage": "https://github.com/datocms/astro-datocms",
+  "license": "MIT",
+  "author": "Stefano Verna <s.verna@datocms.com>",
+  "contributors": [
+    "Silvano Stralla <silvano@datocms.com>"
+  ],
+  "keywords": [
+    "astro",
+    "withastro",
+    "astro-component",
+    "datocms",
+    "typescript",
+    "ui"
+  ],
+  "scripts": {
+    "prepare": "npx simple-git-hooks",
+    "lint": "prettier --check .",
+    "format": "npm run toc && npx prettier . --write",
+    "toc": "doctoc --github README.md src",
+    "test": "echo 1"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./Image": "./src/Image/index.ts",
+    "./StructuredText": "./src/StructuredText/index.ts",
+    "./Seo": "./src/Seo/index.ts",
+    "./QueryListener": "./src/QueryListener/index.ts"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@0no-co/graphql.web": "^1.0.7",
+    "datocms-listen": "^1.0.0",
+    "datocms-structured-text-utils": "^4.0.1"
+  },
+  "peerDependencies": {
+    "astro": "*"
+  },
+  "devDependencies": {
+    "astro": "^4.13.1",
+    "doctoc": "^2.2.1",
+    "np": "^10.0.7",
+    "prettier": "^3.3.3",
+    "prettier-plugin-astro": "^0.14.1",
+    "simple-git-hooks": "^2.11.1",
+    "typescript": "^5.5.4"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "npm run format"
+  }
 }

package/src/Image/Image.astro

@@ -1,9 +1,8 @@
 ---
-
 import { buildSrcSet } from './buildSrcSet';
 import type { ImageProps } from './types';
 
-interface Props extends ImageProps {};
+interface Props extends ImageProps {}
 
 const {
   data,
@@ -21,52 +20,45 @@ const placeholderStyle =
   usePlaceholder && data.base64
     ? {
         backgroundImage: `url("${data.base64}")`,
-        backgroundSize: "cover",
-        backgroundRepeat: "no-repeat",
-        backgroundPosition: "50% 50%",
-        color: "transparent",
+        backgroundSize: 'cover',
+        backgroundRepeat: 'no-repeat',
+        backgroundPosition: '50% 50%',
+        color: 'transparent',
       }
     : usePlaceholder && data.bgColor
-      ? { backgroundColor: data.bgColor ?? undefined, color: "transparent" }
+      ? { backgroundColor: data.bgColor ?? undefined, color: 'transparent' }
       : undefined;
 
 const { width } = data;
 
-const height =
-  data.height ?? Math.round(data.aspectRatio ? width / data.aspectRatio : 0);
+const height = data.height ?? Math.round(data.aspectRatio ? width / data.aspectRatio : 0);
 
 const sizingStyle = {
   aspectRatio: `${width} / ${height}`,
-  width: "100%",
+  width: '100%',
   maxWidth: `${width}px`,
-  height: "auto",
+  height: 'auto',
 };
 ---
 
 <picture class={pictureClass} style={pictureStyle}>
   {
     data.webpSrcSet && (
-      <source
-        srcset={data.webpSrcSet}
-        sizes={sizes ?? data.sizes ?? null}
-        type="image/webp"
-      />
+      <source srcset={data.webpSrcSet} sizes={sizes ?? data.sizes ?? null} type="image/webp" />
     )
   }
   <source
-    srcset={data.srcSet ??
-      buildSrcSet(data.src, data.width, srcSetCandidates) ??
-      null}
+    srcset={data.srcSet ?? buildSrcSet(data.src, data.width, srcSetCandidates) ?? null}
     sizes={sizes ?? data.sizes ?? null}
   />
   {
     data.src && (
       <img
         src={data.src}
-        alt={data.alt ?? ""}
+        alt={data.alt ?? ''}
         title={data.title ?? null}
-        fetchpriority={priority ? "high" : undefined}
-        loading={priority ? undefined : "lazy"}
+        fetchpriority={priority ? 'high' : undefined}
+        loading={priority ? undefined : 'lazy'}
         class={imgClass}
         style={{
           ...placeholderStyle,

package/src/Image/README.md

@@ -0,0 +1,124 @@
+# Progressive responsive image
+
+`<Image>` is a TypeScript-ready Astro component specially designed to work seamlessly with DatoCMS’s [`responsiveImage` GraphQL query](https://www.datocms.com/docs/content-delivery-api/uploads#responsive-images) which optimizes image loading for your websites.
+
+### Out-of-the-box features
+
+- Completely native, with no JavaScript footprint
+- Offers optimized version of images for browsers that support WebP/AVIF format
+- Generates multiple smaller images so smartphones and tablets don’t download desktop-sized images
+- Efficiently lazy loads images to speed initial page load and save bandwidth
+- Holds the image position so your page doesn’t jump while images load
+- Uses either blur-up or background color techniques to show a preview of the image while it loads
+
+### Table of contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Setup](#setup)
+- [Usage](#usage)
+- [Example](#example)
+- [The `ResponsiveImage` object](#the-responsiveimage-object)
+- [`<Image />`](#image-)
+  - [Props](#props)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+### Setup
+
+You can import the component like this:
+
+```js
+import { Image } from '@datocms/astro/Image';
+```
+
+## Usage
+
+1. Use `<Image>` in place of the regular `<img />` tag
+2. Write a GraphQL query to your DatoCMS project using the [`responsiveImage` query](https://www.datocms.com/docs/content-delivery-api/images-and-videos#responsive-images)
+
+The GraphQL query returns multiple thumbnails with optimized compression. The components automatically set up the "blur-up" effect as well as lazy loading of images further down the screen.
+
+## Example
+
+Here is a minimal starting point:
+
+```astro
+---
+import { Image } from '@datocms/astro/Image';
+import { executeQuery } from '@datocms/cda-client';
+
+const query = gql`
+  query {
+    blogPost {
+      title
+      cover {
+        responsiveImage(imgixParams: { fit: crop, w: 300, h: 300, auto: format }) {
+          # always required
+          src
+          width
+          height
+          # not required, but strongly suggested!
+          alt
+          title
+          # blur-up placeholder, JPEG format, base64-encoded, or...
+          base64
+          # background color placeholder
+          bgColor
+          # you can omit sizes if you explicitly pass the sizes prop to the image component
+          sizes
+        }
+      }
+    }
+  }
+`;
+
+const { blogPost } = await executeQuery(query, { token: '<YOUR-API-TOKEN>' });
+---
+
+<Image data={blogPost.cover.responsiveImage} />
+```
+
+## The `ResponsiveImage` object
+
+The `data` prop of both components expects an object with the same shape as the one returned by `responsiveImage` GraphQL call. It's up to you to make a GraphQL query that will return the properties you need for a specific use of the `<Image>` component.
+
+- The minimum required properties for `data` are: `src`, `width` and `height`;
+- `alt` and `title`, while not mandatory, are all highly suggested, so remember to use them!
+- If you don't request `srcSet`, the component will auto-generate an `srcset` based on `src` + the `srcSetCandidates` prop (it can help reducing the GraphQL response size drammatically when many images are returned);
+- We strongly to suggest to always specify [`{ auto: format }`](https://docs.imgix.com/apis/rendering/auto/auto#format) in your `imgixParams`, instead of requesting `webpSrcSet`, so that you can also take advantage of more performant optimizations (AVIF), without increasing GraphQL response size;
+- If you request both the `bgColor` and `base64` property, the latter will take precedence, so just avoid querying both fields at the same time, as it will only make the GraphQL response bigger :wink:;
+- You can avoid requesting `sizes` and directly pass a `sizes` prop to the component to reduce the GraphQL response size;
+
+Here's a complete recap of what `responsiveImage` offers:
+
+| property    | type    | required           | description                                                                                                                                                                                    |
+| ----------- | ------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| src         | string  | :white_check_mark: | The `src` attribute for the image                                                                                                                                                              |
+| width       | integer | :white_check_mark: | The width of the image                                                                                                                                                                         |
+| height      | integer | :white_check_mark: | The height of the image                                                                                                                                                                        |
+| alt         | string  | :x:                | Alternate text (`alt`) for the image (not required, but strongly suggested!)                                                                                                                   |
+| title       | string  | :x:                | Title attribute (`title`) for the image (not required, but strongly suggested!)                                                                                                                |
+| sizes       | string  | :x:                | The HTML5 `sizes` attribute for the image (omit it if you're already passing a `sizes` prop to the Image component)                                                                            |
+| base64      | string  | :x:                | A base64-encoded thumbnail to offer during image loading                                                                                                                                       |
+| bgColor     | string  | :x:                | The background color for the image placeholder (omit it if you're already requesting `base64`)                                                                                                 |
+| srcSet      | string  | :x:                | The HTML5 `srcSet` attribute for the image (can be omitted, the Image component knows how to build it based on `src`)                                                                          |
+| webpSrcSet  | string  | :x:                | The HTML5 `srcSet` attribute for the image in WebP format (deprecated, it's better to use the [`auto=format`](https://docs.imgix.com/apis/rendering/auto/auto#format) Imgix transform instead) |
+| aspectRatio | float   | :x:                | The aspect ratio (width/height) of the image                                                                                                                                                   |
+
+## `<Image />`
+
+### Props
+
+| prop             | type                     | default                            | required           | description                                                                                                                                          |
+| ---------------- | ------------------------ | ---------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| data             | `ResponsiveImage` object |                                    | :white_check_mark: | The actual response you get from a DatoCMS `responsiveImage` GraphQL query \*\*\*\*                                                                  |
+| pictureClass     | string                   | null                               | :x:                | Additional CSS class for the root `<picture>` tag                                                                                                    |
+| pictureStyle     | CSS properties           | null                               | :x:                | Additional CSS rules to add to the root `<picture>` tag                                                                                              |
+| imgClass         | string                   | null                               | :x:                | Additional CSS class for the `<img>` tag                                                                                                             |
+| imgStyle         | CSS properties           | null                               | :x:                | Additional CSS rules to add to the `<img>` tag                                                                                                       |
+| priority         | Boolean                  | false                              | :x:                | Disables lazy loading, and sets the image [fetchPriority](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority) to "high" |
+| sizes            | string                   | undefined                          | :x:                | The HTML5 [`sizes`](https://web.dev/learn/design/responsive-images/#sizes) attribute for the image (will be used `data.sizes` as a fallback)         |
+| usePlaceholder   | Boolean                  | true                               | :x:                | Whether the image should use a blurred image placeholder                                                                                             |
+| srcSetCandidates | Array<number>            | [0.25, 0.5, 0.75, 1, 1.5, 2, 3, 4] | :x:                | If `data` does not contain `srcSet`, the candidates for the `srcset` attribute of the image will be auto-generated based on these width multipliers  |

package/src/Image/buildSrcSet.ts

@@ -1,10 +1,9 @@
-
-const bogusBaseUrl = "https://example.com/";
+const bogusBaseUrl = 'https://example.com/';
 
 export const buildSrcSet = (
   src: string | null | undefined,
   width: number | undefined,
-  candidateMultipliers: number[]
+  candidateMultipliers: number[],
 ) => {
   if (!(src && width)) {
     return undefined;
@@ -15,20 +14,14 @@ export const buildSrcSet = (
       const url = new URL(src, bogusBaseUrl);
 
       if (multiplier !== 1) {
-        url.searchParams.set("dpr", `${multiplier}`);
-        const maxH = url.searchParams.get("max-h");
-        const maxW = url.searchParams.get("max-w");
+        url.searchParams.set('dpr', `${multiplier}`);
+        const maxH = url.searchParams.get('max-h');
+        const maxW = url.searchParams.get('max-w');
         if (maxH) {
-          url.searchParams.set(
-            "max-h",
-            `${Math.floor(Number.parseInt(maxH) * multiplier)}`
-          );
+          url.searchParams.set('max-h', `${Math.floor(Number.parseInt(maxH) * multiplier)}`);
         }
         if (maxW) {
-          url.searchParams.set(
-            "max-w",
-            `${Math.floor(Number.parseInt(maxW) * multiplier)}`
-          );
+          url.searchParams.set('max-w', `${Math.floor(Number.parseInt(maxW) * multiplier)}`);
         }
       }
 
@@ -38,8 +31,8 @@ export const buildSrcSet = (
         return null;
       }
 
-      return `${url.toString().replace(bogusBaseUrl, "/")} ${finalWidth}w`;
+      return `${url.toString().replace(bogusBaseUrl, '/')} ${finalWidth}w`;
     })
     .filter(Boolean)
-    .join(",");
+    .join(',');
 };

package/src/Image/index.ts

@@ -1,2 +1,4 @@
-import Image from "./Image.astro";
+import Image from './Image.astro';
+
+export * from './types';
 export { Image };

package/src/Image/types.ts

@@ -56,11 +56,11 @@ export type ImageProps = {
    * -> https://web.dev/learn/design/responsive-images/#sizes
    * -> https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes
    **/
-  sizes?: HTMLImageElement["sizes"];
+  sizes?: HTMLImageElement['sizes'];
   /**
    * If `data` does not contain `srcSet`, the candidates for the `srcset` of the image will be auto-generated based on these width multipliers
    *
    * Default candidate multipliers are [0.25, 0.5, 0.75, 1, 1.5, 2, 3, 4]
    **/
   srcSetCandidates?: number[];
-}
+};

package/src/QueryListener/QueryListener.astro

@@ -0,0 +1,56 @@
+---
+import type { QueryListenerOptions } from './types';
+import { print } from '@0no-co/graphql.web';
+
+type Props<QueryResult, QueryVariables> = QueryListenerOptions<QueryResult, QueryVariables>;
+
+const { query, ...rest } = Astro.props;
+
+const stringifiedQuery = typeof query === 'object' ? print(query) : query;
+---
+
+<datocms-query-listener data-config={JSON.stringify({ ...rest, query: stringifiedQuery })}>
+</datocms-query-listener>
+
+<script>
+  import { subscribeToQuery as subscribeToQueryFn } from 'datocms-listen';
+  import type { QueryListenerOptions } from './types';
+
+  class QueryListener extends HTMLElement {
+    config: QueryListenerOptions<unknown, unknown>;
+    updatesReceived: number = 0;
+
+    constructor() {
+      super();
+
+      if (!this.dataset.config) {
+        throw new Error('Missing config');
+      }
+
+      this.config = JSON.parse(this.dataset.config);
+
+      import('datocms-listen').then(({ subscribeToQuery }) => {
+        this.run(subscribeToQuery);
+      });
+    }
+
+    run(subscribeToQuery: typeof subscribeToQueryFn) {
+      subscribeToQuery<unknown, unknown>({
+        ...this.config,
+        onUpdate: () => {
+          this.updatesReceived += 1;
+
+          if (this.updatesReceived > 1) {
+            document.location.reload();
+          }
+        },
+        onChannelError: (error) => {
+          console.error('[QueryListener]', error);
+        },
+      });
+    }
+  }
+
+  // Tell the browser to use our AstroHeart class for <astro-heart> elements.
+  customElements.define('datocms-query-listener', QueryListener);
+</script>

package/src/QueryListener/README.md

@@ -0,0 +1,67 @@
+# Live real-time updates
+
+`<QueryListener />` is an Astro component that you can use to implement client-side reload of the page as soon as the content of a query changes. It uses DatoCMS's [Real-time Updates API](https://www.datocms.com/docs/real-time-updates-api/api-reference) to receive the updated query results in real-time, and is able to reconnect in case of network failures.
+
+Live reloads are great to get instant previews of your content while editing it inside DatoCMS.
+
+`<QueryListener />` is based on the `subscribeToQuery` helper provided by the [datocms-listen](https://www.npmjs.com/package/datocms-listen) package.
+
+## Table of Contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Installation](#installation)
+- [Reference](#reference)
+- [Initialization options](#initialization-options)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Installation
+
+```
+npm install --save @datocms/astro
+```
+
+## Reference
+
+Import `<QueryListener>` from `@datocms/astro` and use it inside your components setup function like this:
+
+```astro
+---
+import { QueryListener } from '@datocms/astro/QueryListener';
+import { executeQuery } from '@datocms/cda-client';
+
+const query = gql`
+  query {
+    homepage {
+      title
+    }
+  }
+`;
+
+const data = await executeQuery(query, { token: '<YOUR-API-TOKEN>' });
+---
+
+<h1>{data.homepage.title}</h1>
+
+<QueryListener query={query} token="<YOUR-API-TOKEN>" />
+```
+
+## Initialization options
+
+| prop               | type                                                                                       | required           | description                                                                                      | default                              |
+| ------------------ | ------------------------------------------------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------ |
+| enabled            | boolean                                                                                    | :x:                | Whether the subscription has to be performed or not                                              | true                                 |
+| query              | string \| [`TypedDocumentNode`](https://github.com/dotansimha/graphql-typed-document-node) | :white_check_mark: | The GraphQL query to subscribe                                                                   |                                      |
+| token              | string                                                                                     | :white_check_mark: | DatoCMS API token to use                                                                         |                                      |
+| variables          | Object                                                                                     | :x:                | GraphQL variables for the query                                                                  |                                      |
+| includeDrafts      | boolean                                                                                    | :x:                | If true, draft records will be returned                                                          |                                      |
+| excludeInvalid     | boolean                                                                                    | :x:                | If true, invalid records will be filtered out                                                    |                                      |
+| environment        | string                                                                                     | :x:                | The name of the DatoCMS environment where to perform the query (defaults to primary environment) |                                      |
+| contentLink        | `'vercel-1'` or `undefined`                                                                | :x:                | If true, embed metadata that enable Content Link                                                 |                                      |
+| baseEditingUrl     | string                                                                                     | :x:                | The base URL of the DatoCMS project                                                              |                                      |
+| cacheTags          | boolean                                                                                    | :x:                | If true, receive the Cache Tags associated with the query                                        |                                      |
+| initialData        | Object                                                                                     | :x:                | The initial data to use on the first render                                                      |                                      |
+| reconnectionPeriod | number                                                                                     | :x:                | In case of network errors, the period (in ms) to wait to reconnect                               | 1000                                 |
+| baseUrl            | string                                                                                     | :x:                | The base URL to use to perform the query                                                         | `https://graphql-listen.datocms.com` |

package/src/QueryListener/index.ts

@@ -0,0 +1,4 @@
+import QueryListener from './QueryListener.astro';
+
+export * from './types';
+export { QueryListener };