{"id":40173632,"url":"https://github.com/nickradford/astro-grab","last_synced_at":"2026-01-19T17:31:27.444Z","repository":{"id":330658861,"uuid":"1120487588","full_name":"nickradford/astro-grab","owner":"nickradford","description":"visual element targeting for astro apps","archived":false,"fork":false,"pushed_at":"2026-01-16T04:52:24.000Z","size":5415,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-16T06:44:11.479Z","etag":null,"topics":["astro","developer-tools","grab"],"latest_commit_sha":null,"homepage":"https://astro-grab.nickradford.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nickradford.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-21T10:25:29.000Z","updated_at":"2026-01-16T04:52:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nickradford/astro-grab","commit_stats":null,"previous_names":["nickradford/astro-grab"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nickradford/astro-grab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickradford%2Fastro-grab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickradford%2Fastro-grab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickradford%2Fastro-grab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickradford%2Fastro-grab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nickradford","download_url":"https://codeload.github.com/nickradford/astro-grab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickradford%2Fastro-grab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28577419,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T16:29:19.148Z","status":"ssl_error","status_checked_at":"2026-01-19T16:29:17.772Z","response_time":67,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astro","developer-tools","grab"],"created_at":"2026-01-19T17:31:27.366Z","updated_at":"2026-01-19T17:31:27.425Z","avatar_url":"https://github.com/nickradford.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Astro Grab (Alpha)\n\n**Visual element targeting for Astro projects** - Hold Cmd/Ctrl+G to target any element and copy its source code to your clipboard.\n\n## What is Astro Grab?\n\nAstro 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.\n\n## Features (Alpha)\n\n- 🎯 **Visual targeting mode**: Hold Cmd/Ctrl+G to enter targeting mode with visual highlights\n- 📋 **Instant clipboard copy**: Click any element to copy its source code snippet\n- 🔍 **Source attribution**: Automatically tracks elements to their .astro files\n- ⚡ **Dev-only**: Zero impact on production builds\n- 🎨 **Non-intrusive**: Overlay doesn't interfere with page interaction\n\n## Quick Start\n\n### Installation\n\n```bash\nbun install\n```\n\n### Development\n\nStart all package watchers and the demo app:\n\n```bash\nbun run dev\n```\n\nThis will:\n\n- Build and watch all packages in `packages/`\n- Start the Astro dev server for the demo in `apps/demo`\n- Enable hot reload for client code changes\n\nBuilds are optimized with Turborepo:\n\n- Automatic parallel execution when dependencies allow\n- Local caching speeds up subsequent builds\n- Dependency graph ensures correct build order\n\nVisit `http://localhost:4321` and try the targeting mode:\n\n1. Hold Cmd+G (Mac) or Ctrl+G (Win/Linux) for 1 second\n2. Move your mouse over elements to see them highlighted\n3. Click an element to copy its source code\n4. Press Escape to exit targeting mode\n\n### Building\n\nBuild all packages with Turborepo:\n\n```bash\nbun run build\n```\n\nTurborepo automatically:\n\n- Builds packages in dependency order (shared → server/client → integration)\n- Caches build outputs for faster rebuilds\n- Runs packages in parallel when dependencies allow\n\nBuild specific packages:\n\n```bash\nbun run turbo run build --filter astro-grab-shared\n```\n\n### Testing\n\nRun all tests:\n\n```bash\nbun run test\n```\n\nWatch mode:\n\n```bash\nbun run test:watch\n```\n\nRun tests in specific package:\n\n```bash\nbun run turbo run test --filter astro-grab-shared\n```\n\n## Project Structure\n\nThis is a Bun monorepo with the following packages:\n\n- **`packages/astro-grab`**: Main Astro integration (what users install)\n- **`packages/astro-grab-client`**: Client-side overlay and keybind logic\n- **`packages/astro-grab-server`**: Vite dev server middleware and snippet endpoint\n- **`packages/astro-grab-shared`**: Shared types and utilities\n- **`apps/demo`**: Demo Astro site for testing\n\n## Usage in Your Project\n\n1. Install the integration:\n\n```bash\nbun add astro-grab\n```\n\n2. Add to your `astro.config.mjs`:\n\n```javascript\nimport { defineConfig } from \"astro/config\";\nimport { astroGrab } from \"astro-grab\";\n\nexport default defineConfig({\n  integrations: [\n    astroGrab({\n      enabled: true, // Enable in dev mode (default: true)\n      holdDuration: 1000, // Hold time in ms (default: 1000)\n      contextLines: 10, // Lines of context around target (default: 5)\n      template: `Source: {{file}}:{{targetLine}}\\n\\n\\`\\`\\`{{language}}\\n{{snippet}}\\n\\`\\`\\``, // Custom clipboard template\n    }),\n  ],\n});\n```\n\n### Custom Clipboard Template\n\nYou can customize the format of the copied snippet using the `template` option with `{{variable}}` interpolation:\n\n```javascript\nastroGrab({\n  template: `File: {{file}}\nLine: {{targetLine}}\n\n{{snippet}}`\n})\n```\n\n**Available variables:**\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `{{file}}` | Path to the .astro file | `src/components/Card.astro` |\n| `{{snippet}}` | The extracted code snippet | `\u003cdiv\u003e...\u003c/div\u003e` |\n| `{{startLine}}` | First line of snippet | `12` |\n| `{{endLine}}` | Last line of snippet | `18` |\n| `{{targetLine}}` | The line clicked on | `15` |\n| `{{language}}` | Language identifier | `astro` |\n\n3. Run your dev server:\n\n```bash\nnpm run dev\n```\n\n4. Hold Cmd/Ctrl+G and click elements to grab their source!\n\n## Production Usage (Demo Sites)\n\nBy 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:\n\n```bash\n# Build with astro-grab enabled\nASTRO_GRAB_DANGEROUSLY_FORCE_ENABLE=true npm run build\n```\n\n**⚠️ Security Warning**: This exposes source code snippets to end users. Only enable this on demo sites where sharing component source is intentional.\n\n## How It Works\n\n1. **Instrumentation**: During dev, the Vite plugin transforms `.astro` files to add `data-astro-grab=\"file:line:col\"` attributes to HTML elements\n2. **Client injection**: The integration automatically injects a client script that listens for Cmd/Ctrl+G\n3. **Targeting mode**: Holding the keybind for 1s activates an overlay that highlights elements under the cursor\n4. **Snippet extraction**: Clicking an element fetches a code snippet from the dev server and copies it to clipboard\n\n## Known Limitations (Alpha)\n\n- **HMR**: Client changes require page reload; server/integration changes require dev server restart\n- **Parser**: Only `.astro` files (no `.jsx`, `.vue`, etc.)\n- **Snippets**: Fixed context window (±40 lines), no dependency resolution\n- **Browser**: Requires modern browser with Clipboard API (HTTPS or localhost)\n\n## Development\n\nSee [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed development instructions, architecture notes, and contribution guidelines.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickradford%2Fastro-grab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnickradford%2Fastro-grab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickradford%2Fastro-grab/lists"}