@salesforce/webapp-template-feature-react-authentication-experimental 1.21.0 → 1.22.1

package/dist/.a4drules/graphql.md

@@ -3,85 +3,378 @@
 Instructs agents to use the established GraphQL utilities for Salesforce data access.
 
 ## Targets
-- `force-app/main/default/webapplications/*/**/*.ts`
-- `force-app/main/default/webapplications/*/**/*.tsx`
+- `force-app/main/default/webApplications/static-app/**/*.ts`
+- `force-app/main/default/webApplications/static-app/**/*.tsx`
 
-## Required: Use executeGraphQL Function
+## TypeScript Types & Code Generation
 
-When fetching data via GraphQL in the web app, **always** use the `executeGraphQL` function from `force-app/main/default/webapplications/<appName>/src/api/graphql.ts`.
+### Generated Types File
+Types are auto-generated at: `force-app/main/default/webApplications/static-app/src/api/graphql-operations-types.ts`
+
+### Generation Command
+```bash
+cd force-app/main/default/webApplications/static-app && npm run graphql:codegen
+```
+
+The codegen configuration is located at `scripts/graphql/codegen.js` and generates types from:
+- Schema: `schema.graphql` (root level)
+- Documents: `force-app/main/default/webApplications/static-app/src/**/*.{graphql,ts,tsx}`
+
+### Type Naming Convention
+For a GraphQL operation named `GetHighRevenueAccounts`:
+- **Query/Mutation Response Type**: `GetHighRevenueAccountsQuery` or `GetHighRevenueAccountsMutation`
+- **Input Variables Type**: `GetHighRevenueAccountsQueryVariables` or `GetHighRevenueAccountsMutationVariables`
+
+## Core Types & Function Signatures
+
+### executeGraphQL Function
+Located in `force-app/main/default/webApplications/static-app/src/api/graphql.ts`:
 
-### Import Pattern
 ```typescript
-import { executeGraphQL } from '../api/graphql';
-// or adjust relative path as needed based on file location
+function executeGraphQL<T, InputVariables = Record<string, unknown>>(
+  query: string,
+  variables?: InputVariables
+): Promise<T>
+```
+
+- `T` - The response type (e.g., `GetHighRevenueAccountsQuery`)
+- `InputVariables` - The variables type (e.g., `GetHighRevenueAccountsQueryVariables`)
+
+### gql Template Tag
+Also exported from `graphql.ts` for inline query definitions:
+
+```typescript
+import { gql } from '../api/graphql';
+
+const MY_QUERY = gql`
+  query MyQuery {
+    uiapi {
+      ...
+    }
+  }
+`;
 ```
 
-### Usage Pattern
+The `gql` tag is a template literal that allows defining GraphQL queries inline while maintaining syntax highlighting in most editors.
+
+### GraphQLResponse Shape
+The raw response wrapper (handled internally by `executeGraphQL`):
+
 ```typescript
-interface MyQueryResponse {
+interface GraphQLResponse<T> {
+  data: T;
+  errors?: Array<{
+    message: string;
+    locations?: Array<{ line: number; column: number }>;
+    path?: string[];
+  }>;
+}
+```
+
+### NodeOfConnection Utility Type
+Extract the node type from a connection (edges/node pattern):
+
+```typescript
+import { type NodeOfConnection } from '../api/graphql';
+
+// Extract Account node type from the query response
+type AccountNode = NodeOfConnection<
+  GetHighRevenueAccountsQuery['uiapi']['query']['Account']
+>;
+```
+
+### UIAPI Response Shape
+All Salesforce GraphQL queries follow this structure:
+
+```typescript
+interface UIAPIQueryResponse {
   uiapi: {
     query: {
-      MyObject: {
-        edges: Array<{
-          node: {
+      [ObjectName]: {
+        edges?: Array<{
+          node?: {
             Id: string;
-            Name: { value: string };
-            // ... other fields
-          };
-        }>;
-      };
+            [FieldName]?: { value?: FieldType | null } | null;
+            // Reference fields include the related record
+            [ReferenceField]?: {
+              value?: string | null;  // The ID
+              [RelatedField]?: { value?: RelatedType | null } | null;
+            } | null;
+          } | null;
+        } | null> | null;
+      } | null;
     };
   };
 }
+```
 
