astro-click-to-source

An Astro integration that enables click-to-source functionality during development. Hold Alt (or another modifier) and click any element to instantly open its source file in your editor at the exact line and column.

Features

• Alt+Click to open source - Jump directly to the component source in your editor
• Visual highlighting - See which element you're about to open when holding the modifier key
• Tooltip preview - Shows the file path and line number before you click
• Clipboard mode - Copy the source path instead of opening the editor
• Multi-editor support - Works with VS Code, Neovim, WebStorm, and more
• HMR-aware - Maintains source mappings across hot module reloads
• Zero config - Works out of the box with sensible defaults

Installation

npm install astro-click-to-source

Usage

Add the integration to your astro.config.mjs:

import { defineConfig } from 'astro/config';
import { clickToSource } from 'astro-click-to-source';

export default defineConfig({
  integrations: [clickToSource()]
});

Then run your dev server and Alt+Click (or Option+Click on Mac) any element to open its source file.

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | modifier | 'alt' \| 'ctrl' \| 'meta' \| 'shift' | 'alt' | Modifier key to hold while clicking | | showHighlight | boolean | true | Show visual highlight on hover when modifier is held |

Example with options

import { clickToSource } from 'astro-click-to-source';

export default defineConfig({
  integrations: [
    clickToSource({
      modifier: 'ctrl',      // Use Ctrl+Click instead of Alt+Click
      showHighlight: false   // Disable visual highlighting
    })
  ]
});

Environment Variables

CLICK_TO_SOURCE

Set this environment variable to customize the behavior:

| Value | Behavior | |-------|----------| | code (default) | Open in VS Code | | cursor | Open in Cursor | | windsurf | Open in Windsurf | | antigravity | Open in Antigravity | | trae | Open in Trae | | nvim | Open in Neovim | | vim | Open in Vim | | webstorm | Open in WebStorm | | phpstorm | Open in PhpStorm | | idea | Open in IntelliJ IDEA | | sublime | Open in Sublime Text | | atom | Open in Atom | | clipboard | Copy path to clipboard instead of opening editor |

Any CLI command on your PATH that accepts a file:line:column argument will work — the value is forwarded to launch-editor. So if your editor ships a shell binary (e.g. the antigravity command installed by the Antigravity IDE), just set CLICK_TO_SOURCE to its name.

# Open in Neovim
CLICK_TO_SOURCE=nvim npm run dev

# Open in Antigravity IDE
CLICK_TO_SOURCE=antigravity npm run dev

# Copy to clipboard
CLICK_TO_SOURCE=clipboard npm run dev

How It Works

1. Source Mapping: Astro adds data-astro-source-file and data-astro-source-loc attributes to elements in development mode
2. Caching: The integration caches these mappings to survive HMR updates
3. Click Handling: When you Alt+Click, it finds the nearest element with source info
4. Editor Opening: Uses launch-editor to open your editor at the exact location

Editor Detection

The integration uses launch-editor which automatically detects your editor from:

1. CLICK_TO_SOURCE environment variable
2. LAUNCH_EDITOR environment variable
3. EDITOR environment variable
4. Running editor processes

Requirements

• Astro 4.0.0 or higher
• Node.js 18.17.0 or higher

License

MIT