feat(examples): add Astro getting-started example

.github/workflows/ci-examples.yml

@@ -94,7 +94,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        example: [react, vue, vanilla, cdn, angular, nuxt, laravel, solid]
+        example: [react, vue, vanilla, cdn, angular, nuxt, laravel, solid, astro]
     steps:
       - uses: actions/checkout@v6
 

README.md

@@ -118,7 +118,7 @@ Starter projects to get you running quickly:
 | [Vanilla JS](examples/getting-started/vanilla) | [CDN](examples/getting-started/cdn) |
 | [Comments](examples/editor/built-in-ui/comments) | [Track changes](examples/editor/built-in-ui/track-changes) |
 | [Toolbar](examples/editor/built-in-ui/toolbar) | [AI redlining](examples/ai/redlining) |
-| [AI redlining (server-side)](examples/document-engine/ai-redlining) | |
+| [AI redlining (server-side)](examples/document-engine/ai-redlining) | [Astro](examples/getting-started/astro) |
 
 [Browse all examples](examples/)
 

examples/README.md

@@ -39,6 +39,7 @@ Framework starters. Pick one, run `pnpm install && pnpm dev`.
 | [nextjs](./getting-started/nextjs) | Next.js (SSR-safe) |
 | [nuxt](./getting-started/nuxt) | Nuxt setup |
 | [laravel](./getting-started/laravel) | Laravel + Inertia |
+| [astro](./getting-started/astro) | Astro setup |
 
 ## Editor
 

examples/__tests__/playwright.config.ts

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 // EXAMPLE can be:
-//   "react", "vue", "vanilla", "cdn", "angular"  (getting-started)
+//   "react", "vue", "vanilla", "cdn", "angular", "astro"  (getting-started)
 //   "editor/collaboration/providers/superdoc-yjs", etc.
 const example = process.env.EXAMPLE || 'react';
 