-const MY_QUERY = `
-  query GetMyData {
-    uiapi {
-      query {
-        MyObject(first: 10) {
-          edges {
-            node {
-              Id
-              Name { value }
-            }
+## Required Workflow
+
+There are **two acceptable patterns** for defining GraphQL queries:
+
+### Pattern 1: External .graphql File (Recommended for complex queries)
+
+#### Step 1: Create .graphql File
+Store queries in `.graphql` files for codegen to process:
+
+```graphql
+# force-app/main/default/webApplications/static-app/src/api/utils/query/myQuery.graphql
+query GetMyData($myVariable: String) {
+  uiapi {
+    query {
+      MyObject(first: 10, where: { Field: { eq: $myVariable } }) {
+        edges {
+          node {
+            Id
+            Name { value }
           }
         }
       }
     }
   }
+}
+```
+
+#### Step 2: Run Code Generation
+```bash
+cd force-app/main/default/webApplications/static-app && npm run graphql:codegen
+```
+
+This generates types in `graphql-operations-types.ts`:
+- `GetMyDataQuery` - response type
+- `GetMyDataQueryVariables` - variables type
+
+#### Step 3: Import and Use
+```typescript
+import { executeGraphQL, type NodeOfConnection } from '../api/graphql';
+import MY_QUERY from './query/myQuery.graphql?raw';
+import type {
+  GetMyDataQuery,
+  GetMyDataQueryVariables,
+} from '../graphql-operations-types';
+
+// Extract node type for cleaner return types
+type MyNode = NodeOfConnection<GetMyDataQuery['uiapi']['query']['MyObject']>;
+
+export async function getMyData(
+  variables: GetMyDataQueryVariables
+): Promise<MyNode[]> {
+  const response = await executeGraphQL<GetMyDataQuery>(MY_QUERY, variables);
+  return response.uiapi?.query?.MyObject?.edges?.map(edge => edge?.node) || [];
+}
+```
+
+**Key imports for Pattern 1:**
+- `executeGraphQL` - Execute the query
+- `NodeOfConnection` - Extract node types from connection responses
+- Query from `.graphql` file with `?raw` suffix
+- Generated types from `graphql-operations-types.ts`
+
+**Pattern 1 Benefits:**
+- Full codegen support with automatic type generation
+- Syntax highlighting and validation in `.graphql` files
+- Easier to share queries across multiple files/components
+- Better for complex queries with fragments and multiple variables
+- IDE support for GraphQL (autocomplete, validation)
+- Queries can be tested independently
+- Clear separation of concerns between query definition and usage
+
+**Pattern 1 Limitations:**
+- Requires separate file management
+- Extra step to run codegen after query changes
+- More boilerplate (file import with `?raw`, separate file to maintain)
+- Slight overhead for very simple queries
+- Need to navigate between files during development
+- Doesn't support dynamic queries (e.g., the set of fields changes based on runtime conditions and cannot be predetermined)
+
+### Pattern 2: Inline Query with gql Tag (Recommended for simple queries)
+
+For simpler queries without variables or when colocation is preferred:
+
+```typescript
+import { executeGraphQL, gql } from '../api/graphql';
+import { type CurrentUserQuery } from '../graphql-operations-types';
+
+const CURRENT_USER_QUERY = gql`
+  query CurrentUser {
+    uiapi {
+      currentUser {
+        Id
+        Name {
+          value
+        }
+      }
+    }
+  }
 `;
 
