feat: warn on misconfigured NUXT_PUBLIC_SCRIPTS_* env vars (#778)

Author: harlan-zw

packages/script/src/module.ts

@@ -40,6 +40,7 @@ import { generateInterceptPluginContents } from './plugins/intercept'
 import{NuxtScriptBundleTransformer}from'./plugins/transform'
 import{buildProxyConfigsFromRegistry,generatePartytownResolveUrl,getPartytownForwards,registry,resolveCapabilities}from'./registry'
 import{registerTypeTemplates,templatePlugin,templateTriggerResolver}from'./templates'
+import{validateScriptsEnvVars}from'./validate-env'
 
 exporttype{FirstPartyPrivacy}
 
@@ -556,6 +557,14 @@ export default defineNuxtModule<ModuleOptions>({
 )
 }
 
+// Surface env vars under `NUXT_PUBLIC_SCRIPTS_*` that won't be consumed:
+// wrong key (typo / marketing name), wrong field, or script not registered.
+validateScriptsEnvVars(
+scripts,
+newSet(Object.keys(config.registry||{}).filter(k=>(config.registryasany)?.[k]!==false)),
+logger,
+)
+
 // Setup runtimeConfig for proxies and devtools.
 // Must run AFTER env var resolution above so the API key is populated.
 constgoogleMapsEnabled=config.googleStaticMapsProxy?.enabled||!!config.registry?.googleMaps

packages/script/src/validate-env.ts

@@ -0,0 +1,163 @@
+importtype{ConsolaInstance}from'consola'
+importtype{RegistryScript}from'./runtime/types'
+
+constUPPER_RE=/([A-Z])/g
+consttoScreamingSnake=(s: string)=>s.replace(UPPER_RE,'_$1').toUpperCase()
+
+constENV_PREFIX='NUXT_PUBLIC_SCRIPTS_'
+
+functionlevenshtein(a: string,b: string): number{
+if(a===b)
+return0
+if(!a.length)
+returnb.length
+if(!b.length)
+returna.length
+constprev: number[]=[]
+for(letj=0;j<=b.length;j++)prev.push(j)
+for(leti=1;i<=a.length;i++){
+letprevDiag=prev[0]!
+prev[0]=i
+for(letj=1;j<=b.length;j++){
+consttmp=prev[j]!
+prev[j]=a[i-1]===b[j-1]
+ ? prevDiag
+ : Math.min(prevDiag,prev[j]!,prev[j-1]!)+1
+prevDiag=tmp
+}
+}
+returnprev[b.length]!
+}
+
+/**
+ * Warn for `NUXT_PUBLIC_SCRIPTS_*` env vars that don't map to a valid registry
+ * key + field. Nuxt resolves env vars against runtimeConfig before modules run,
+ * so a misspelled key (e.g. `NUXT_PUBLIC_SCRIPTS_MICROSOFT_CLARITY_ID` instead
+ * of `NUXT_PUBLIC_SCRIPTS_CLARITY_ID`) is silently dropped with no error.
+ */
+exportfunctionvalidateScriptsEnvVars(
+scripts: RegistryScript[],
+enabledRegistryKeys: Set<string>,
+logger: ConsolaInstance,
+): void{
+// Build a map from screaming-snake registry key to its envDefaults fields
+constvalidByKey=newMap<string,{camel: string,fields: Set<string>}>()
+for(constsofscripts){
+if(!s.registryKey||!s.envDefaults||!Object.keys(s.envDefaults).length)
+continue
+constscreaming=toScreamingSnake(s.registryKey)
+constfields=newSet(Object.keys(s.envDefaults).map(toScreamingSnake))
+validByKey.set(screaming,{camel: s.registryKey, fields })
+}
+
+if(!validByKey.size)
+return
+
+constallValidEnvKeys: string[]=[]
+for(const[screaming,{ fields }]ofvalidByKey){
+for(constfoffields)
+allValidEnvKeys.push(`${ENV_PREFIX}${screaming}_${f}`)
+}
+
+for(constenvKeyofObject.keys(process.env)){
+if(!envKey.startsWith(ENV_PREFIX))
+continue
+if(allValidEnvKeys.includes(envKey))
+continue
+
+constsegment=envKey.slice(ENV_PREFIX.length)
+
+// Case 1: matches a valid registry key but unknown field
+letmatchedKey: {screaming: string,camel: string,fields: Set<string>}|undefined
+for(const[screaming,info]ofvalidByKey){
+if(segment===screaming||segment.startsWith(`${screaming}_`)){
+matchedKey={ screaming, ...info}
+break
+}
+}
+
+if(matchedKey){
+constfield=segment.slice(matchedKey.screaming.length+1)
+logger.warn(
+`[scripts] env var \`${envKey}\` does not match any option on \`${matchedKey.camel}\`. `
++`Valid fields: ${[...matchedKey.fields].map(f=>`\`${ENV_PREFIX}${matchedKey!.screaming}_${f}\``).join(', ')}.${
+field ? ` Got: \`${field}\`.` : ''}`,
+)
+continue
+}
+
+// Case 2: registry key appears as a substring of the segment (e.g.
+// `MICROSOFT_CLARITY_ID` contains `CLARITY`). Likely a marketing-name
+// prefix; suggest the canonical key, and if the remainder is a valid
+// field, suggest the full corrected env var.
+constsegmentParts=segment.split('_')
+letsubstringMatch: {screaming: string,camel: string,fields: Set<string>,remainder: string}|undefined
+for(const[screaming,info]ofvalidByKey){
+constkeyParts=screaming.split('_')
+for(leti=0;i<=segmentParts.length-keyParts.length;i++){
+letok=true
+for(letj=0;j<keyParts.length;j++){
+if(segmentParts[i+j]!==keyParts[j]){
+ok=false
+break
+}
+}
+if(ok){
+substringMatch={
+ screaming,
+camel: info.camel,
+fields: info.fields,
+remainder: segmentParts.slice(i+keyParts.length).join('_'),
+}
+break
+}
+}
+if(substringMatch)
+break
+}
+
+letsuggestion=''
+if(substringMatch){
+if(substringMatch.remainder&&substringMatch.fields.has(substringMatch.remainder)){
+suggestion=` Did you mean \`${ENV_PREFIX}${substringMatch.screaming}_${substringMatch.remainder}\` (registry key \`${substringMatch.camel}\`)?`
+}
+else{
+suggestion=` Did you mean registry key \`${substringMatch.camel}\` (\`${ENV_PREFIX}${substringMatch.screaming}_*\`)?`
+}
+}
+else{
+// Fallback: closest registry key by edit distance on the leading parts
+letbest: {key: string,camel: string,dist: number}|undefined
+for(const[screaming,info]ofvalidByKey){
+consthead=segmentParts.slice(0,screaming.split('_').length).join('_')
+constd=levenshtein(head,screaming)
+if(!best||d<best.dist)
+best={key: screaming,camel: info.camel,dist: d}
+}
+if(best&&best.dist<=Math.max(2,Math.floor(best.key.length/2)))
+suggestion=` Did you mean registry key \`${best.camel}\` (\`${ENV_PREFIX}${best.key}_*\`)?`
+}
+
+logger.warn(
+`[scripts] env var \`${envKey}\` does not map to any registered script.${
+suggestion}`,
+)
+}
+
+// Case 3: env var maps to a known script that the user hasn't enabled in
+// their nuxt.config registry. The value gets resolved into runtimeConfig
+// but won't be consumed unless the script is registered.
+for(const[screaming,info]ofvalidByKey){
+if(enabledRegistryKeys.has(info.camel))
+continue
+for(constfieldofinfo.fields){
+constenvKey=`${ENV_PREFIX}${screaming}_${field}`
+if(process.env[envKey]!==undefined){
+logger.warn(
+`[scripts] env var \`${envKey}\` is set but \`${info.camel}\` is not registered in \`scripts.registry\`. `
++`Add \`registry: { ${info.camel}: {} }\` to your nuxt.config for it to take effect.`,
+)
+}
+}
+}
+}

