@ttoss/react-feature-flags 0.2.11 → 0.2.13

package/README.md

@@ -64,14 +64,25 @@ const MyComponent = () => {
 
 ### `FeatureFlag` component
 
-You can use `FeatureFlag` component to render its children only if the feature flag is enabled. It has a `fallback` (optional) prop that can be used to render something else if the feature flag is disabled.
+You can use `FeatureFlag` component to render its children only if the feature flag is enabled. It has optional props for error handling and fallback content.
+
+**Props:**
+
+- `name`: Feature flag name
+- `children`: Component to render when feature is enabled
+- `fallback`: Component to render when feature is disabled (optional)
+- `errorFallback`: Component to render when feature is enabled but an error occurs (optional)
 
 ```tsx
 import { FeatureFlag } from '@ttoss/react-feature-flags';
 
 const MyComponent = () => {
   return (
-    <FeatureFlag name="my-feature" fallback={<div>Feature is disabled</div>}>
+    <FeatureFlag
+      name="my-feature"
+      fallback={<div>Feature is disabled</div>}
+      errorFallback={<div>Something went wrong</div>}
+    >
       <div>Feature is enabled</div>
     </FeatureFlag>
   );
@@ -80,13 +91,13 @@ const MyComponent = () => {
 
 ### Update feature flags
 
-You can update feature flags by calling `updateFeatures` function that is returned from `useFeatureFlags` hook. This is useful when you want to update feature flags after providers are initialized.
+You can update feature flags by calling `updateFeatures` function that is returned from `useUpdateFeatures` hook. This is useful when you want to update feature flags after providers are initialized.
 
 ```tsx
-import { useFeatureFlags } from '@ttoss/react-feature-flags';
+import { useUpdateFeatures } from '@ttoss/react-feature-flags';
 
 const MyComponent = () => {
-  const { updateFeatures } = useFeatureFlags();
+  const { updateFeatures } = useUpdateFeatures();
   const handleClick = async () => {
     const response = await fetch('https://...');
     const { features } = await response.json();
@@ -96,6 +107,31 @@ const MyComponent = () => {
 };
 ```
 
+### Error Handling
+
+The `FeatureFlag` component includes built-in error boundary protection. When a feature is enabled but the wrapped component throws an error, it will render the `errorFallback` instead of crashing the entire application.
+
+```tsx
+import { FeatureFlag } from '@ttoss/react-feature-flags';
+
+const MyComponent = () => {
+  return (
+    <FeatureFlag
+      name="experimental-feature"
+      errorFallback={<div>This feature is temporarily unavailable</div>}
+    >
+      <ExperimentalComponent />
+    </FeatureFlag>
+  );
+};
+```
+
+This is especially useful for:
+
+- **Experimental features** that might have bugs
+- **Gradual rollouts** where you want graceful degradation
+- **Production safety** when testing new functionality
+
 ### TypeScript
 
 If you are using TypeScript, you can define your feature flags names on `feature-flags.d.ts` file.
@@ -118,3 +154,84 @@ const MyComponent = () => {
   return <div>{isFeatureEnabled ? 'Enabled' : 'Disabled'}</div>;
 };
 ```
+
+## Examples
+
+### `loadFeatures` function needs a hook
+
+If `loadFeatures` function needs to use data from a hook, you can create a custom Provider that uses the hook, passes the data to `loadFeatures` function, and then wraps the `FeatureFlagsProvider`.
+
+For example, you need `userId` from a custom hook `useMe` to load features:
+
+```tsx
+import * as React from 'react';
+import { FeatureFlagsProvider as TtossFeatureFlagsProvider } from '@ttoss/react-feature-flags';
+
+const FeatureFlagsProvider = ({ children }: { children: React.ReactNode }) => {
+  const { me } = useMe();
+
+  const loadFeatures = React.useCallback(async () => {
+    if (!me?.email) {
+      return [];
+    }
+
+    /**
+     * Specify modules that some users have access to.
+     */
+    if (me.email === 'user@example.com') {
+      return ['module1', 'module2'];
+    }
+
+    return [];
+  }, [me?.email]);
+
+  return (
+    <TtossFeatureFlagsProvider loadFeatures={loadFeatures}>
+      {children}
+    </TtossFeatureFlagsProvider>
+  );
+};
+```
+
+## Best Practices
+
+### Use Unique Entrypoints
+
+When implementing feature flags, always ensure that **all dependencies** for your new feature are contained within the feature flag boundary. This prevents failures when the feature is disabled.
+
+#### ✅ Recommended: Unique Entrypoint
+
+```tsx
+import { FeatureFlag } from '@ttoss/react-feature-flags';
+import { MyNewComponent } from './MyNewComponent';
+
+const MyComponent = () => {
+  return (
+    <FeatureFlag name="my-feature" fallback={null}>
+      <MyNewComponent />
+    </FeatureFlag>
+  );
+};
+```
+
+#### ❌ Avoid: Non-Unique Entrypoint
+
+```tsx
+import { FeatureFlag } from '@ttoss/react-feature-flags';
+import { MyNewComponent } from './MyNewComponent';
+import { useMyNewComponentHook } from './useMyNewComponentHook';
+
+const MyComponent = () => {
+  const data = useMyNewComponentHook(); // This executes even when feature is disabled
+
+  return (
+    <FeatureFlag name="my-feature" fallback={null}>
+      <MyNewComponent data={data} />
+    </FeatureFlag>
+  );
+};
+```
+
+**Why this matters**: In the non-unique entrypoint example, `useMyNewComponentHook()` executes regardless of whether the feature flag is enabled. If this hook fails or has dependencies that don't exist when the feature is disabled, it will break the entire `MyComponent`, even though the feature flag should prevent this.
+
+**Solution**: Move all feature-related logic, including hooks, API calls, and dependencies, inside the component that's wrapped by the feature flag.

package/dist/esm/index.js

@@ -1,5 +1,8 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 
+// src/FeatureFlag.tsx
+import { ErrorBoundary } from "react-error-boundary";
+
 // src/useFeatureFlag.ts
 import * as React2 from "react";
 
@@ -38,17 +41,19 @@ var useFeatureFlag = name => {
 };
 
 // src/FeatureFlag.tsx
-import { Fragment, jsx as jsx2 } from "react/jsx-runtime";
+import { jsx as jsx2 } from "react/jsx-runtime";
 var FeatureFlag = ({
   name,
   children,
-  fallback = null
+  fallback = null,
+  errorFallback = null
 }) => {
   const isEnabled = useFeatureFlag(name);
   if (!isEnabled) {
     return fallback;
   }
-  return /* @__PURE__ */jsx2(Fragment, {
+  return /* @__PURE__ */jsx2(ErrorBoundary, {
+    fallback: errorFallback,
     children
   });
 };

package/dist/index.d.ts

@@ -5,8 +5,9 @@ interface FeatureFlagProps {
     name: FeatureFlags;
     children: React.ReactNode;
     fallback?: React.ReactNode;
+    errorFallback?: React.ReactNode;
 }
-declare const FeatureFlag: ({ name, children, fallback, }: FeatureFlagProps) => string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null;
+declare const FeatureFlag: ({ name, children, fallback, errorFallback, }: FeatureFlagProps) => string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null;
 
 declare const FeatureFlagsProvider: ({ children, loadFeatures, }: {
     children: React.ReactNode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/react-feature-flags",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "React Feature Flags",
   "license": "MIT",
   "author": "ttoss",
@@ -22,16 +22,19 @@
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "react-error-boundary": "^5.0.0"
+  },
   "peerDependencies": {
     "react": ">=16.8.0"
   },
   "devDependencies": {
     "@types/react": "^19.1.8",
-    "jest": "^30.0.2",
+    "jest": "^30.0.4",
     "react": "^19.1.0",
     "tsup": "^8.5.0",
-    "@ttoss/config": "^1.35.4",
-    "@ttoss/test-utils": "^2.1.24"
+    "@ttoss/config": "^1.35.5",
+    "@ttoss/test-utils": "^2.1.25"
   },
   "keywords": [
     "feature-flags",