-const response = await executeGraphQL<MyQueryResponse>(MY_QUERY, { /* variables */ });
+interface User {
+    id: string;
+    name: string;
+}
+
+export async function getCurrentUser(): Promise<User | null> {
+  try {
+    const response = await executeGraphQL<CurrentUserQuery>(CURRENT_USER_QUERY);
+
+    const userData = response.uiapi.currentUser;
+
+    if (!userData) {
+      throw new Error('No user data found');
+    }
+
+    return {
+      id: userData.Id,
+      name: userData.Name?.value || 'User',
+    };
+  } catch (error) {
+    console.error('Error fetching user data:', error);
+    throw error;
+  }
+}
 ```
 
-## Reference Example
+**Key imports for Pattern 2:**
+- `executeGraphQL` - Execute the query
+- `gql` - Template tag for inline query definition
+- Generated types from `graphql-operations-types.ts`
+
+**Pattern 2 Benefits:**
+- Query is colocated with usage code
+- Supports dynamic queries (e.g., the set of fields changes based on runtime conditions and cannot be predetermined)
+- No separate file to maintain
+- Still gets type-checked against generated types
+- Simpler for straightforward queries
+
+**Pattern 2 Limitations:**
+- Inline queries without `gql` template tag are not processed by codegen
+- Must manually ensure query name matches generated types
+- Less suitable for complex queries with fragments
+
+## Reference Examples
 
-See `force-app/main/default/webapplications/<appName>/src/api/utils/accounts.ts` for a complete working example that demonstrates:
-1. TypeScript interface definitions for GraphQL response shapes
-2. GraphQL query construction using UIAPI syntax
-3. Proper typing with `executeGraphQL<T>()`
-4. Data extraction from the response
+### Pattern 1 Example: accounts.ts
+See `force-app/main/default/webApplications/static-app/src/api/utils/accounts.ts` for Pattern 1:
+1. Importing query from `.graphql` file with `?raw` suffix
+2. Importing generated types from `graphql-operations-types.ts`
+3. Using `NodeOfConnection` to extract node types
+4. Proper typing with `executeGraphQL<ResponseType>(query, variables)`
+5. Safe data extraction from the nested response
 
-## Anti-Patterns (FORBIDDEN)
+### Pattern 2 Example: user.ts
+See `force-app/main/default/webApplications/static-app/src/api/utils/user.ts` for Pattern 2:
+1. Using `gql` template tag for inline query definition
+2. Importing generated types from `graphql-operations-types.ts`
+3. Simple query without variables
+4. Error handling with try/catch
+5. Direct access to `uiapi.currentUser` (non-connection response)
+
+## Conditional Field Selection with Directives
+
+For dynamic fieldsets with known fields that should be conditionally included, use GraphQL directives instead of building queries dynamically. This preserves type generation while allowing runtime control.
+
+### Directives
+- **`@include(if: $condition)`** - include field/fragment when `$condition` is `true`
+- **`@skip(if: $condition)`** - skip field/fragment when `$condition` is `true`
+
+### Example with Fragments
+```graphql
+# static-app/src/api/utils/query/getAccountDetails.graphql
+query GetAccountDetails(
+  $id: ID!
+  $includeFinancials: Boolean!
+  $includeContacts: Boolean!
+) {
+  uiapi {
+    query {
+      Account(where: { Id: { eq: $id } }) {
+        edges {
+          node {
+            Id
+            Name { value }
+            ...FinancialFields @include(if: $includeFinancials)
+            ...ContactFields @include(if: $includeContacts)
+          }
+        }
+      }
+    }
+  }
+}
+
+fragment FinancialFields on Account {
+  AnnualRevenue { value }
+  NumberOfEmployees { value }
+}
+
+fragment ContactFields on Account {
+  Phone { value }
+  Website { value }
+}
+```
+
+### Usage
+```typescript
+import { executeGraphQL } from '../api/graphql';
+import QUERY from './query/getAccountDetails.graphql?raw';
+import type {
+  GetAccountDetailsQuery,
+  GetAccountDetailsQueryVariables,
+} from '../graphql-operations-types';
+
+const data = await executeGraphQL<GetAccountDetailsQuery>(QUERY, {
+  id: accountId,
+  includeFinancials: userWantsFinancials,
+  includeContacts: userWantsContacts,
+});
+```
+
+### Benefits
+- Query stays in `.graphql` file (codegen works)
+- Generated types include all possible fields as optional
+- Runtime control over which fields are fetched
+- Better performance when fields aren't needed
+- Type safety is preserved
+
+## Anti-Patterns (Not Recommended)
 
 ### Direct API Calls
 ```typescript
