astro-ym


Lightweight, type-safe Yandex Metrika integration for Astro.

Designed for Astro 4+ and Astro 5+ (supports both View Transitions and the new Client Router). It handles SPA navigation correctly out of the box, eliminating duplicate hits and ensuring accurate tracking.

✨ Features

- 🚀 Client Router Support: Automatically tracks page views on route changes (SPA navigation) using astro:page-load.
- 💤 Lazy Loading: Optional lazy load of Yandex Metrika script (load on first user interaction or after timeout) for better Lighthouse scores.
- ⚡ Zero Config: Smart defaults (Clickmap, Link tracking enabled by default).
- 🛡 TypeScript: Fully typed component and helper functions.
- 🎯 Goals Helper: Exported reachGoal function for easy conversion tracking.
- 🪶 Lightweight: Uses the modern Yandex tag.js structure and queues calls before the script loads.

📦 Installation

``bash
npm install astro-ym
`

🚀 Usage

Add the component to your main Layout file (e.g., src/layouts/Layout.astro). It is recommended to place it before the closing tag.

`astro
---
import { YandexMetrika } from 'astro-ym';
---












`

$3

You can enable/disable specific features via props.

`astro
counterId={12345678}
clickmap={true}
trackLinks={true}
accurateTrackBounce={true}
webvisor={true}
ecommerce="dataLayer"
params={{ source: "astro" }}
/>
`

$3

You can enable lazy loading so that the Yandex Metrika script loads only after the first user interaction (scroll, click, mousemove, touch, keydown) or after a fallback timeout.

`astro
counterId={12345678}
webvisor={true}
lazy={true}
// optional: fallback timeout in ms (default: 3500)
timeout={4000}
/>
`

This keeps ym available immediately (calls are queued), but delays loading tag.js to improve performance metrics like TBT and LCP.

🎯 Sending Goals (Conversions)

You can trigger goals from anywhere in your client-side code (UI components, scripts) using the exported helper. It automatically detects the counter ID.

$3

`tsx
import { reachGoal } from "astro-ym";

export const BuyButton = () => {
const handleClick = () => {
// Send goal
reachGoal("purchase_click");

// With params
// reachGoal('purchase_click', { price: 100, currency: 'USD' });
};

return Buy Now;
};
`

$3

`html

`

📚 Props Reference

| Prop | Type | Default | Description |
| :-------------------- | :------------------- | :----------- | :-------------------------------------------------------------------------------------------- |
| counterId | number \| string | Required | Your Yandex Metrika Counter ID. |
| ssr | boolean | true | Helps Yandex detect initial server-side load correctly. |
| webvisor | boolean | false | Enables Webvisor (session recording). |
| clickmap | boolean | true | Enables Click map. |
| trackLinks | boolean | true | Tracks external link clicks. |
| accurateTrackBounce | boolean \| number | true | Accurate bounce rate tracking (true = 15s, or pass custom timeout in ms). |
| ecommerce | boolean \| string | false | Enable E-commerce data collection. Pass container name (e.g., "dataLayer") if needed. |
| type | number | 0 | Counter type. 1 for Yandex Advertising Network (RSYA), 0 for standard. |
| trackHash | boolean | false | Track changes in the URL hash (#anchor) as separate hits. |
| sendTitle | boolean | true | Send the page