@@ -29,6 +29,7 @@ const portMap: Record<string, number> = {
   cdn: 3000,
   nuxt: 3000,
   laravel: 8000,
+  astro: 4321,
   'editor/collaboration/providers/hocuspocus': 3000,
   'advanced/headless-toolbar/svelte-shadcn': 5190,
   'ai/streaming': 5180,
@@ -41,19 +42,26 @@ const exampleAbsPath = resolve(__dirname, examplePath);
 const hasLocalNodeModules = existsSync(resolve(exampleAbsPath, 'node_modules', '.bin'));
 const run = hasLocalNodeModules ? `npm run --prefix ${examplePath}` : `pnpm --dir ${examplePath} run`;
 
-// Laravel: build Vite assets first, then serve with PHP only (via `start` script).
-// The concurrently approach (php + vite dev) is unreliable in CI.
-const isLaravel = example === 'laravel';
-
-// Start command
-const isCdn = example === 'cdn';
-const command = isCdn
-  ? `node ${examplePath}/setup.mjs && npx serve ${examplePath} -l ${port}`
-  : isLaravel
-    ? `${run} start`
-    : useConcurrently.includes(example)
-      ? `${run} dev`
-      : `${run} dev -- --port ${port}`;
+// Start command — Laravel builds Vite assets first, then serves with PHP only
+// (the concurrently approach is unreliable in CI).
+let command: string;
+switch (example) {
+  case 'cdn':
+    command = `node ${examplePath}/setup.mjs && npx serve ${examplePath} -l ${port}`;
+    break;
+  case 'laravel':
+    command = `${run} start`;
+    break;
+  case 'astro':
+    command = `${run} dev`;
+    break;
+  default:
+    if (useConcurrently.includes(example)) {
+      command = `${run} dev`;
+    } else {
+      command = `${run} dev -- --port ${port}`;
+    }
+}
 
 export default defineConfig({
   testDir: '.',

examples/getting-started/README.md

@@ -10,6 +10,7 @@ Minimal examples for integrating SuperDoc into your project. Each example loads
 | [solid](./solid) | SolidJS + TypeScript with Vite | [Guide](https://docs.superdoc.dev/getting-started/frameworks/solid) |
 | [vanilla](./vanilla) | Plain JavaScript with Vite | [Guide](https://docs.superdoc.dev/getting-started/quickstart) |
 | [cdn](./cdn) | Zero build tools — just an HTML file | [Guide](https://docs.superdoc.dev/getting-started/quickstart) |
+| [astro](./astro) | Astro setup | [Guide](https://docs.superdoc.dev/getting-started/quickstart) |
 
 The bundler examples pass [`@superdoc-dev/fonts`](https://docs.superdoc.dev/getting-started/fonts), so SuperDoc's bundled fallback fonts (Carlito for Calibri, and more) render without copying any assets. The CDN example loads them from the script's path; the Laravel example copies them into `public/fonts/`.
 

examples/getting-started/astro/.gitignore

@@ -0,0 +1,24 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# jetbrains setting folder
+.idea/

examples/getting-started/astro/README.md

@@ -0,0 +1,17 @@
+# SuperDoc — Astro
+
+Minimal Astro example.
+
+SuperDoc runs in a client-side `<script>` block only - do not initialize it during SSR.
+
+## Run
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## Learn more
+
+- [Quickstart Guide](https://docs.superdoc.dev/getting-started/quickstart)
+- [Configuration Reference](https://docs.superdoc.dev/editor/superdoc/configuration)

examples/getting-started/astro/astro.config.mjs

@@ -0,0 +1,9 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+
+// https://astro.build/config
+export default defineConfig({
+	server: {
+		port: 4321,
+	},
+});

examples/getting-started/astro/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "superdoc-astro-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev"
+  },
+  "dependencies": {
+    "astro": "^7.1.3",
+    "@superdoc-dev/fonts": "workspace:*",
+    "superdoc": "latest"
+  }
+}

examples/getting-started/astro/src/pages/index.astro

@@ -0,0 +1,44 @@
+---
+import 'superdoc/style.css';
+---
+
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width" />
+		<meta name="generator" content={Astro.generator} />
+		<title>SuperDoc — Astro</title>
+	</head>
+	<body>
+		<div style="padding: 1rem; background: #f5f5f5">
+			<input type="file" id="file-input" accept=".docx" />
+		</div>
+		<div id="editor" style="height: calc(100vh - 60px)"></div>
+
+		<script>
+			import { SuperDoc } from 'superdoc';
+			import { superdocFonts } from '@superdoc-dev/fonts';
+
+			let superdoc: SuperDoc | null = null;
+
+			const initEditor = (file: File) => {
+				superdoc?.destroy();
+				superdoc = new SuperDoc({
+					selector: '#editor',
+					document: file,
+					fonts: superdocFonts,
+				});
+			};
+
+			const handleFile = (e: Event) => {
+				const file = (e.target as HTMLInputElement).files?.[0];
+				if (!file) return;
+
+				initEditor(file);
+			};
+
+			const fileInput = document.querySelector<HTMLInputElement>('#file-input');
+			fileInput?.addEventListener('change', handleFile);
+		</script>
+	</body>
+</html>

examples/getting-started/astro/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}

examples/manifest.json

@@ -31,6 +31,21 @@
     "ci": true,
     "slug": "vue"
   },
+  {
+    "id": "getting-started-astro",
+    "section": "getting-started",
+    "subsection": "frameworks",
+    "kind": "integration-example",
+    "status": "active",
+    "sourceKind": "local",
+    "title": "Astro starter",
+    "category": "Getting Started",
+    "surface": "Frameworks",
+    "sourceRepo": "superdoc-dev/superdoc",
+    "sourcePath": "examples/getting-started/astro",
+    "docs": "https://docs.superdoc.dev/getting-started/quickstart",
+    "ci": true
+  },
   {
     "id": "getting-started-vanilla",
     "section": "getting-started",