@dataql/astro
Version:
DataQL Astro SDK with SSR/SSG support and multi-framework compatibility
243 lines (186 loc) • 4.8 kB
Markdown
# @dataql/astro
DataQL Astro SDK with SSG/SSR support and multi-framework island compatibility.
## Features
- 🌟 **Astro Optimized**: Built specifically for Astro's island architecture
- 🏝️ **Island Support**: Works seamlessly with React, Vue, Svelte, and other framework islands
- 📊 **Static First**: Optimized for static site generation with optional SSR
- 🔄 **Offline-First**: Works offline with automatic sync when online
- ⚡ **Performance**: Minimal JavaScript footprint with island hydration
- 🎯 **TypeScript**: Full TypeScript support with type inference
## Installation
```bash
npm install @dataql/astro
# or
yarn add @dataql/astro
```
## Quick Start
### 1. Add DataQL Integration
```js
// astro.config.mjs
import { defineConfig } from "astro/config";
import { createAstroIntegration } from "@dataql/astro";
export default defineConfig({
integrations: [
createAstroIntegration({
appToken: "your-app-token",
databaseName: "my-astro-db",
}),
],
});
```
### 2. Fetch Data in Astro Components
```astro
// src/pages/posts.astro
import { DataQLAstroClient } from '@dataql/astro';
const client = new DataQLAstroClient({
appToken: 'your-app-token',
staticGeneration: true,
});
const posts = await client.find('posts');
<html>
<head>
<title>Blog Posts</title>
</head>
<body>
<h1>Latest Posts</h1>
{posts.map(post => (
<article>
<h2>{post.title}</h2>
<p>{post.excerpt}</p>
<a href={`/posts/${post.slug}`}>Read more</a>
</article>
))}
</body>
</html>
```
### 3. Interactive Islands
```astro
// src/components/PostList.astro
import PostManager from './PostManager';
import { DataQLAstroClient } from '@dataql/astro';
const client = new DataQLAstroClient({
appToken: 'your-app-token',
islandMode: true,
});
const initialPosts = await client.find('posts');
<!-- Static content -->
<h1>Posts</h1>
<!-- Interactive island -->
<PostManager
client:load
initialPosts={initialPosts}
dataqlConfig={{
appToken: 'your-app-token',
enablePersistence: true,
}}
/>
```
### 4. React Island Example
```jsx
// src/components/PostManager.jsx
import { useState, useEffect } from "react";
export default function PostManager({ initialPosts, dataqlConfig }) {
const [posts, setPosts] = useState(initialPosts);
const [loading, setLoading] = useState(false);
const addPost = async (postData) => {
setLoading(true);
// DataQL operations would work here
setLoading(false);
};
return (
<div>
<button onClick={() => addPost({ title: "New Post" })}>
{loading ? "Adding..." : "Add Post"}
</button>
{posts.map((post) => (
<div key={post.id}>
<h3>{post.title}</h3>
<p>{post.content}</p>
</div>
))}
</div>
);
}
```
### 5. Dynamic Routes
```astro
// src/pages/posts/[slug].astro
import { DataQLAstroClient } from '@dataql/astro';
const { slug } = Astro.params;
const client = new DataQLAstroClient({
appToken: 'your-app-token',
});
const post = await client.find('posts', { slug });
if (!post.length) {
return Astro.redirect('/404');
}
const currentPost = post[0];
<html>
<head>
<title>{currentPost.title}</title>
</head>
<body>
<article>
<h1>{currentPost.title}</h1>
<div>{currentPost.content}</div>
</article>
</body>
</html>
```
## API Reference
### Client
- `DataQLAstroClient` - Main client for Astro applications
- `AstroDataQLComponent` - Component wrapper for island hydration
### Integration
- `createAstroIntegration()` - Astro integration setup
### Utilities
- `createAstroDataQLConfig()` - Create optimized configuration
- `fetchStaticData()` - Helper for static data fetching
- `prefetchData()` - Preload data for performance
## Configuration
```js
const config = {
appToken: "your-app-token",
databaseName: "my-astro-db",
enablePersistence: true,
staticGeneration: true,
islandMode: true,
syncConfig: {
autoSync: true,
syncInterval: 30000,
},
debug: false,
};
```
## Multi-Framework Support
DataQL Astro SDK works with all framework islands:
### React
```jsx
import { DataQLProvider } from "@dataql/astro/react";
```
### Vue
```vue
<script setup>
import { useDataQL } from "@dataql/astro/vue";
</script>
```
### Svelte
```svelte
<script>
import { dataql } from '@dataql/astro/svelte';
</script>
```
## Build-Time Optimization
DataQL automatically optimizes for Astro's build process:
- **Static Data**: Fetched at build time for static pages
- **Island Hydration**: Minimal JavaScript for interactive components
- **Prefetching**: Intelligent data prefetching for better performance
- **Caching**: Build-time and runtime caching strategies
## License
MIT