feat: deprecate `featureFlags.override` in favor of `featureFlags.overrideFeatureFlags`, a new function that supports overriding flags and flag payloads #1697

dmarticus · 2025-01-28T19:26:46Z

Changes

The context for these changes are this feature request (#1304) and this slack thread: https://posthog.slack.com/archives/C07Q2U4BH4L/p1738088710814869. TL;DR – if folks want to use override to manage the value of the feature flag in the client side, I don't see any reason not to.

To make this change ergonomically (I was frustrated by the semantics of override, since to override payloads I'd have to do something like override($flagValue, $some_bool, $payload), instead of just letting users do override($flagValue, $payload) without needing to specify the override warning), I ended up deprecating override and replaced it with the more ergonomic overrideFeatureFlags. Even though override is deprecated, though, it still works – it just calls that new method under the hood. I added the @deprecated flag and a warning so that folks on the latest version of posthog-js move away from it.

Closes #1304

Updated the docs around this change to support using the new method, too: https://github.com/PostHog/posthog.com/pull/10528/files

Checklist

Tests for new code (see advice on the tests we use)
Accounted for the impact of any changes across different browsers
Accounted for backwards compatibility of any changes (no breaking changes in posthog-js!)

vercel · 2025-01-28T19:26:51Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
posthog-js	✅ Ready (Inspect)	Visit Preview	Jan 29, 2025 10:39pm

dmarticus · 2025-01-28T19:27:45Z

src/posthog-featureflags.ts

+        const overriddenPayloads = this.instance.get_property(PERSISTENCE_OVERRIDE_FEATURE_FLAG_PAYLOADS)
+
+        if (!overriddenPayloads) {
+            return flagPayloads || {}
+        }
+
+        const finalPayloads = extend({}, flagPayloads || {})
+        const overriddenKeys = Object.keys(overriddenPayloads)
+        for (let i = 0; i < overriddenKeys.length; i++) {
+            finalPayloads[overriddenKeys[i]] = overriddenPayloads[overriddenKeys[i]]
+        }
+        return finalPayloads


same pattern that we do in getFlags

dmarticus · 2025-01-28T19:30:15Z

src/posthog-featureflags.ts

+        if (triggerFlagEvent) {
+            this._fireFeatureFlagsCallbacks()


this should be sufficient to trigger hooks like useFeatureFlagEnabled, which is what I was yapping about here: https://posthog.slack.com/archives/C07Q2U4BH4L/p1738088710814869

github-actions · 2025-01-28T19:31:01Z

Size Change: +10.2 kB (+0.31%)

Total Size: 3.29 MB

Filename	Size	Change
`dist/array.full.es5.js`	267 kB	+1.04 kB (+0.39%)
`dist/array.full.js`	370 kB	+1.02 kB (+0.28%)
`dist/array.full.no-external.js`	369 kB	+1.02 kB (+0.28%)
`dist/array.js`	182 kB	+1.02 kB (+0.56%)
`dist/array.no-external.js`	181 kB	+1.02 kB (+0.57%)
`dist/main.js`	183 kB	+1.02 kB (+0.56%)
`dist/module.full.js`	370 kB	+1.02 kB (+0.28%)
`dist/module.full.no-external.js`	369 kB	+1.02 kB (+0.28%)
`dist/module.js`	182 kB	+1.02 kB (+0.56%)
`dist/module.no-external.js`	181 kB	+1.02 kB (+0.57%)

ℹ️ View Unchanged

Filename	Size
`dist/all-external-dependencies.js`	215 kB
`dist/customizations.full.js`	13.8 kB
`dist/dead-clicks-autocapture.js`	14.5 kB
`dist/exception-autocapture.js`	9.48 kB
`dist/external-scripts-loader.js`	2.64 kB
`dist/recorder-v2.js`	115 kB
`dist/recorder.js`	115 kB
`dist/surveys-preview.js`	68.8 kB
`dist/surveys.js`	71.8 kB
`dist/tracing-headers.js`	1.76 kB
`dist/web-vitals.js`	10.4 kB

_{compressed-size-action}

dmarticus · 2025-01-28T19:38:07Z

src/posthog-featureflags.ts

+     * @param {boolean} [triggerFlagEvent] Optional parameter to trigger the _fireFeatureFlagsCallbacks() event.
+     * If set to true, calling `override` will trigger the callback, which is useful for triggering things like the `useFeatureFlagEnabled` hook.


should I make this default true? It's definitely new behavior, but perhaps users want it? Just saw this thread on this type of thing and it seems like the user is expecting that override methods work like bootstrapping methods.

I think so and would even go as far as to say we might not even want to add an argument for this? Even our docs seem to communicate overrides as being the same as bootstraps outside of how long the value is persisted: https://posthog.com/docs/feature-flags/bootstrapping#overriding-feature-flags

havenbarnes

Nice improvement and test coverage!

…reloads

dmarticus · 2025-01-29T21:30:50Z

src/posthog-featureflags.ts

-     * Override feature flags on the client-side.  Useful for setting non-persistent feature flags, or for testing/debugging
-     * feature flags in the PostHog app.
+    /**
+     * @deprecated Use overrideFeatureFlags instead. This will be removed in a future version.


added the deprecated tag, so users of this latest version will see the warning in their IDE like this

dmarticus · 2025-01-29T21:31:02Z

src/posthog-featureflags.ts

+     * @deprecated Use overrideFeatureFlags instead. This will be removed in a future version.
+     */
+    override(flags: boolean | string[] | Record<string, string | boolean>, suppressWarning: boolean = false): void {
+        logger.warn('override is deprecated. Please use overrideFeatureFlags instead.')


logging a deprecation warning too; is this overkill? cc @havenbarnes

Seems reasonable to me, good to have the forcing function so no one gets completely blindsided later when this gets removed

dmarticus · 2025-01-29T21:31:18Z

src/posthog-featureflags.ts

     */
-    override(flags: boolean | string[] | Record<string, string | boolean>, suppressWarning: boolean = false): void {
+    overrideFeatureFlags(


implement the new method here

nit: if we're here changing the shape of the method signature anyway, should we go ahead and transition to a single object parameter (I'd suggest making flags optional too) to keep things nice and clean?

Reason I bring this up is that if someone is only interested in overriding payloads, they will always have to pass some empty value in for flags which is a tad annoying

handled this

havenbarnes

Looks good, left one nit on the new method's arguments. Also we'll wanna update the code example here https://posthog.com/docs/feature-flags/bootstrapping#overriding-feature-flags

dmarticus · 2025-01-29T23:12:28Z

Looks good, left one nit on the new method's arguments. Also we'll wanna update the code example here posthog.com/docs/feature-flags/bootstrapping#overriding-feature-flags

yup, doing that here: PostHog/posthog.com#10528

impl and tests, needs docs but that's a posthog.com thing

9e5170d

vercel bot deployed to Preview January 28, 2025 19:27 View deployment

fix docs

fb90322

dmarticus commented Jan 28, 2025

View reviewed changes

vercel bot deployed to Preview January 28, 2025 19:35 View deployment

dmarticus commented Jan 28, 2025

View reviewed changes

dmarticus requested a review from havenbarnes January 28, 2025 21:43

havenbarnes approved these changes Jan 28, 2025

View reviewed changes

dmarticus added the bump minor Bump minor version when this PR gets merged label Jan 28, 2025

dmarticus added 2 commits January 28, 2025 14:22

trigger callbacks on manual overrides every time

518a777

deprecate and override

a07dc9e

vercel bot deployed to Preview January 29, 2025 20:12 View deployment

Merge branch 'main' into feat/support-payload-overrides-and-override-…

07bc1fb

…reloads

dmarticus mentioned this pull request Jan 29, 2025

feat(toolbar): support feature flag payload overrides in the flag toolbar PostHog/posthog#28058

Merged

dmarticus commented Jan 29, 2025

View reviewed changes

havenbarnes approved these changes Jan 29, 2025

View reviewed changes

do the thing

d41ff54

vercel bot deployed to Preview January 29, 2025 22:33 View deployment

logs

506c412

vercel bot deployed to Preview January 29, 2025 22:39 View deployment

dmarticus changed the title ~~feat: deprecate featureFlags.override in favor of featureFlags.overrideFeatureFlags~~ feat: deprecate featureFlags.override in favor of featureFlags.overrideFeatureFlags, a new function that supports both override flags and overriding flag payloads Jan 29, 2025

dmarticus mentioned this pull request Jan 29, 2025

chore(flags): update docs to support new overrideFeatureFlags method PostHog/posthog.com#10528

Merged

dmarticus merged commit 690773b into main Jan 30, 2025
32 checks passed

dmarticus deleted the feat/support-payload-overrides-and-override-reloads branch January 30, 2025 18:51

dmarticus mentioned this pull request Feb 3, 2025

Flags sprint Feb 7 - Feb 21 PostHog/posthog#28216

Open

dmarticus mentioned this pull request Feb 5, 2025

Sprint - Feb 10 - Feb 21 PostHog/posthog#28311

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: deprecate `featureFlags.override` in favor of `featureFlags.overrideFeatureFlags`, a new function that supports overriding flags and flag payloads #1697

feat: deprecate `featureFlags.override` in favor of `featureFlags.overrideFeatureFlags`, a new function that supports overriding flags and flag payloads #1697

dmarticus commented Jan 28, 2025 •

edited

Loading

vercel bot commented Jan 28, 2025 •

edited

Loading

dmarticus Jan 28, 2025

dmarticus Jan 28, 2025

github-actions bot commented Jan 28, 2025 •

edited

Loading

dmarticus Jan 28, 2025

havenbarnes Jan 28, 2025 •

edited

Loading

havenbarnes left a comment

dmarticus Jan 29, 2025

dmarticus Jan 29, 2025

havenbarnes Jan 29, 2025

dmarticus Jan 29, 2025

havenbarnes Jan 29, 2025 •

edited

Loading

dmarticus Jan 29, 2025

havenbarnes left a comment

dmarticus commented Jan 29, 2025

		* @param {boolean} [triggerFlagEvent] Optional parameter to trigger the _fireFeatureFlagsCallbacks() event.
		* If set to true, calling `override` will trigger the callback, which is useful for triggering things like the `useFeatureFlagEnabled` hook.

feat: deprecate featureFlags.override in favor of featureFlags.overrideFeatureFlags, a new function that supports overriding flags and flag payloads #1697

feat: deprecate featureFlags.override in favor of featureFlags.overrideFeatureFlags, a new function that supports overriding flags and flag payloads #1697

Conversation

dmarticus commented Jan 28, 2025 • edited Loading

Changes

Checklist

vercel bot commented Jan 28, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Jan 28, 2025 • edited Loading

Choose a reason for hiding this comment

havenbarnes Jan 28, 2025 • edited Loading

Choose a reason for hiding this comment

havenbarnes left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

havenbarnes Jan 29, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

havenbarnes left a comment

Choose a reason for hiding this comment

dmarticus commented Jan 29, 2025

feat: deprecate `featureFlags.override` in favor of `featureFlags.overrideFeatureFlags`, a new function that supports overriding flags and flag payloads #1697

feat: deprecate `featureFlags.override` in favor of `featureFlags.overrideFeatureFlags`, a new function that supports overriding flags and flag payloads #1697

dmarticus commented Jan 28, 2025 •

edited

Loading

vercel bot commented Jan 28, 2025 •

edited

Loading

github-actions bot commented Jan 28, 2025 •

edited

Loading

havenbarnes Jan 28, 2025 •

edited

Loading

havenbarnes Jan 29, 2025 •

edited

Loading