@vskstudio/takt-astro 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VSK Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @vskstudio/takt-astro
+
+Astro integration for [Takt](https://github.com/vskstudio/takt-core), privacy-friendly analytics. It injects a tiny browser runtime that boots Takt, fires the initial pageview, and tracks client-side navigations — including [Astro View Transitions](https://docs.astro.build/en/guides/view-transitions/).
+
+## Install
+
+```sh
+pnpm add @vskstudio/takt-astro @vskstudio/takt-core
+```
+
+## Usage
+
+Pick **one** of the two paths below — not both. Both boot core's default instance, so combining them would just re-initialise.
+
+### Integration (recommended)
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config'
+import takt from '@vskstudio/takt-astro'
+
+export default defineConfig({
+  integrations: [takt({ domain: 'example.com' })],
+})
+```
+
+### `<Takt />` component
+
+For per-layout control, place the component in a layout `<head>`:
+
+```astro
+---
+import Takt from '@vskstudio/takt-astro/Takt.astro'
+---
+<head>
+  <Takt domain="example.com" />
+</head>
+```
+
+## Options
+
+Both the integration and the component accept the same options:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `domain` | `string` | `location.hostname` | Site identifier sent with every event. |
+| `endpoint` | `string` | `/api/event` | Ingestion endpoint. |
+| `outbound` | `boolean` | `false` | Auto-track outbound link clicks. |
+| `files` | `boolean` | `false` | Auto-track file downloads. |
+| `spa` | `boolean` | `true` | Track client-side navigations. |
+| `respectDnt` | `boolean` | `true` | Suppress events when Do Not Track is on. |
+| `excludeLocalhost` | `boolean` | `true` | Suppress events on localhost / private IPs. |
+
+## View Transitions
+
+Astro's client router navigates via `history.pushState`. Core's SPA tracking patches `pushState`, so a single pageview fires per client navigation — including View Transitions DOM swaps — while `init()` fires the one initial pageview. That single source means navigations are never double-counted. The runtime is SSR/prerender safe — it only runs in the browser.
+
+## Custom events
+
+Re-exported from core for convenience:
+
+```js
+import { track } from '@vskstudio/takt-astro'
+
+track('Signup', { revenue: { amount: '9.00', currency: 'USD' } })
+```
+
+## License
+
+MIT

package/Takt.astro

@@ -0,0 +1,10 @@
+---
+import { resolveOptions, type TaktOptions } from './src/options'
+import { buildRuntime } from './src/runtime'
+
+type Props = TaktOptions
+
+const runtime = buildRuntime(resolveOptions(Astro.props))
+---
+<!-- Pick ONE install path — this component OR the integration — not both. -->
+<script is:inline type="module" set:html={runtime}></script>

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { AstroIntegration } from 'astro';
+import { InitOptions } from '@vskstudio/takt-core';
+export { InitOptions, TrackOptions, optIn, optOut, pageview, track } from '@vskstudio/takt-core';
+
+/**
+ * Options for the Takt integration and `<Takt />` component. Mirrors core's
+ * {@link InitOptions} naming; `spa` maps to core's `auto`.
+ */
+interface TaktOptions {
+    /** Site identifier sent with every event. Defaults to `location.hostname`. */
+    domain?: string;
+    /** Ingestion endpoint. Defaults to `/api/event`. */
+    endpoint?: string;
+    /** Auto-track outbound link clicks. */
+    outbound?: boolean;
+    /** Auto-track file downloads. */
+    files?: boolean;
+    /** Track client-side navigations (history + Astro View Transitions). Default `true`. */
+    spa?: boolean;
+    /** Suppress events when the browser's Do Not Track is enabled. Default `true`. */
+    respectDnt?: boolean;
+    /** Suppress events on localhost and private IP ranges. Default `true`. */
+    excludeLocalhost?: boolean;
+}
+declare function resolveOptions(options?: TaktOptions): InitOptions;
+
+/** Pick ONE install path — this integration OR the `<Takt />` component — not both. */
+declare function takt(options?: TaktOptions): AstroIntegration;
+
+/**
+ * Build the browser runtime that boots Takt.
+ *
+ * Returned as a source string because Astro's `injectScript` and the `<Takt />`
+ * component both take a raw module body.
+ */
+declare function buildRuntime(options: InitOptions): string;
+
+export { type TaktOptions, buildRuntime, takt as default, resolveOptions, takt };

package/dist/index.js

@@ -0,0 +1,61 @@
+// src/options.ts
+function resolveOptions(options = {}) {
+  return {
+    domain: options.domain,
+    endpoint: options.endpoint,
+    outbound: options.outbound ?? false,
+    files: options.files ?? false,
+    respectDnt: options.respectDnt ?? true,
+    excludeLocalhost: options.excludeLocalhost ?? true,
+    auto: options.spa ?? true
+  };
+}
+
+// src/runtime.ts
+function buildRuntime(options) {
+  const json = JSON.stringify(options).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026");
+  return [
+    `import { init } from '@vskstudio/takt-core';`,
+    // SSR/prerender guard: this module is evaluated under Node when Astro
+    // prerenders, where window/init's browser APIs are absent.
+    `if (typeof window !== 'undefined' && !window.__takt) {`,
+    `  const o = ${json};`,
+    // Idempotent across both entry paths (integration + <Takt/>): the flag stops
+    // a second boot from disposing the first instance's listeners.
+    `  window.__takt = true;`,
+    // Single source of pageviews. init() enables core's SPA tracking, which
+    // patches history.pushState/replaceState. Astro's ClientRouter navigates via
+    // pushState and does NOT replace the history object on DOM swap, so the patch
+    // persists and fires one pageview per View Transitions navigation. init()
+    // also fires the initial pageview. We therefore do NOT listen to
+    // astro:page-load — doing so would double-count every in-app navigation.
+    `  init(o);`,
+    `}`
+  ].join("\n");
+}
+
+// src/integration.ts
+function takt(options = {}) {
+  const runtime = buildRuntime(resolveOptions(options));
+  return {
+    name: "@vskstudio/takt-astro",
+    hooks: {
+      "astro:config:setup": ({ injectScript }) => {
+        injectScript("page", runtime);
+      }
+    }
+  };
+}
+
+// src/index.ts
+import { track, pageview, optOut, optIn } from "@vskstudio/takt-core";
+export {
+  buildRuntime,
+  takt as default,
+  optIn,
+  optOut,
+  pageview,
+  resolveOptions,
+  takt,
+  track
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@vskstudio/takt-astro",
+  "version": "0.2.0",
+  "description": "Astro integration for Takt privacy-friendly analytics",
+  "license": "MIT",
+  "author": "VSK Studio",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "keywords": [
+    "analytics",
+    "privacy",
+    "astro",
+    "astro-integration",
+    "withastro",
+    "takt"
+  ],
+  "homepage": "https://github.com/vskstudio/takt-astro#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vskstudio/takt-astro.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vskstudio/takt-astro/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./Takt.astro": "./Takt.astro",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "Takt.astro"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@vskstudio/takt-core": ">=0.2.0",
+    "astro": ">=4"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.0",
+    "@size-limit/preset-small-lib": "^11.1.6",
+    "@vskstudio/takt-core": "^0.2.0",
+    "astro": "^5.0.0",
+    "eslint": "^9.0.0",
+    "size-limit": "^11.1.6",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "size": "size-limit",
+    "release": "pnpm build && changeset publish"
+  }
+}