Add sample feature flagging system to next.js template

.gitignore

@@ -2,3 +2,4 @@
 .DS_Store
 # Developer-specific IDE settings
 .vscode
+.env.local

app/.env.development

@@ -5,3 +5,6 @@
 
 # If you deploy to a subpath, change this to the subpath so relative paths work correctly.
 NEXT_PUBLIC_BASE_PATH=
+
+# AWS Evidently Feature Flag variables
+FEATURE_FLAGS_PROJECT=

app/package.json

@@ -19,6 +19,7 @@
     "ts:check": "tsc --noEmit"
   },
   "dependencies": {
+    "@aws-sdk/client-evidently": "^3.465.0",
     "@trussworks/react-uswds": "^6.0.0",
     "@uswds/uswds": "3.7.0",
     "lodash": "^4.17.21",

app/src/i18n/messages/en-US/index.ts

@@ -19,6 +19,10 @@ export const messages = {
     intro:
       "This is a template for a React web application using the <LinkToNextJs>Next.js framework</LinkToNextJs>.",
     body: "This is template includes:<ul><li>Framework for server-side rendered, static, or hybrid React applications</li><li>TypeScript and React testing tools</li><li>U.S. Web Design System for themeable styling and a set of common components</li><li>Type checking, linting, and code formatting tools</li><li>Storybook for a frontend workshop environment</li></ul>",
+    featureflagging:
+      "The template includes AWS Evidently for feature flagging. Toggle flag to see the content below change:",
+    flagoff: "Flag is disabled",
+    flagon: "Flag is enabled",
     formatting:
       "The template includes an internationalization library with basic formatters built-in. Such as numbers: { amount, number, currency }, and dates: { isoDate, date, long}.",
   },

app/src/pages/index.tsx

@@ -1,10 +1,21 @@
-import type { GetServerSideProps, NextPage } from "next";
+import type {
+  GetServerSideProps,
+  InferGetServerSidePropsType,
+  NextPage,
+} from "next";
 import { getMessagesWithFallbacks } from "src/i18n/getMessagesWithFallbacks";
+import { isFeatureEnabled } from "src/services/feature-flags";
 
 import { useTranslations } from "next-intl";
 import Head from "next/head";
 
-const Home: NextPage = () => {
+interface PageProps {
+  isFooEnabled: boolean;
+}
+
+const Home: NextPage<InferGetServerSidePropsType<typeof getServerSideProps>> = (
+  props: PageProps
+) => {
   const t = useTranslations("home");
 
   return (
@@ -36,16 +47,25 @@ const Home: NextPage = () => {
             isoDate: new Date("2023-11-29T23:30:00.000Z"),
           })}
         </p>
+
+        {/* Demonstration of feature flagging */}
+        <p>{t("featureflagging")}</p>
+        {props.isFooEnabled ? <p>^..^{t("flagon")}</p> : <p>{t("flagoff")}</p>}
       </div>
     </>
   );
 };
 
 // Change this to getStaticProps if you're not using server-side rendering
