Astro Analytics — VS Code Extension

🧑‍🚀 Not sure what Astro is? See the Astro website at astro.build!

Publisher: kieks.me GbR

Shows Google Analytics GA4 metrics directly in VS Code when you open Astro Markdown or .astro files.

Features

• CodeLens at the top of each .md/.mdx/.astro file with Bounce Rate, Views, Users, and Session Duration
• Explorer — Bounce rate shown next to file names in the directory tree when analytics data exists (badge + tooltip)
• Hover tooltip with full metrics table (hover over the first lines of the file)
• Status Bar in the bottom-right with the Bounce Rate of the currently open page
• Automatic caching (5-minute TTL), manual refresh on click

Bounce Rate Color Coding

The extension shows bounce rate with colored indicators (green / yellow / orange / red) in CodeLens, Explorer file tree, hover, status bar, and the dashboard:

Setup

1. Prepare credentials

The extension requires Google Application Default Credentials with the analytics.readonly scope.

If you don't have them yet, create ADC. For a visual walkthrough, see e.g. Authenticate with GCP using gcloud auth application-default login.

gcloud auth application-default login \
  --scopes https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=~/Certificates/gcp/internal-dev.json

The path to the created credentials file is printed in the console:

Credentials saved to file: [~/.config/gcloud/application_default_credentials.json]

2. Configure the extension

In VS Code: Cmd+, → search for Astro Analytics

Example settings.json:

{
  "astroAnalytics.propertyId": "364493652",
  "astroAnalytics.credentialsPath": "~/.config/gcloud/application_default_credentials.json",
  "astroAnalytics.lookbackDays": 90,
  "astroAnalytics.contentRoot": "src/content",
  "astroAnalytics.pagesRoot": "src/pages"
}

3. URL slug mapping

The extension requests GA4 dimension pagePath and derives the slug from the file path:

src/content/blog/datenstrategie-ki.md  →  /blog/datenstrategie-ki/
src/content/karriere/index.md          →  /karriere/
src/pages/blog/my-post.astro           →  /blog/my-post/
src/pages/index.astro                  →  /

Dynamic routes ([slug].astro, [...slug].astro, [slug]/[id].astro) are supported:

• In the dashboard, a GA4 path like /blog/ can resolve to a dynamic route file (e.g. src/pages/[slug].astro) when no static file exists, so the row stays clickable and opens that file.
• When you open a dynamic route file, the extension shows aggregated bounce rate, views, users, and session duration for all GA4 paths that match that route (e.g. all single-segment paths for [slug].astro).

4. Test that data is loading

If you don’t see any metrics (CodeLens shows “no data” or status bar stays empty):

1. Run the test command
   Cmd+Shift+P → “Astro Analytics: Test API Connection”.
   You can also run “Astro Analytics: Open Dashboard” to open a dashboard tab in the editor area with a sortable table of cached pages, bounce rate indicators, clickable page links (open in editor), and a refresh button.
   The Output panel (channel “Astro Analytics”) will show:

   • Whether the GA4 API call succeeded and how many page paths were returned
   • The first 15 pagePath values from GA4 (so you can compare with your slug mapping)
   • If a .md/.mdx/.astro file is open: the current file’s slug and whether it matches any GA4 path

2. Check configuration
   Ensure astroAnalytics.propertyId is set (numeric GA4 Property ID) and, if needed, astroAnalytics.credentialsPath points to your credentials JSON.

3. Check slug matching
   GA4 pagePath and the extension’s slug both use a trailing slash (e.g. /blog/my-post/). If your site sends paths without a trailing slash, the extension normalizes them for lookup; the test output shows both raw and normalized paths.

4. Check the Output channel
   After a normal refresh, the same channel logs e.g. Loaded N pages from GA4 and sample pagePath values. Any API errors appear there and as an error notification.

If the command "Astro Analytics: Test API Connection" is not found:
Rebuild the extension and reload the window. See CONTRIBUTING.md for build and reload steps.

Localization

The extension is localized for the following languages. The UI (commands, settings, dashboard, messages) follows the VS Code display language when a translation is available:

Translations are provided via package.nls.*.json (contributed UI) and l10n/bundle.l10n.*.json (extension messages and dashboard). The dashboard (sidebar and full panel) uses the current VS Code display language and the same dashboard.* keys from the l10n bundles.

Installation

Install from the VS Code Marketplace or from a .vsix file (Cmd+Shift+P → "Install from VSIX..."). To build from source, see CONTRIBUTING.md.