https://github.com/nickradford/astro-grab
visual element targeting for astro apps
https://github.com/nickradford/astro-grab
astro developer-tools grab
Last synced: 5 months ago
JSON representation
visual element targeting for astro apps
- Host: GitHub
- URL: https://github.com/nickradford/astro-grab
- Owner: nickradford
- License: mit
- Created: 2025-12-21T10:25:29.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-16T04:52:24.000Z (5 months ago)
- Last Synced: 2026-01-16T06:44:11.479Z (5 months ago)
- Topics: astro, developer-tools, grab
- Language: TypeScript
- Homepage: https://astro-grab.nickradford.dev
- Size: 5.16 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Astro Grab (Alpha)
**Visual element targeting for Astro projects** - Hold Cmd/Ctrl+G to target any element and copy its source code to your clipboard.
## What is Astro Grab?
Astro Grab is a dev-only tool that helps you quickly locate and grab source code from your Astro components. Simply hold Cmd+G (Mac) or Ctrl+G (Windows/Linux) for one second, then click any element to copy its source snippet to your clipboard - perfect for pasting into AI assistants like Claude.
## Features (Alpha)
- 🎯 **Visual targeting mode**: Hold Cmd/Ctrl+G to enter targeting mode with visual highlights
- 📋 **Instant clipboard copy**: Click any element to copy its source code snippet
- 🔍 **Source attribution**: Automatically tracks elements to their .astro files
- ⚡ **Dev-only**: Zero impact on production builds
- 🎨 **Non-intrusive**: Overlay doesn't interfere with page interaction
## Quick Start
### Installation
```bash
bun install
```
### Development
Start all package watchers and the demo app:
```bash
bun run dev
```
This will:
- Build and watch all packages in `packages/`
- Start the Astro dev server for the demo in `apps/demo`
- Enable hot reload for client code changes
Builds are optimized with Turborepo:
- Automatic parallel execution when dependencies allow
- Local caching speeds up subsequent builds
- Dependency graph ensures correct build order
Visit `http://localhost:4321` and try the targeting mode:
1. Hold Cmd+G (Mac) or Ctrl+G (Win/Linux) for 1 second
2. Move your mouse over elements to see them highlighted
3. Click an element to copy its source code
4. Press Escape to exit targeting mode
### Building
Build all packages with Turborepo:
```bash
bun run build
```
Turborepo automatically:
- Builds packages in dependency order (shared → server/client → integration)
- Caches build outputs for faster rebuilds
- Runs packages in parallel when dependencies allow
Build specific packages:
```bash
bun run turbo run build --filter astro-grab-shared
```
### Testing
Run all tests:
```bash
bun run test
```
Watch mode:
```bash
bun run test:watch
```
Run tests in specific package:
```bash
bun run turbo run test --filter astro-grab-shared
```
## Project Structure
This is a Bun monorepo with the following packages:
- **`packages/astro-grab`**: Main Astro integration (what users install)
- **`packages/astro-grab-client`**: Client-side overlay and keybind logic
- **`packages/astro-grab-server`**: Vite dev server middleware and snippet endpoint
- **`packages/astro-grab-shared`**: Shared types and utilities
- **`apps/demo`**: Demo Astro site for testing
## Usage in Your Project
1. Install the integration:
```bash
bun add astro-grab
```
2. Add to your `astro.config.mjs`:
```javascript
import { defineConfig } from "astro/config";
import { astroGrab } from "astro-grab";
export default defineConfig({
integrations: [
astroGrab({
enabled: true, // Enable in dev mode (default: true)
holdDuration: 1000, // Hold time in ms (default: 1000)
contextLines: 10, // Lines of context around target (default: 5)
template: `Source: {{file}}:{{targetLine}}\n\n\`\`\`{{language}}\n{{snippet}}\n\`\`\``, // Custom clipboard template
}),
],
});
```
### Custom Clipboard Template
You can customize the format of the copied snippet using the `template` option with `{{variable}}` interpolation:
```javascript
astroGrab({
template: `File: {{file}}
Line: {{targetLine}}
{{snippet}}`
})
```
**Available variables:**
| Variable | Description | Example |
|----------|-------------|---------|
| `{{file}}` | Path to the .astro file | `src/components/Card.astro` |
| `{{snippet}}` | The extracted code snippet | `
...` |
| `{{startLine}}` | First line of snippet | `12` |
| `{{endLine}}` | Last line of snippet | `18` |
| `{{targetLine}}` | The line clicked on | `15` |
| `{{language}}` | Language identifier | `astro` |
3. Run your dev server:
```bash
npm run dev
```
4. Hold Cmd/Ctrl+G and click elements to grab their source!
## Production Usage (Demo Sites)
By default, astro-grab only works in development mode. For demo sites or production deployments that need to showcase the feature, you can force-enable it:
```bash
# Build with astro-grab enabled
ASTRO_GRAB_DANGEROUSLY_FORCE_ENABLE=true npm run build
```
**⚠️ Security Warning**: This exposes source code snippets to end users. Only enable this on demo sites where sharing component source is intentional.
## How It Works
1. **Instrumentation**: During dev, the Vite plugin transforms `.astro` files to add `data-astro-grab="file:line:col"` attributes to HTML elements
2. **Client injection**: The integration automatically injects a client script that listens for Cmd/Ctrl+G
3. **Targeting mode**: Holding the keybind for 1s activates an overlay that highlights elements under the cursor
4. **Snippet extraction**: Clicking an element fetches a code snippet from the dev server and copies it to clipboard
## Known Limitations (Alpha)
- **HMR**: Client changes require page reload; server/integration changes require dev server restart
- **Parser**: Only `.astro` files (no `.jsx`, `.vue`, etc.)
- **Snippets**: Fixed context window (±40 lines), no dependency resolution
- **Browser**: Requires modern browser with Clipboard API (HTTPS or localhost)
## Development
See [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed development instructions, architecture notes, and contribution guidelines.
## License
MIT