@eightyfourthousand/lib-instr 2026.3.0

package/.babelrc

@@ -0,0 +1,12 @@
+{
+  "presets": [
+    [
+      "@nx/react/babel",
+      {
+        "runtime": "automatic",
+        "useBuiltIns": "usage"
+      }
+    ]
+  ],
+  "plugins": []
+}

package/.eslintrc.json

@@ -0,0 +1,18 @@
+{
+  "extends": ["plugin:@nx/react", "../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*", "storybook-static"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    }
+  ]
+}

package/README.md

@@ -0,0 +1,7 @@
+# lib-instr
+
+This library was generated with [Nx](https://nx.dev).
+
+## Running unit tests
+
+Run `nx test lib-instr` to execute the unit tests via [Jest](https://jestjs.io).

package/jest.config.ts

@@ -0,0 +1,10 @@
+module.exports = {
+  displayName: 'lib-instr',
+  preset: '../../jest.preset.js',
+  transform: {
+    '^(?!.*\\.(js|jsx|ts|tsx|css|json)$)': '@nx/react/plugins/jest',
+    '^.+\\.[tj]sx?$': ['babel-jest', { presets: ['@nx/react/babel'] }],
+  },
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx'],
+  coverageDirectory: '../../coverage/libs/lib-utils',
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@eightyfourthousand/lib-instr",
+  "version": "2026.3.0",
+  "description": "Feature flag and instrumentation helpers for 84000 applications.",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/84000/84000-apps.git",
+    "directory": "libs/lib-instr"
+  },
+  "homepage": "https://github.com/84000/84000-apps",
+  "bugs": {
+    "url": "https://github.com/84000/84000-apps/issues"
+  },
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "sideEffects": false,
+  "keywords": [],
+  "author": ""
+}

package/postcss.config.mjs

@@ -0,0 +1,9 @@
+// postcss.config.mjs
+/** @type {import('postcss-load-config').Config} */
+const config = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+
+export default config;

package/project.json

@@ -0,0 +1,24 @@
+{
+  "name": "lib-instr",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/lib-instr/src",
+  "projectType": "library",
+  "tags": ["type:utility", "scope:shared"],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/lib-instr",
+        "main": "libs/lib-instr/src/index.ts",
+        "tsConfig": "libs/lib-instr/tsconfig.lib.json",
+        "rootDir": "libs/lib-instr/src",
+        "generateExportsField": true,
+        "additionalEntryPoints": [
+          "libs/lib-instr/src/ssr.ts",
+          "libs/lib-instr/src/static.ts"
+        ]
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './lib/browser-client';
+export * from './lib/feature-flags';
+export * from './lib/instr-provider';
+export * from './lib/use-instr';

package/src/lib/browser-client.ts

@@ -0,0 +1,22 @@
+import posthog from 'posthog-js';
+
+export const initializeInstrumentation = () => {
+  const POSTHOG_KEY = process.env.NEXT_PUBLIC_POSTHOG_KEY;
+  const POSTHOG_HOST = process.env.NEXT_PUBLIC_POSTHOG_HOST;
+
+  if (!POSTHOG_KEY) {
+    console.warn('Missing NEXT_PUBLIC_POSTHOG_KEY environment variable');
+  }
+
+  if (!POSTHOG_HOST) {
+    console.warn('Missing NEXT_PUBLIC_POSTHOG_HOST environment variable');
+  }
+
+  if (POSTHOG_KEY && POSTHOG_HOST) {
+    posthog.init(POSTHOG_KEY, {
+      api_host: POSTHOG_HOST,
+      defaults: '2025-05-24',
+      person_profiles: 'identified_only',
+    });
+  }
+};

package/src/lib/feature-flags.tsx

@@ -0,0 +1,77 @@
+import {
+  useFeatureFlagEnabled as phUseFeatureFlagEnabled,
+  useFeatureFlagPayload as phUseFeatureFlagPayload,
+  useFeatureFlagVariantKey as phUseFeatureFlagVariantKey,
+  PostHogFeatureProps,
+} from '@posthog/react';
+import { JsonType } from 'posthog-js';
+
+export type FeatureFlag =
+  | 'authority-pages'
+  | 'translation-hover-cards'
+  | 'studio-header-config'
+  | 'show-restriction-warning';
+
+export type FeatureFlagPayload = {
+  apps?: string[];
+  [key: string]: JsonType;
+};
+
+/**
+ * Checks if a feature flag is enabled for the current application.
+ * If the feature flag has an "apps" payload, it checks if the current
+ * application is included in that list.
+ *
+ * @param flagKey - The key of the feature flag to check.
+ * @returns True if the feature flag is enabled for the current application, false otherwise.
+ */
+export const useFeatureFlagEnabled = (flagKey: FeatureFlag): boolean => {
+  if (!phUseFeatureFlagEnabled(flagKey)) {
+    return false;
+  }
+
+  const APPLICATION_NAME = process.env.NEXT_PUBLIC_APPLICATION_NAME || '';
+  const { apps } = phUseFeatureFlagPayload(flagKey) as FeatureFlagPayload;
+
+  if (!apps?.length) {
+    return true;
+  }
+
+  return apps.includes(APPLICATION_NAME);
+};
+
+export const useFeatureFlagPayload = (
+  flagKey: FeatureFlag,
+): FeatureFlagPayload => {
+  return phUseFeatureFlagPayload(flagKey) as FeatureFlagPayload;
+};
+
+export const useFeatureFlagVariantKey = (
+  flagKey: FeatureFlag,
+): string | boolean | undefined => {
+  return phUseFeatureFlagVariantKey(flagKey);
+};
+
+export type GatedFeatureProps = PostHogFeatureProps & {
+  flag: FeatureFlag;
+};
+
+export const GatedFeature = ({ children, flag }: GatedFeatureProps) => {
+  const enabled = useFeatureFlagEnabled(flag);
+  return enabled ? children : null;
+};
+
+/**
+ * Returns the studio header config payload from PostHog.
+ * Returns undefined if the flag is not enabled or has no payload.
+ */
+export const useStudioHeaderConfig = (): unknown => {
+  const enabled = phUseFeatureFlagEnabled('studio-header-config');
+  const payload = phUseFeatureFlagPayload('studio-header-config');
+
+  if (!enabled) {
+    return undefined;
+  }
+
+  return payload;
+};

package/src/lib/instr-provider.tsx

@@ -0,0 +1,7 @@
+import { ReactNode } from 'react';
+import posthog from 'posthog-js';
+import { PostHogProvider } from '@posthog/react';
+
+export const InstrProvider = ({ children }: { children: ReactNode }) => {
+  return <PostHogProvider client={posthog}>{children}</PostHogProvider>;
+};

package/src/lib/server-client.ts

@@ -0,0 +1,24 @@
+import { PostHog } from 'posthog-node';
+
+export const createInstrumentationClient = () => {
+  const POSTHOG_KEY = process.env.NEXT_PUBLIC_POSTHOG_KEY;
+  const POSTHOG_HOST = process.env.NEXT_PUBLIC_POSTHOG_HOST;
+
+  if (!POSTHOG_KEY) {
+    console.warn('Missing NEXT_PUBLIC_POSTHOG_KEY environment variable');
+  }
+
+  if (!POSTHOG_HOST) {
+    console.warn('Missing NEXT_PUBLIC_POSTHOG_HOST environment variable');
+  }
+
+  if (!POSTHOG_KEY || !POSTHOG_HOST) {
+    return;
+  }
+
+  return new PostHog(POSTHOG_KEY, {
+    host: POSTHOG_HOST,
+    flushAt: 1,
+    flushInterval: 0,
+  });
+};

package/src/lib/static-features.ts

@@ -0,0 +1,21 @@
+// NOTE: PostHog does not currently support checking feature flags or remote
+// config values during server-side rendering. Until that is supported, we will
+// use this hard coded configuration.
+
+export type StaticFeature = 'glossary-attestations';
+
+const STATIC_FEATURE_FLAGS: Record<StaticFeature, string[]> = {
+  'glossary-attestations': ['scholars-room'],
+};
+
+export const isStaticFeatureEnabled = (flagKey: StaticFeature) => {
+  const APPLICATION_NAME = process.env.NEXT_PUBLIC_APPLICATION_NAME || '';
+
+  const apps = STATIC_FEATURE_FLAGS[flagKey] || [];
+
+  if (!apps.length) {
+    return true;
+  }
+
+  return apps.includes(APPLICATION_NAME);
+};

package/src/lib/use-instr.ts

@@ -0,0 +1,3 @@
+import { usePostHog } from '@posthog/react';
+
+export const useInstr = usePostHog;

package/src/ssr.ts

@@ -0,0 +1 @@
+export * from './lib/server-client';

package/src/static.ts

@@ -0,0 +1 @@
+export * from './lib/static-features';

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "allowJs": false,
+    "esModuleInterop": false,
+    "allowSyntheticDefaultImports": true,
+    "strict": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ],
+  "extends": "../../tsconfig.base.json"
+}

package/tsconfig.lib.json

@@ -0,0 +1,28 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "declaration": true,
+    "types": [
+      "node",
+      "@nx/react/typings/cssmodule.d.ts",
+      "@nx/react/typings/image.d.ts",
+      "next",
+      "@nx/next/typings/image.d.ts"
+    ]
+  },
+  "exclude": [
+    "jest.config.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.js",
+    "src/**/*.test.js",
+    "src/**/*.spec.jsx",
+    "src/**/*.test.jsx",
+    "**/*.stories.ts",
+    "**/*.stories.js"
+  ],
+  "include": ["src/**/*.js", "src/**/*.jsx", "src/**/*.ts", "src/**/*.tsx"]
+}

package/tsconfig.spec.json

@@ -0,0 +1,22 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "module": "commonjs",
+    "moduleResolution": "node10",
+    "jsx": "react-jsx",
+    "types": ["jest", "node"]
+  },
+  "include": [
+    "jest.config.ts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.d.ts"
+  ]
+}