Problem

The Deploy Documentation workflow has been failing since PR #284 was merged.

Error:

Could not resolve "../types/gtag" from "docs/.vitepress/theme/composables/useGA4Tracking.ts"

First failure: 2026-02-04T22:16:22Z (run #21690527035)
Last success: 2026-02-04T20:12:19Z (run #21686705917)
Introduced by: PR #284 (feat(docs): upgrade vue-privacy with GA4 tracking + dependency updates)

Root Cause Analysis

The file docs/.vitepress/theme/composables/useGA4Tracking.ts has a side-effect import on line 16:

import "../types/gtag"; // Import gtag type declaration

This import points to docs/.vitepress/theme/types/gtag.d.ts - a TypeScript declaration file (.d.ts).

The issue: Vite/Rollup cannot resolve .d.ts files as runtime imports. Declaration files are metadata for TypeScript's type checker, not actual modules that can be imported at build time.

Solution Options

Option A: Convert to regular TypeScript module (Recommended)

Rename gtag.d.ts to gtag.ts - the file only contains declare global augmentation and export {}, which is valid in both .d.ts and .ts files.

Option B: Use triple-slash reference directive

Replace the import in useGA4Tracking.ts:

// Remove: import "../types/gtag";
// Add at top of file:
/// <reference path="../types/gtag.d.ts" />

Option C: Configure TypeScript to auto-include types

Add the types directory to tsconfig.json includes and remove the explicit import entirely.

Files to modify

1. docs/.vitepress/theme/types/gtag.d.ts → rename to gtag.ts (Option A)
2. docs/.vitepress/theme/composables/useGA4Tracking.ts → line 16 import path

Impact

• Documentation site is not being deployed to gitlab-mcp.sw.foundation
• All pushes to main since PR feat(docs): upgrade vue-privacy with GA4 tracking + dependency updates #284 have failed deployment
• 5 consecutive workflow failures