https://github.com/jan-nikolov/astro-annotate
Visual annotation overlay for Astro staging sites. Annotations stored as structured JSON, readable by developers and LLMs.
https://github.com/jan-nikolov/astro-annotate
annotations astro astro-integration developer-tools devtools feedback llm shadow-dom staging typescript
Last synced: 28 days ago
JSON representation
Visual annotation overlay for Astro staging sites. Annotations stored as structured JSON, readable by developers and LLMs.
- Host: GitHub
- URL: https://github.com/jan-nikolov/astro-annotate
- Owner: jan-nikolov
- License: mit
- Created: 2026-02-20T13:34:43.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-20T12:56:19.000Z (3 months ago)
- Last Synced: 2026-03-21T05:24:35.867Z (3 months ago)
- Topics: annotations, astro, astro-integration, developer-tools, devtools, feedback, llm, shadow-dom, staging, typescript
- Language: TypeScript
- Homepage: https://github.com/jan-nikolov/astro-annotate#readme
- Size: 2.34 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# astro-annotate
[](https://www.npmjs.com/package/astro-annotate)
[](https://www.npmjs.com/package/astro-annotate)
[](./LICENSE)
[](https://astro.build)
Visual annotation overlay for Astro staging sites. Clients and stakeholders annotate HTML elements directly in the browser. Annotations are stored as structured JSON, readable by developers and LLMs.
> **Status:** Phase 1 (MVP) — local dev mode. Works with `astro dev`.
## Why astro-annotate?
- **Built for Astro** — `npx astro add`, Dev Toolbar icon, View Transitions support
- **Zero dependencies** — vanilla TypeScript client, ~15KB gzipped
- **LLM-native** — annotations saved as `annotations.json` with CSS selectors, feed directly to Claude Code or Cursor
- **No SaaS, no account** — everything stays in your repo, no third-party service
- **Shadow DOM isolated** — overlay UI never touches your site's styles
## Quick Start
```bash
npx astro add astro-annotate
```
Manual installation
```bash
npm install astro-annotate
```
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import annotate from 'astro-annotate';
export default defineConfig({
integrations: [annotate()],
});
```
## Features
- **Element-based annotations** — hover to highlight, click to annotate any HTML element
- **Figma-style pins** — small teardrops that point toward annotated elements with directional tilt
- **Draggable panel** — freely movable annotations panel with resize handle and snap-to-side docking
- **CSS selector tracking** — annotations reference elements by robust CSS selectors (IDs, data-testid, tag+class)
- **JSON storage** — annotations saved as `annotations.json`, directly readable by developers and LLMs
- **Astro Dev Toolbar** — native toolbar icon with notification badge for open annotations
- **Device detection** — automatically tags annotations as mobile/tablet/desktop
## Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| `Alt + C` | Toggle annotation mode |
| `Alt + L` | Toggle annotations panel |
| `Escape` | Close topmost UI (form → detail → panel → exit mode) |
| `Ctrl + Enter` | Submit annotation |
## Reading Annotations
The `annotations.json` file is structured for both humans and machines:
```json
{
"version": "1.0",
"annotations": [
{
"id": "abc123",
"page": "/",
"selector": "h1.hero-title",
"text": "Make this headline shorter",
"author": "Client Name",
"status": "open",
"device": "desktop",
"viewport": { "width": 1440, "height": 900 }
}
]
}
```
## Configuration
| Option | Default | Description |
|--------|---------|-------------|
| `enabled` | `true` in dev | Enable the annotation overlay |
| `storage` | `'local'` | Storage backend |
| `annotationsPath` | `'./annotations.json'` | Path to the annotations file |
```js
annotate({
enabled: true,
storage: 'local',
annotationsPath: './annotations.json',
})
```
## Roadmap
- **Phase 2:** Deployed mode on Cloudflare Pages with password auth
- **Phase 3:** Screenshots, CLI export, mobile UX, docs
## Contributing
Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions.
## License
MIT