Adding externalUserId to connect-react

userId should be deprecated

Author: dannyroosevelt

packages/connect-react/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 # Changelog
 
+# [1.3.0] - 2025-06-10
+
+## Added
+- Support for `externalUserId` parameter across all components as the preferred way to identify users
+- Backward compatibility with existing `userId` parameter
+- Proper user identification in SDK debugger for `configureComponent`, `reloadComponentProps`, and `getAccounts` calls
+
+## Changed
+- All internal SDK calls now use `externalUserId` parameter for consistency with backend SDK
+- Account loading now properly includes user identification from form context
+
+## Deprecated
+- `userId` parameter in favor of `externalUserId` (existing code continues to work with console warnings)
+
+## Migration
+Replace `userId` with `externalUserId` in component props:
+```typescript
+// Before
+<ComponentFormContainer userId={userId} />
+
+// After (recommended)
+<ComponentFormContainer externalUserId={userId} />
+```
+
 # [1.2.1] - 2025-06-07
 
 - Fixing the SelectApp component to properly handle controlled values when not found in search results

packages/connect-react/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipedream/connect-react",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Pipedream Connect library for React",
   "files": [
     "dist"

packages/connect-react/src/components/ComponentForm.tsx

@@ -10,7 +10,14 @@ import type {
 import { InternalComponentForm } from "./InternalComponentForm";
 
 export type ComponentFormProps<T extends ConfigurableProps, U = ConfiguredProps<T>> = {
-  userId: string;
+  /**
+   * Your end user ID, for whom you're configuring the component.
+   */
+  externalUserId?: string;
+  /**
+   * @deprecated Use `externalUserId` instead.
+   */
+  userId?: string;
   component: V1Component<T>;
   configuredProps?: U; // XXX value?
   disableQueryDisabling?: boolean;
@@ -22,7 +29,10 @@ export type ComponentFormProps<T extends ConfigurableProps, U = ConfiguredProps<
   hideOptionalProps?: boolean;
   sdkResponse?: unknown | undefined;
   enableDebugging?: boolean;
-};
+} & (
+  | { externalUserId: string; userId?: never }
+  | { userId: string; externalUserId?: never }
+);
 
 export function ComponentForm<T extends ConfigurableProps>(props: ComponentFormProps<T>) {
   return (

packages/connect-react/src/components/ControlApp.tsx

@@ -2,6 +2,7 @@ import Select, { components as ReactSelectComponents } from "react-select";
 import { useFrontendClient } from "../hooks/frontend-client-context";
 import { useAccounts } from "../hooks/use-accounts";
 import { useFormFieldContext } from "../hooks/form-field-context";
+import { useFormContext } from "../hooks/form-context";
 import { useCustomize } from "../hooks/customization-context";
 import type { BaseReactSelectProps } from "../hooks/customization-context";
 import { useMemo } from "react";
@@ -28,6 +29,7 @@ type ControlAppProps = {
 
 export function ControlApp({ app }: ControlAppProps) {
   const client = useFrontendClient();
+  const { externalUserId } = useFormContext();
   const formFieldCtx = useFormFieldContext<ConfigurablePropApp>();
   const {
     id, prop, value, onChange,
@@ -73,6 +75,7 @@ export function ControlApp({ app }: ControlAppProps) {
     refetch: refetchAccounts,
   } = useAccounts(
     {
+      externalUserId,
       app: app.name_slug,
       oauth_app_id: oauthAppId,
     },

packages/connect-react/src/components/RemoteOptionsContainer.tsx

@@ -13,7 +13,7 @@ export type RemoteOptionsContainerProps = {
 export function RemoteOptionsContainer({ queryEnabled }: RemoteOptionsContainerProps) {
   const client = useFrontendClient();
   const {
-    userId,
+    externalUserId,
     component,
     configurableProps,
     configuredProps,
@@ -60,7 +60,7 @@ export function RemoteOptionsContainer({ queryEnabled }: RemoteOptionsContainerP
     configuredPropsUpTo[prop.name] = configuredProps[prop.name];
   }
   const componentConfigureInput: ComponentConfigureOpts = {
-    userId,
+    externalUserId,
     page,
     prevContext: context,
     componentId: component.key,

packages/connect-react/src/hooks/form-context.tsx

@@ -16,6 +16,7 @@ import {
 import {
   Observation, SdkError,
 } from "../types";
+import { resolveUserId } from "../utils/resolve-user-id";
 
 export type DynamicProps<T extends ConfigurableProps> = { id: string; configurableProps: T; }; // TODO
 
@@ -39,6 +40,8 @@ export type FormContext<T extends ConfigurableProps> = {
   setConfiguredProp: (idx: number, value: unknown) => void; // XXX type safety for value (T will rarely be static right?)
   setSubmitting: (submitting: boolean) => void;
   submitting: boolean;
+  externalUserId: string;
+  /** @deprecated Use externalUserId instead */
   userId: string;
   enableDebugging?: boolean;
 };
@@ -77,8 +80,23 @@ export const FormContextProvider = <T extends ConfigurableProps>({
   const id = useId();
 
   const {
-    component, configuredProps: __configuredProps, propNames, userId, sdkResponse, enableDebugging,
+    component, configuredProps: __configuredProps, propNames, externalUserId, userId, sdkResponse, enableDebugging,
   } = formProps;
+  
+  // Resolve user ID with deprecation warning
+  const { resolvedId: resolvedExternalUserId, warningType } = useMemo(() => 
+    resolveUserId(externalUserId, userId), 
+    [externalUserId, userId]
+  );
+
+  // Show deprecation warnings in useEffect to avoid render side effects
+  useEffect(() => {
+    if (warningType === 'both') {
+      console.warn('[connect-react] Both externalUserId and userId provided. Using externalUserId. Please remove userId to avoid this warning.');
+    } else if (warningType === 'deprecated') {
+      console.warn('[connect-react] userId is deprecated. Please use externalUserId instead.');
+    }
+  }, [warningType]);
   const componentId = component.key;
 
   const [
@@ -134,7 +152,7 @@ export const FormContextProvider = <T extends ConfigurableProps>({
     setReloadPropIdx,
   ] = useState<number>();
   const componentReloadPropsInput: ReloadComponentPropsOpts = {
-    userId,
+    externalUserId: resolvedExternalUserId,
     componentId,
     configuredProps,
     dynamicPropsId: dynamicProps?.id,
@@ -349,14 +367,14 @@ export const FormContextProvider = <T extends ConfigurableProps>({
   const [
     prevUserId,
     setPrevUserId,
-  ] = useState(userId)
+  ] = useState(resolvedExternalUserId)
   useEffect(() => {
-    if (prevUserId !== userId) {
+    if (prevUserId !== resolvedExternalUserId) {
       updateConfiguredProps({});
-      setPrevUserId(userId)
+      setPrevUserId(resolvedExternalUserId)
     }
   }, [
-    userId,
+    resolvedExternalUserId,
   ]);
 
   // maybe should take prop as first arg but for text inputs didn't want to compute index each time
@@ -550,7 +568,8 @@ export const FormContextProvider = <T extends ConfigurableProps>({
     id,
     isValid: !Object.keys(errors).length, // XXX want to expose more from errors
     props: formProps,
-    userId,
+    externalUserId: resolvedExternalUserId,
+    userId: resolvedExternalUserId, // Keep for backward compatibility
     component,
     configurableProps,
     configuredProps,

packages/connect-react/src/utils/resolve-user-id.ts

@@ -0,0 +1,21 @@
+/**
+ * Resolves user ID from either externalUserId or userId parameters
+ * Prefers externalUserId and returns both the resolved value and warning info
+ */
+export const resolveUserId = (
+  externalUserId?: string, 
+  userId?: string
+): { resolvedId: string; warningType?: 'both' | 'deprecated' } => {
+  if (externalUserId) {
+    if (userId) {
+      return { resolvedId: externalUserId, warningType: 'both' };
+    }
+    return { resolvedId: externalUserId };
+  }
+  
+  if (userId) {
+    return { resolvedId: userId, warningType: 'deprecated' };
+  }
+  
+  throw new Error('Either externalUserId or userId must be provided');
+};