Astro Grab (Alpha)

Visual element targeting for Astro projects - Hold Cmd/Ctrl+G by default 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. Hold Cmd+G (Mac) or Ctrl+G (Windows/Linux) for 1 second by default, or configure a different trigger key, then click any element to copy its source snippet to your clipboard.

Features (Alpha)

• 🎯 Visual targeting mode: Hold Cmd/Ctrl+<key> 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

bun install

Development

Start all package watchers and the demo app:

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 by default
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:

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:

bun run turbo run build --filter astro-grab-shared

Testing

Run all tests:

bun run test

Watch mode:

bun run test:watch

Run tests in specific package:

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:

bun add astro-grab

2. Add to your astro.config.mjs:

import { defineConfig } from "astro/config";
import { astroGrab } from "astro-grab";

export default defineConfig({
  integrations: [
    astroGrab({
      enabled: true, // Enable in dev mode (default: true)
      key: "b", // Base key for `Cmd/Ctrl+<key>` (default: "g")
      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:

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	<div>...</div>
{{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:

npm run dev

4. Hold your configured Cmd/Ctrl+<key> shortcut 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:

# 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+<key>
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 for detailed development instructions, architecture notes, and contribution guidelines.

License

MIT