feat(nuxt): add enabled option in module config

[robinsimonklein]

Problem

Developers using the Nuxt module often need to disable PostHog in certain environments (testing, local development, staging). Currently, the only way to do this is to conditionally exclude the module from nuxt.config.ts, which can lead to runtime errors if code tries to use PostHog composables when the module isn't loaded.

Changes

Added an optional enabled configuration option to the Nuxt module

Behavior

• When enabled: false: PostHog client is not initialized, all composables return undefined, no events are sent
• When enabled: true or undefined: Normal behavior (backward compatible)

Release info Sub-libraries affected

Libraries affected

• All of them
• posthog-js (web)
• posthog-js-lite (web lite)
• posthog-node
• posthog-react-native
• @posthog/react
• @posthog/ai
• @posthog/nextjs-config
• @posthog/nuxt
• @posthog/rollup-plugin
• @posthog/webpack-plugin
• @posthog/types

Checklist

• Tests for new code (didn't find tests for @posthog/nuxt 👀 )
• Accounted for the impact of any changes across different platforms
• Accounted for backwards compatibility of any changes (no breaking changes!)
• Took care not to unnecessarily increase the bundle size

If releasing new changes

• Ran pnpm changeset to generate a changeset file
• Added the "release" label to the PR to indicate we're publishing new versions for the affected packages

[vercel]

@robinsimonklein is attempting to deploy a commit to the PostHog Team on Vercel.

A member of the Team first needs to authorize it.

[ablaszkiewicz]

@robinsimonklein - thanks for the contribution. It makes sense to add an option to disable it. I just think that making posthog undefined might cause some serious bugs. Imagine your code does this:

posthog.capture(...); // <-- execution will stop at this line with "Cannot read properties of undefined (reading 'capture')" 
someCrucialLogic();

I've checked and:

• in Node SDK (this would be nitro plugin) we allow passing disabled: true into posthog options,
• in browser SDK (this would be vue plugin) we do not have an explicit disable option but we expose opt_out_capturing_by_default - I am checking with the team whether this is the correct option because I am not sure. I'll update this thread once I figure this out.

I'm happy to merge this once we solve this :)

[robinsimonklein]

@ablaszkiewicz Good catch on the disabled option in the Node SDK! I just pushed the change.

For the browser SDK, I suspect opt_out_capturing_by_default is more for GDPR compliance, but let's wait for the
team's input.

My initial thinking was that optional chaining (posthog?.capture()) wouldn't be a major issue since enabled
defaults to true (no breaking changes). But you're right that it's not ideal for the DX.

[abdulhaq-e]

I think a good solution would be to use this suggested enabled property to override the loaded callback. The override would basically disable all kind of posthog functionality. This is what i'm currently doing (although the configuration is probably incomplete), inspired by the docs:

  posthogConfig: {
    publicKey: env.posthogApiKey,
    host: env.posthogApiHost,
    clientConfig: {
      autocapture: env.posthogEnabled,
      capture_exceptions: env.posthogAutocaptureExceptions,
      loaded: function (ph) {
        if (!env.posthogEnabled) {
          ph.opt_out_capturing();
          ph.set_config({ disable_session_recording: true });
        }
      },
    },
    sourcemaps: {
      enabled: env.posthogAutocaptureExceptions,
      envId: env.posthogProjectId,
      personalApiKey: env.posthogPersonalApiKey,
    },
  }

It's not the same as skipping posthog initialization but I think it is better DX compared to using optional chaining if the composable returns null.

[github-actions]

This PR hasn't seen activity in a week! Should it be merged, closed, or further worked on? If you want to keep it open, post a comment or remove the stale label – otherwise this will be closed in another week.

[github-actions]

This PR was closed due to lack of activity. Feel free to reopen if it's still relevant.