flags

Major Changes

• 1822587: BREAKING CHANGE: Configuration overhaul

  What

  This release changes HappyKit's configuration approach.

  Previously you had to create a flags.config.js file and import it into your pages/_app.js and into every middleware that wanted to use feature flags. If you were using your own AppFlags type, you also had to pass this type every time you invoked getFlags(), useFlags() or getEdgeFlags(). And the configuration options for client-, server- and edge were mixed together into a single flags.config.js file.

  Why

  This release replaces the existing configuration approach with a new one. This new approach configuration prepares happykit for upcoming features.

  How

  1. Add flags folder

  Follow the updated Setup instructions to create the flags folder in your own application, and fill it with.

  After this step, you should have

  • ./flags/config.ts which exports a configuration
  • ./flags/client.ts which exports a useFlags function
  • ./flags/server.ts which exports a getFlags function
  • ./flags/edge.ts which exports a getEdgeFlags function

  2. Set up absolute imports

  Enable Absolute Imports as described here.

  3. Adapt your imports

  Then change the application code in your pages/ folder to use these functions from your flags/ folder instead of from @happykit/flags:

  - import { useFlags } from "@happykit/flags/client"
  + import { useFlags } from "flags/client"
  

  - import { getFlags } from "@happykit/flags/server"
  + import { getFlags } from "flags/server"
  

  - import { getEdgeFlags } from "@happykit/flags/edge"
  + import { getEdgeFlags } from "flags/edge"
  

  _Note that because of the absolute imports we configured in step 2, all imports from "flags/" will use the local flags folder you created in step 1.*

  4. Delete your old setup

  We can now delete the old setup since we no longer need it

  • delete flags.config.js
  • remove the flags.config import from your pages/_app file
    • you might be able to delete the pages/_app file if it's not doing anything else anymore
  • remove the import of flags.config from your middleware

Adds support for node v18

• removes the AbortController polyfill. The AbortController is now only used if it exists as a global in the surrounding environment

• config did not update when used as esm bundle, introduced internal getConfig() to fix it #24

Breaking change

If you were doing import { config } from "@happykit/flags/config", you now need to import { getConfig } from "@happykit/flags/config". I believe most people are not importing config into their app.

This was a breaking I only realized after publishing as v2.0.6, so the sem ver does not reflect the breaking change. I apologize if this broke your build.

This is a special once-off release which is equal to v2.0.5, except for additional latency metrics reporting.

• remove unnecessary next.js dependency

• upgrades a bunch of dependencies

• Upgrades nanoid dependency to v3.2.0 to resolve a dependabot warning dc9728b65ad55590398537ce57cb2713cdc80db2

• logs a console warning when you invoke useFlags() simultaneously on the same page (details), 050419ac35671eec84138680025262c570eaee65 0730af0cd3c75601f5343a59b3eec3952207333d
• upgrades internal dependencies 74fe55d0bf4b74840f0cc0f907faaa2fae999cf7

diff

• internal: removes unused static field from generated requestBody, https://github.com/happykit/flags/pull/19

• adds support for Next.js Middleware
  • you can now use getEdgeFlags to load your flags in middleware
  • see a demo of using flags in middleware at flags.happykit.dev/demo/middleware

BREAKING CHANGES

• next v12.0.2 is now the new minimal peerDependency (as this is the first version supporting middleware and setting maxAge correctly)
  • older Next.js versions should still if you are not using getEdgeFlags
• we now recommend storing your config in flags.config.js as shown in the example and then importing flags.config into _app
  • note that configure() is now called from within flags.config.ts
  • note that configure() is no longer called in _app.tsx
  • calling configure() from flags.config.ts prepares you for loading flags in _middleware by importing flags.config

This release adds the ability to specify a timeout for loading flags on the server. Flags usually resolve within ~75ms, but in case something goes wrong the flag evaluation requests can now be aborted at a user-configured timeout.