-// FORBIDDEN: Direct axios/fetch calls for GraphQL
+// NOT RECOMMENDED: Direct axios/fetch calls for GraphQL
 const response = await axios.post('/graphql', { query });
 
-// REQUIRED: Use executeGraphQL
+// PREFERRED: Use executeGraphQL
 const data = await executeGraphQL<ResponseType>(query, variables);
 ```
 
 ### Missing Type Definitions
 ```typescript
-// FORBIDDEN: Untyped GraphQL calls
+// NOT RECOMMENDED: Untyped GraphQL calls
+const data = await executeGraphQL(query);
+
+// PREFERRED: Provide response type
+const data = await executeGraphQL<GetMyDataQuery>(query);
+```
+
+### Plain String Queries (Without gql Tag)
+```typescript
+// NOT RECOMMENDED: Plain string queries without gql tag
+const query = `query { ... }`;
 const data = await executeGraphQL(query);
 
-// REQUIRED: Provide response type
-const data = await executeGraphQL<MyTypedResponse>(query);
+// PREFERRED: Use gql tag for inline queries
+const QUERY = gql`query { ... }`;
+const data = await executeGraphQL<ResponseType>(QUERY);
+
+// OR: Use .graphql file for complex queries
+import QUERY from './query/myQuery.graphql?raw';
+const data = await executeGraphQL<ResponseType>(QUERY);
 ```
 
+**Why avoid plain strings:**
+- No syntax highlighting or validation
+- Harder to maintain and refactor
+- More error-prone
+
 ## Benefits of executeGraphQL
 - Centralized error handling for GraphQL errors
 - Consistent typing with `GraphQLResponse<T>` interface
@@ -90,9 +383,26 @@ const data = await executeGraphQL<MyTypedResponse>(query);
 
 ## Quality Checklist
 Before completing GraphQL data access code:
-1. Import `executeGraphQL` from the correct path
-2. Define TypeScript interfaces for the query response
-3. Use proper generic typing: `executeGraphQL<ResponseType>`
-4. Handle the returned data appropriately
-5. Follow the pattern established in `force-app/main/default/webapplications/<appName>/src/api/utils/accounts.ts`
 
+### For Pattern 1 (.graphql files):
+1. [ ] Create `.graphql` file for the query/mutation
+2. [ ] Run `npm run graphql:codegen` to generate types
+3. [ ] Import query with `?raw` suffix
+4. [ ] Import generated types from `graphql-operations-types.ts`
+5. [ ] Use `executeGraphQL<ResponseType>()` with proper generic
+6. [ ] Use `NodeOfConnection` for cleaner node types when needed
+7. [ ] Handle optional chaining for nested response data
+8. [ ] Follow the pattern in `accounts.ts`
+
+### For Pattern 2 (inline with gql):
+1. [ ] Define query using `gql` template tag
+2. [ ] Ensure query name matches generated types in `graphql-operations-types.ts`
+3. [ ] Import generated types for the query
+4. [ ] Use `executeGraphQL<ResponseType>()` with proper generic
+5. [ ] Handle errors with try/catch when appropriate
+6. [ ] Handle optional chaining for nested response data
+7. [ ] Follow the pattern in `user.ts`
+
+### General:
+- [ ] Choose Pattern 1 for complex queries with variables, fragments, or when shared
+- [ ] Choose Pattern 2 for simple, colocated queries without complex requirements

package/dist/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.22.1](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.22.0...v1.22.1) (2026-02-11)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
+# [1.22.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.21.0...v1.22.0) (2026-02-10)
+
+
+### Features
+
+* @W-20916499 use DataSDK ([#81](https://github.com/salesforce-experience-platform-emu/webapps/issues/81)) ([fbd88e5](https://github.com/salesforce-experience-platform-emu/webapps/commit/fbd88e58283925f8fe241e99c3f968ba2c614f48))
+
+
+
+
+
 # [1.21.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.20.0...v1.21.0) (2026-02-10)
 
 **Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental

package/dist/force-app/main/default/webapplications/feature-react-authentication/build/vite.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vite').UserConfigFnObject;
+export default _default;

package/dist/force-app/main/default/webapplications/feature-react-authentication/build/vite.config.js

@@ -0,0 +1,73 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+import { resolve } from 'path';
+import tailwindcss from '@tailwindcss/vite';
+import salesforce from '@salesforce/vite-plugin-webapp-experimental';
+export default defineConfig(function (_a) {
+  var mode = _a.mode;
+  return {
+    plugins: [tailwindcss(), react(), salesforce()],
+    // Build configuration for MPA
+    build: {
+      outDir: resolve(__dirname, 'dist'),
+      assetsDir: 'assets',
+      sourcemap: false,
+    },
+    // Resolve aliases (shared between build and test)
+    resolve: {
+      alias: {
+        '@': path.resolve(__dirname, './src'),
+        '@api': path.resolve(__dirname, './src/api'),
+        '@components': path.resolve(__dirname, './src/components'),
+        '@utils': path.resolve(__dirname, './src/utils'),
+        '@styles': path.resolve(__dirname, './src/styles'),
+        '@assets': path.resolve(__dirname, './src/assets'),
+      },
+    },
+    // Vitest configuration
+    test: {
+      // Override root for tests (build uses src/pages as root)
+      root: resolve(__dirname),
+      // Use jsdom environment for React component testing
+      environment: 'jsdom',
+      // Setup files to run before each test
+      setupFiles: ['./src/test/setup.ts'],
+      // Global test patterns
+      include: [
+        'src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}',
+        'src/**/__tests__/**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}',
+      ],
+      // Coverage configuration
+      coverage: {
+        provider: 'v8',
+        reporter: ['text', 'html', 'clover', 'json'],
+        exclude: [
+          'node_modules/',
+          'src/test/',
+          'src/**/*.d.ts',
+          'src/main.tsx',
+          'src/vite-env.d.ts',
+          'src/components/**/index.ts',
+          '**/*.config.ts',
+          'build/',
+          'dist/',
+          'coverage/',
+          'eslint.config.js',
+        ],
+        thresholds: {
+          global: {
+            branches: 85,
+            functions: 85,
+            lines: 85,
+            statements: 85,
+          },
+        },
+      },
+      // Test timeout
+      testTimeout: 10000,
+      // Globals for easier testing
+      globals: true,
+    },
+  };
+});

package/dist/force-app/main/default/webapplications/feature-react-authentication/e2e/app.spec.ts

@@ -0,0 +1,24 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('base-react-app', () => {
+  test('home page loads and shows welcome content', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.getByRole('heading', { name: 'Home' })).toBeVisible();
+    await expect(
+      page.getByText('Welcome to your React application.')
+    ).toBeVisible();
+  });
+
+  test('about page loads', async ({ page }) => {
+    await page.goto('/about');
+    await expect(page).toHaveURL(/\/about/);
+    await expect(page.getByRole('heading', { name: 'About' })).toBeVisible();
+    await expect(page.getByText('This is the about page.')).toBeVisible();
+  });
+
+  test('not found route shows 404', async ({ page }) => {
+    await page.goto('/non-existent-route');
+    await expect(page.getByRole('heading', { name: '404' })).toBeVisible();
+    await expect(page.getByText('Page not found')).toBeVisible();
+  });
+});