Allow conditionally enabling the module

[DamianGlowala]

Describe the feature

Currently, there doesn't seem to be a way to conditionally enable the module. This is what I would ideally imagine:

gtag: {
  id: import.meta.env.GOOGLE_ANALYTICS_ID,
  enabled: !!import.meta.env.GOOGLE_ANALYTICS_ID
}

Sadly, enabled is used for a different purpose, which is confusing. Could we consider renaming current enabled option to a more descriptive one, please (e.g. initializationMode: 'auto' | 'manual')? (Yes, this would be a breaking change but worth it in my opinion.)

Additional information

• [ ] Would you be willing to help implement this feature?
• [ ] Can you think of other implementations of this feature?

Final checks

• [X] Check existing issues.

[johannschopplich]

Great idea! I've seen enabled being used in other modules. Is this some kind of hidden convention?

[DamianGlowala]

From my perspective, it depends on the module. This one sounds like a good one to have the enabled option, as some users might want to enable it conditionally (e.g. based on the presence of the environment variable for the GTAG ID, or their preference on the environment in which the app runs, i.e. dev/stage/prod).

It would be as easy as adding the following snippet at the start of the module setup function:

if (!options.enabled) {
  return
}

[johannschopplich]

What I generally dislike about this approach for a enabled option is that it breaks auto-imports... I mean, if the user want's to disable the model altogether, he might as well remove it from his Nuxt config? Tricky one. 😄

But yeah, if other modules provide this option that it might be best to add support for enabled to keep the ecosystem aligned.

[DamianGlowala]

Would you say more about how this approach might break auto-imports? If we return from the module's setup function early, none of the imports/plugins will be added. Let me know if there's something more to consider here I might have overlooked 😄 https://github.com/johannschopplich/nuxt-gtag/blob/4f6a6345570fda14285802eb1dcafae1492a99a1/src/module.ts#L119 https://github.com/johannschopplich/nuxt-gtag/blob/4f6a6345570fda14285802eb1dcafae1492a99a1/src/module.ts#L128

And, to be very clear, we are talking about disabling the module conditionally, when the condition is some form of a variable.

[DamianGlowala]

I know what you mean now. Yes, the code using whatever this module exports will break when enabled: false. Other alternative would be:

export default defineNuxtConfig({
  modules: [
    'other-module',
    ...(import.meta.env.GOOGLE_ANALYTICS_ID ? ['nuxt-gtag'] : [])
  ]
})

... but, this would mean we would have to add the config with the same condition (and just checked that we lose autocompletion for module config by doing it this way):

export default defineNuxtConfig({
  otherConfig: {},
  ...(import.meta.env.GOOGLE_ANALYTICS_ID ? {
    gtag: {
      id: import.meta.env.GOOGLE_ANALYTICS_ID
    }
  } : {})
})

What do you think?

[johannschopplich]

After much consideration and a lot of feedback from the community, I've changed the module API to properly support conditionally disabling the module. Fixed in: https://github.com/johannschopplich/nuxt-gtag/commit/f9080102e9e13b9b66342da0a3ea646b5b44c5f3

In v2.x and earlier, the enabled option was used to control manual initialization of the Google tag script. This option has been replaced with initMode in v3.x. To migrate your configuration, set the initMode option to manual:

export default defineNuxtConfig({
  modules: ['nuxt-gtag'],

  gtag: {
-    enabled: false,
+    initMode: 'manual',
    id: 'GX-XXXXXXXXXX'
  }
})

The enabled option is still available in v3.x, but is now used to disable the Google tag module for the current environment. This is useful if you want to disable the module in development or staging environments:

export default defineNuxtConfig({
  modules: ['nuxt-gtag'],

  gtag: {
    enabled: process.env.NODE_ENV === 'production',
    id: 'G-XXXXXXXXXX'
  }
})