The configuration option can be set globally in configure() for clientLoadingTimeout, serverLoadingTimeout and staticLoadingTimeout each.

The global configuration can be overwritten per page by useFlags and getFlags by specifying the loadingTimeout option.

Adds

• config.clientLoadingTimeout: The timeout used by useFlags on the client
• config.serverLoadingTimeout: The timeout used by getFlags inside of getServerSideProps (for server-side rendering)
• config.staticLoadingTimeout: The timeout used by getFlags inside of getStaticProps or getStaticPaths (for static site generation)

Deprecates

• configure({ loadingTimeout }). Use configure({ clientLoadingTimeout }) instead. It behaves the same, it was renamed only.

Full Changelog: https://github.com/happykit/flags/compare/v1.0.2...v1.1.0

• accept GetStaticPathsContext as context in getFlags({ context })

• adds missing export of FlagBag type to @happykit/flags/client

A complete rewrite of the @happykit/flags client

The main new features are that it supports

• rollouts
• user and traits
• instead of storing only the last request thing in localStorage it now uses a runtime cache for all requests
• acts in a stale-while-revalidate fashion, inspired by swr
• full support for any rendering scenario (client-side, server-side or static site generation)
• the client now supports a loadingTimeout after which it will fall back to the default flags

Technically this repo now contains an example which is deployed to flags.happykit.dev and we've switched to preconstruct.tools as the bundler.

Breaking changes

instead of a single entry point, the package now has multiple entry points

• @happykit/flags/config: Configuration functions
• @happykit/flags/server: Everything related to the server
• @happykit/flags/client: Everything related to the client
• @happykit/flags/context: A helper to pass the flagBag down through React's context

useFlags() returns an object instead of the flags

• flags are now be null while the flags are loading

// before
import { useFlags }  from "@happykit/flags"
const flags = useFlags()

// after
import { useFlags }  from "@happykit/flags/client"
const { flags } = useFlags()

The object returned from useFlags() is sometimes referred to as the flagBag. It has the following properties now:

const flagBag = useFlags()

flagBag.flags; // the feature flags or null, optimistically resolved from the cache
flagBag.data; // the feature flags as loaded from the server; does not use cache; does not use fallbacks
flagBag.error; // null or a a string; contains the reason the flags could not be loaded if "data" is null
flagBag.fetching; // boolean; true when the flags are currently being refetched
flagBag.settled; // boolean; true when the flags are not expected to change again (unless your input or flag definition changes)
flagBag.revalidate; // function which revalidates the flags for the given user and traits

See here for more information.

getFlags now returns an object instead of the flags

// before
import { useFlags, getFlags } from '@happykit/flags';

export default function FooPage(props) {
  const flags = useFlags({ initialFlags: props.initialFlags });
  return flags.xzibit ? 'Yo dawg' : 'Hello';
}

export const getServerSideProps = async () => {
  const initialFlags = await getFlags();
  return { props: { initialFlags } };
};

// after
import { useFlags } from "@happykit/flags/client";
import { getFlags } from "@happykit/flags/server";

export const getServerSideProps = async (context) => {
  const { initialFlagState } = await getFlags({ context });
  return { props: { initialFlagState } };
};

export default function FooPage(props) {
  const { flags } = useFlags({ initialState: props.initialFlagState });
  return flags?.xzibit ? 'Yo dawg' : 'Hello';
}

See here for more information.

configure

• configure now takes an envKey instead of a clientId

// before
import { configure } from '@happykit/flags';
configure({ clientId: process.env.NEXT_PUBLIC_FLAGS_CLIENT_ID });

// after
import { configure } from "@happykit/flags/config";
configure({ envKey: process.env.NEXT_PUBLIC_FLAGS_ENVIRONMENT_KEY });

See here for more information.

• add bootstrapping from localStorage #1
• add disableCaching option #1
• avoid multiple requests for same flags #1

• Export Flags type

breaking

• Remove usePrimitiveFlags export