-export const getServerSideProps: GetServerSideProps = async ({ locale }) => {
+export const getServerSideProps: GetServerSideProps<PageProps> = async ({
+  locale,
+}) => {
+  const isFooEnabled = await isFeatureEnabled("foo", "anonymous");
+
   return {
     props: {
       messages: await getMessagesWithFallbacks(locale),
+      isFooEnabled,
     },
   };
 };

app/src/services/feature-flags/FeatureFlagManager.ts

@@ -0,0 +1,52 @@
+import { Evidently } from "@aws-sdk/client-evidently";
+
+/**
+ * Class for managing feature flagging via AWS Evidently.
+ * Class method are available for use in next.js server side code.
+ *
+ * https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/evidently/
+ *
+ */
+export class FeatureFlagManager {
+  client: Evidently;
+  private _project = process.env.FEATURE_FLAGS_PROJECT;
+
+  constructor() {
+    this.client = new Evidently();
+  }
+
+  async isFeatureEnabled(featureName: string, userId: string) {
+    const evalRequest = {
+      entityId: userId,
+      feature: featureName,
+      project: this._project,
+    };
+
+    let featureFlagValue = false;
+    try {
+      const evaluation = await this.client.evaluateFeature(evalRequest);
+      if (evaluation && evaluation.value?.boolValue !== undefined) {
+        featureFlagValue = evaluation.value.boolValue;
+        console.log({
+          message: "Made feature flag evaluation with AWS Evidently",
+          data: {
+            reason: evaluation.reason,
+            userId: userId,
+            featureName: featureName,
+            featureFlagValue: featureFlagValue,
+          },
+        });
+      }
+    } catch (e) {
+      console.error({
+        message: "Error retrieving feature flag variation from AWS Evidently",
+        data: {
+          err: e,
+          userId: userId,
+          featureName: featureName,
+        },
+      });
+    }
+    return featureFlagValue;
+  }
+}

app/src/services/feature-flags/LocalFeatureFlagManager.ts

@@ -0,0 +1,8 @@
+export class LocalFeatureFlagManager {
+  async isFeatureEnabled(featureName: string, userId: string) {
+    console.log(
+      `Using mock feature flag manager for feature ${featureName}, user ${userId}`
+    );
+    return Promise.resolve(false);
+  }
+}

app/src/services/feature-flags/__mocks__/setup.ts

@@ -0,0 +1,4 @@
+import { LocalFeatureFlagManager } from "../LocalFeatureFlagManager";
+import type { FlagManager } from "../setup";
+
+export const manager: FlagManager = new LocalFeatureFlagManager();

app/src/services/feature-flags/index.ts

@@ -0,0 +1,5 @@
+import { manager } from "./setup";
+
+export function isFeatureEnabled(feature: string, userId: string) {
+  return manager.isFeatureEnabled(feature, userId);
+}

app/src/services/feature-flags/setup.ts

@@ -0,0 +1,10 @@
+import { FeatureFlagManager } from "./FeatureFlagManager";
+import { LocalFeatureFlagManager } from "./LocalFeatureFlagManager";
+
+export interface FlagManager {
+  isFeatureEnabled(feature: string, userId: string): Promise<boolean>;
+}
+
+export const manager: FlagManager = process.env.FEATURE_FLAG_PROJECT
+  ? new FeatureFlagManager()
+  : new LocalFeatureFlagManager();

app/tests/pages/index.test.tsx

@@ -2,11 +2,13 @@ import { axe } from "jest-axe";
 import Index from "src/pages/index";
 import { render, screen } from "tests/react-utils";
 
+jest.mock("src/services/feature-flags/setup");
+
 describe("Index", () => {
   // Demonstration of rendering translated text, and asserting the presence of a dynamic value.
   // You can delete this test for your own project.
   it("renders link to Next.js docs", () => {
-    render(<Index />);
+    render(<Index isFooEnabled={true} />);
 
     const link = screen.getByRole("link", { name: /next\.js/i });
 
@@ -15,7 +17,7 @@ describe("Index", () => {
   });
 
   it("passes accessibility scan", async () => {
-    const { container } = render(<Index />);
+    const { container } = render(<Index isFooEnabled={true} />);
     const results = await axe(container);
 
     expect(results).toHaveNoViolations();

docs/feature-flagging.md

@@ -0,0 +1,22 @@
+# Feature flagging
+
+- [AWS Evidently](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Evidently.html) is used for feature flagging
+- For more information about the decision-making behind using Evidently, [this infra ADR is available](https://github.com/navapbc/template-infra/blob/main/docs/decisions/infra/0010-feature-flags-system-design.md)
+- Additional documentation of the feature flagging solution is available in [infra docs](https://github.com/navapbc/template-infra/blob/main/docs/feature-flags.md)
+
+## How it works
+
+1. `services/feature-flags/FeatureFlagManager` provides a service layer to interact with AWS Evidently endpoints. For example, class method `isFeatureEnabled` calls out to Evidently to retrieve a feature flag value we can then return to the client
+1. Pages can call `isFeatureEnabled` from next.js server side code and return the feature flag value to components as props.
+
+## Local development
+
+Out-of-the-box, local calls where `FEATURE_FLAG_PROJECT` environment variable is unset will fall back to use `LocalFeatureFlagManager` which defaults flag values to false. If you want to test Evidently locally, use your AWS IAM credentials. Once you set AWS environment variables locally for the environment you wish to connect to, calls to Evidently will succeed
+
+## Creating a new feature flag
+
+To create a new feature flag, update `/infra/[app_name]/app-config/main.tf`. More information available in infra repository [docs](https://github.com/navapbc/template-infra/blob/main/docs/feature-flags.md).
+
+## Toggling feature flags
+
+Toggle feature flags via the AWS Console GUI. More information [here](https://github.com/navapbc/template-infra/blob/main/docs/feature-flags.md#managing-feature-releases-and-partial-rollouts-via-aws-console).