feat(gtm): debug logging and consent key validation

[harlan-zw]

❓ Type of change

• 📖 Documentation
• 🐞 Bug fix
• 👌 Enhancement
• ✨ New feature
• 🧹 Chore
• ⚠️ Breaking change

📚 Description

Adds an opt-in debug surface for the script registry so misconfigured GTM consent setups surface clear warnings instead of failing silently. A build-time __NUXT_SCRIPTS_DEBUG__ constant is injected via Vite define and Nitro replace, so debug branches DCE in production when debug: false.

When debug is enabled (or in dev), useRegistryScript traces register/load/error events through consola. GTM additionally:

• Validates GCMv2 keys in both defaultConsent and consent.update() payloads, catching typos like analytics_storages or ad_storag.
• Warns when consent.update() runs before any consent default has been queued on the dataLayer, since GTM may apply implicit defaults and create races with downstream tags.

Covered by 5 new tests in test/nuxt-runtime/consent-default.nuxt.test.ts (26 total passing).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
scripts-playground	Ready	Preview, Comment	May 9, 2026 3:25am

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@nuxt/scripts@760

commit: b710d2c

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ffea39e1-37b4-4860-a924-c348e49e4511

📥 Commits

Reviewing files that changed from the base of the PR and between 727e025 and b710d2c.

📒 Files selected for processing (5)

• packages/script/src/module.ts
• packages/script/src/runtime/logger.ts
• packages/script/src/runtime/registry/google-tag-manager.ts
• packages/script/src/runtime/utils.ts
• test/nuxt-runtime/consent-default.nuxt.test.ts

---

📝 Walkthrough

Walkthrough

This PR implements a build-time debug logging system for Nuxt Scripts. It introduces a __NUXT_SCRIPTS_DEBUG__ constant configured from config.debug, integrated into the bundler to enable dead-code elimination. The logger is then configured to respect this flag along with dev mode, enabling debug-level output conditionally. Debug validation and logging are added to Google Tag Manager consent handling to validate consent keys and trace initialization and updates. Script registration in useRegistryScript gains conditional debug output for registration, load, and error events. Tests verify the entire system including consent warning behavior and logger trace calls.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main enhancement: adding debug logging and consent key validation for GTM, which aligns with the primary changes across all modified files.
Description check	✅ Passed	The description is directly related to the changeset, providing clear context about the build-time debug constant, debug logging via consola, GTM consent key validation, and warning logic with test coverage.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/gtm-consent-debug

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}