test/unit/validate-env.test.ts

@@ -0,0 +1,88 @@
+importtype{ConsolaInstance}from'consola'
+importtype{RegistryScript}from'../../packages/script/src/runtime/types'
+import{afterEach,beforeEach,describe,expect,it,vi}from'vitest'
+import{validateScriptsEnvVars}from'../../packages/script/src/validate-env'
+
+constscripts=[
+{registryKey: 'clarity',envDefaults: {id: ''}},
+{registryKey: 'facebookPixel',envDefaults: {id: ''}},
+{registryKey: 'matomoAnalytics',envDefaults: {matomoUrl: '',siteId: ''}},
+]asunknownasRegistryScript[]
+
+functionmakeLogger(){
+return{warn: vi.fn()}asunknownasConsolaInstance
+}
+
+describe('validateScriptsEnvVars',()=>{
+constremoveKeys: string[]=[]
+
+beforeEach(()=>{
+for(constkofObject.keys(process.env)){
+if(k.startsWith('NUXT_PUBLIC_SCRIPTS_'))
+deleteprocess.env[k]
+}
+})
+
+afterEach(()=>{
+for(constkofremoveKeys.splice(0))
+deleteprocess.env[k]
+})
+
+it('does not warn for valid env var on enabled script',()=>{
+process.env.NUXT_PUBLIC_SCRIPTS_CLARITY_ID='abc'
+removeKeys.push('NUXT_PUBLIC_SCRIPTS_CLARITY_ID')
+constlogger=makeLogger()
+validateScriptsEnvVars(scripts,newSet(['clarity']),logger)
+expect(logger.warn).not.toHaveBeenCalled()
+})
+
+it('warns when env var uses marketing name instead of registry key',()=>{
+process.env.NUXT_PUBLIC_SCRIPTS_MICROSOFT_CLARITY_ID='abc'
+removeKeys.push('NUXT_PUBLIC_SCRIPTS_MICROSOFT_CLARITY_ID')
+constlogger=makeLogger()
+validateScriptsEnvVars(scripts,newSet(['clarity']),logger)
+expect(logger.warn).toHaveBeenCalledTimes(1)
+constmsg=(logger.warnasany).mock.calls[0][0]asstring
+expect(msg).toContain('NUXT_PUBLIC_SCRIPTS_MICROSOFT_CLARITY_ID')
+expect(msg).toContain('clarity')
+})
+
+it('warns when field is unknown on a valid key',()=>{
+process.env.NUXT_PUBLIC_SCRIPTS_CLARITY_FOO='x'
+removeKeys.push('NUXT_PUBLIC_SCRIPTS_CLARITY_FOO')
+constlogger=makeLogger()
+validateScriptsEnvVars(scripts,newSet(['clarity']),logger)
+expect(logger.warn).toHaveBeenCalledTimes(1)
+constmsg=(logger.warnasany).mock.calls[0][0]asstring
+expect(msg).toContain('does not match any option on `clarity`')
+expect(msg).toContain('NUXT_PUBLIC_SCRIPTS_CLARITY_ID')
+})
+
+it('warns when env var is set but script not registered',()=>{
+process.env.NUXT_PUBLIC_SCRIPTS_CLARITY_ID='abc'
+removeKeys.push('NUXT_PUBLIC_SCRIPTS_CLARITY_ID')
+constlogger=makeLogger()
+validateScriptsEnvVars(scripts,newSet(),logger)
+expect(logger.warn).toHaveBeenCalledTimes(1)
+constmsg=(logger.warnasany).mock.calls[0][0]asstring
+expect(msg).toContain('is not registered')
+expect(msg).toContain('clarity')
+})
+
+it('handles camelCase registry keys',()=>{
+process.env.NUXT_PUBLIC_SCRIPTS_FACEBOOK_PIXEL_ID='abc'
+removeKeys.push('NUXT_PUBLIC_SCRIPTS_FACEBOOK_PIXEL_ID')
+constlogger=makeLogger()
+validateScriptsEnvVars(scripts,newSet(['facebookPixel']),logger)
+expect(logger.warn).not.toHaveBeenCalled()
+})
+
+it('handles multi-field scripts',()=>{
+process.env.NUXT_PUBLIC_SCRIPTS_MATOMO_ANALYTICS_SITE_ID='1'
+process.env.NUXT_PUBLIC_SCRIPTS_MATOMO_ANALYTICS_MATOMO_URL='https://x'
+removeKeys.push('NUXT_PUBLIC_SCRIPTS_MATOMO_ANALYTICS_SITE_ID','NUXT_PUBLIC_SCRIPTS_MATOMO_ANALYTICS_MATOMO_URL')
+constlogger=makeLogger()
+validateScriptsEnvVars(scripts,newSet(['matomoAnalytics']),logger)
+expect(logger.warn).not.toHaveBeenCalled()
+})
+})