feat: warn on misconfigured NUXT_PUBLIC_SCRIPTS_* env vars

[harlan-zw]

🔗 Linked issue

Resolves #769

❓ Type of change

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

📚 Description

Nuxt resolves env vars against runtimeConfig before modules run, so a mistyped NUXT_PUBLIC_SCRIPTS_* key (e.g. the marketing name NUXT_PUBLIC_SCRIPTS_MICROSOFT_CLARITY_ID instead of the registry key NUXT_PUBLIC_SCRIPTS_CLARITY_ID) gets silently dropped and the script loads with an empty option. This is what bit the reporter in #769, and it's a class of error that will keep happening.

Adds a build-time scan over process.env that warns when a NUXT_PUBLIC_SCRIPTS_* var can't be resolved, with three cases:

1. Unknown registry key — substring-matches against known keys to suggest a correction. MICROSOFT_CLARITY_ID → Did you mean \NUXT_PUBLIC_SCRIPTS_CLARITY_ID` (registry key `clarity`)?`
2. Unknown field on a valid key — CLARITY_FOO → lists the valid fields for clarity.
3. Valid key, script not registered — env var is set but the script isn't in scripts.registry, so the value won't be consumed. Suggests adding registry: { <key>: {} }.

Supersedes #774, which only documented the Clarity case; this catches it (and the same mistake on every other script) at build time.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
scripts-playground	Ready	Preview, Comment	May 14, 2026 6:20am

[pkg-pr-new]

Open in StackBlitz

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

commit: ecbcb37

[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: 71a861ae-b5f2-462f-97b2-2479579551da

📥 Commits

Reviewing files that changed from the base of the PR and between fb50b0a and ecbcb37.

📒 Files selected for processing (3)

• packages/script/src/module.ts
• packages/script/src/validate-env.ts
• test/unit/validate-env.test.ts

---

📝 Walkthrough

Walkthrough

This PR adds validation for NUXT_PUBLIC_SCRIPTS_* environment variables during Nuxt module setup. A new validateScriptsEnvVars function scans process.env and cross-checks against the scripts registry, warning when env vars reference unknown script fields, have typos in registry keys (via Levenshtein distance), or are set for scripts that aren't registered/enabled. The function is invoked during module setup, and comprehensive unit tests verify all warning scenarios.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% 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 accurately reflects the main change: adding validation/warnings for misconfigured NUXT_PUBLIC_SCRIPTS_* environment variables during build time.
Description check	✅ Passed	The description is directly related to the changeset, explaining the motivation (issue #769), the three warning cases implemented, and how this supersedes previous documentation-only PR #774.
Linked Issues check	✅ Passed	The PR successfully addresses issue #769 by implementing build-time detection of misconfigured NUXT_PUBLIC_SCRIPTS_* env vars with warnings for unknown registry keys, unknown fields, and disabled scripts.
Out of Scope Changes check	✅ Passed	All changes are directly related to the objective of validating NUXT_PUBLIC_SCRIPTS_* environment variables: module integration, validation logic implementation, and comprehensive unit tests.

_{✏️ 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 fix/validate-misconfigured-env-vars

---

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.}