@salesforce/webapp-template-feature-react-authentication-experimental 1.11.2 → 1.13.0

package/dist/.a4drules/skills/install-feature/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: install-feature
+description: Install a feature into the current app. Use when the user asks to add a feature, capability, or functionality like authentication, search, charts, or navigation to their React web app.
+---
+
+# Install feature
+
+When the user asks to add a feature to their app, follow this workflow.
+
+## 1. Match the request to a feature
+
+Available features (npm packages):
+
+
+| Feature                | Package                                                                 | Description                                                            |
+| ---------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| **Authentication**     | `@salesforce/webapp-template-feature-react-authentication-experimental` | Login, register, password reset, protected routes                      |
+| **Global search**      | `@salesforce/webapp-template-feature-react-global-search-experimental`  | Search Salesforce objects with filters and pagination                  |
+| **Navigation menu**    | `@salesforce/webapp-template-feature-react-nav-menu-experimental`       | App layout with responsive navigation menu                             |
+| **Analytics charts**   | `@salesforce/webapp-template-feature-react-chart-experimental`         | Recharts line/bar charts with theming (AnalyticsChart, ChartContainer) |
+| **Shared UI (shadcn)** | `@salesforce/webapp-template-feature-react-shadcn-experimental`         | Button, Card, Input, Select, Table, Tabs, etc.                         |
+
+
+If no feature matches, tell the user and offer to build it from scratch following the project's existing patterns.
+
+## 2. Install the npm package
+
+```bash
+npm install <package-name>
+```
+
+## 3. Copy skills and rules from the package
+
+After install, check the package in `node_modules/<package-name>/` for:
+
+- `**skills/**` – If it exists, copy each skill folder into the current project's skills directory (e.g. `.cline/skills/` or `.cursor/skills/`).
+- `**rules/**` – If it exists, copy each rule file into the current project's rules directory (e.g. `.clinerules/` or `.cursor/rules/`).
+
+Not every package has skills or rules; skip this step if neither directory exists.
+
+## 4. Read the feature's exports and components
+
+Read the package's entry point (usually `index.ts` or the `main` field in its `package.json`) to understand what components and types it exports.
+
+Also read the `feature.ts` file if it exists — it lists dependencies on other features (e.g. shadcn) and any npm dependencies the feature needs (e.g. `recharts`). Install any missing dependencies.
+
+## 5. Implement the feature in the current app
+
+- **If the package exports reusable components** (e.g. `AnalyticsChart`, `ChartContainer`): import and use them directly. Follow the package's README or skill instructions for props, data shapes, and usage patterns.
+- **If the package is a reference implementation** (e.g. authentication pages, search pages): read its source code under `src/` as a reference, then create equivalent pages/components in the current app following the app's existing patterns and conventions.
+
+Place new routes inside the existing app's router (e.g. `routes.tsx`). Do not replace the app shell; add the feature as new routes or sections within it.
+
+## 6. Verify
+
+- Confirm the app builds without errors.
+- Confirm any new routes are accessible and render correctly.
+

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.13.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.12.0...v1.13.0) (2026-02-06)
+
+
+### Features
+
+* adding a sample feature package for reference ([#77](https://github.com/salesforce-experience-platform-emu/webapps/issues/77)) ([94b4d8e](https://github.com/salesforce-experience-platform-emu/webapps/commit/94b4d8e5e89c10888868b8b014c1032ff4b6177d))
+
+
+
+
+
+# [1.12.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.11.2...v1.12.0) (2026-02-06)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
 ## [1.11.2](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.11.1...v1.11.2) (2026-02-06)
 
 **Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental

package/dist/force-app/main/default/classes/WebAppLogin.cls

@@ -0,0 +1,97 @@
+/**
+ * REST endpoint for Web Applications user login.
+ *
+ * Endpoint: POST /services/apexrest/auth/login
+ *
+ * Authenticates a user and returns a redirect URL for session creation.
+ *
+ * @see https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_classes_sites.htm#apex_System_Site_login
+ */
+@RestResource(urlMapping='/auth/login')
+global with sharing class WebAppLogin {
+
+    /**
+     * Authenticates a user and returns a redirect URL.
+     * @param email User's email address (used as username).
+     * @param password User's password.
+     * @param startUrl Optional URL to redirect to after login.
+     * @return LoginResponse with redirectUrl on success, or error message on failure.
+     */
+    @HttpPost
+    global static LoginResponse doLogin(String email, String password, String startUrl) {
+        try {
+            validateInput(email, password);
+
+            String username = email.trim().toLowerCase();
+            String sanitizedStartUrl = WebAppAuthUtils.getSanitizedStartUrl(startUrl, Site.getPathPrefix());
+            PageReference loginResult = Site.login(username, password, sanitizedStartUrl);
+
+            if (loginResult != null) {
+                return new SuccessLoginResponse(loginResult.getUrl());
+            } else {
+                RestContext.response.statusCode = 401;
+                return new ErrorLoginResponse(
+                    'Your login attempt has failed. Make sure the username and password are correct.'
+                );
+            }
+        } catch (WebAppAuthUtils.AuthException ex) {
+            RestContext.response.statusCode = ex.statusCode;
+            return new ErrorLoginResponse(ex.messages);
+        } catch (Exception ex) {
+            RestContext.response.statusCode = 500;
+            return new ErrorLoginResponse('An unexpected error occurred. Please contact your administrator.');
+        }
+    }
+
+    /**
+     * Validates login input fields.
+     * @param email The email to validate.
+     * @param password The password to validate.
+     * @throws WebAppAuthUtils.AuthException if validation fails.
+     */
+    private static void validateInput(String email, String password) {
+        List<String> errors = new List<String>();
+        if (String.isBlank(email)) {
+            errors.add('Email is required.');
+        }
+        if (String.isBlank(password)) {
+            errors.add('Password is required.');
+        }
+        if (!errors.isEmpty()) {
+            throw new WebAppAuthUtils.AuthException(400, errors);
+        }
+    }
+
+    /**
+     * Base response class for login.
+     */
+    global abstract class LoginResponse {
+    }
+
+    /**
+     * Success response with redirect URL.
+     */
+    global class SuccessLoginResponse extends LoginResponse {
+        global Boolean success = true;
+        global String redirectUrl;
+
+        global SuccessLoginResponse(String redirectUrl) {
+            this.redirectUrl = redirectUrl;
+        }
+    }
+
+    /**
+     * Error response with error messages.
+     */
+    global class ErrorLoginResponse extends LoginResponse {
+        global List<String> errors;
+
+        global ErrorLoginResponse(List<String> errors) {
+            this.errors = new List<String>(errors);
+        }
+
+        global ErrorLoginResponse(String error) {
+            this.errors = new List<String>{ error };
+        }
+    }
+}

package/dist/force-app/main/default/classes/WebAppLogin.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>66.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

package/dist/force-app/main/default/classes/WebAppRegistration.cls

@@ -1,14 +1,14 @@
 /**
  * REST endpoint for Web Applications for user self-registration.
- * 
+ *
  * Endpoint: POST /services/apexrest/auth/register/
- * 
+ *
  * Creates a new external user account, validates credentials against org password policy,
  * and returns a login URL for automatic session creation.
- * 
+ *
  * Security: Uses 'without sharing' to allow guest users to check for duplicate usernames.
  */
-@RestResource(urlMapping='/auth/register/')
+@RestResource(urlMapping='/auth/register')
 global without sharing class WebAppRegistration {
 
     /**
@@ -21,7 +21,7 @@ global without sharing class WebAppRegistration {
         Savepoint sp = Database.setSavepoint();
         try {
             request.validate();
-            
+
             User u = new User(
                 Username = request.email,
                 Email = request.email,
@@ -57,13 +57,14 @@ global without sharing class WebAppRegistration {
     }
 
     /**
-     * Success response with login URL.
+     * Success response with redirect URL.
      */
     global class SuccessRegistrationResponse extends RegistrationResponse {
-        global String loginUrl;
-        
-        global SuccessRegistrationResponse(String loginUrl) {
-            this.loginUrl = loginUrl;
+        global Boolean success = true;
+        global String redirectUrl;
+
+        global SuccessRegistrationResponse(String redirectUrl) {
+            this.redirectUrl = redirectUrl;
         }
     }
 
@@ -72,7 +73,7 @@ global without sharing class WebAppRegistration {
      */
     global class ErrorRegistrationResponse extends RegistrationResponse {
         global List<String> errors;
-        
+
         global ErrorRegistrationResponse(List<String> errors) {
             this.errors = new List<String>(errors);
         }

package/dist/force-app/main/default/webapplications/feature-react-authentication/src/pages/Login.tsx

@@ -7,6 +7,7 @@ import { AuthForm } from "../components/forms/auth-form";
 import { useAppForm } from "../hooks/form";
 import { ROUTES } from "../utils/authenticationConfig";
 import { emailSchema, getStartUrl, handleApiResponse, getErrorMessage } from "../utils/helpers";
+import type { AuthResponse } from "../utils/helpers";
 
 const loginSchema = z.object({
 	email: emailSchema,
@@ -26,18 +27,22 @@ export default function Login() {
 			try {
 				// [Dev Note] Salesforce Integration:
 				// We use 'baseClient.post' to make an authenticated (or guest) call to Salesforce.
-				// "/services/apexrest/auth/login" refers to a custom Apex Class exposed as a REST resource.
+				// "/sfciapi/services/apexrest/auth/login" refers to a custom Apex Class exposed as a REST resource.
 				// You must ensure this Apex class exists in your org and handles the login logic
 				// (e.g., creating a session or returning a token).
-				const response = await baseClient.post("/services/apexrest/auth/login", {
+				const response = await baseClient.post("/sfdcapi/services/apexrest/auth/login", {
 					email: value.email.trim().toLowerCase(),
 					password: value.password,
+					startUrl: getStartUrl(searchParams),
 				});
-				await handleApiResponse(response, "Login failed");
-
-				// [Dev Note] After successful API call, redirect to the intended page.
-				// The session cookie is typically set by the server/Apex response headers.
-				navigate(getStartUrl(searchParams), { replace: true });
+				const result = await handleApiResponse<AuthResponse>(response, "Login failed");
+				if (result?.redirectUrl) {
+					// Hard navigate to the URL which establishes the server session cookie
+					window.location.replace(result.redirectUrl);
+				} else {
+					// In case redirectUrl is null, navigate to home
+					navigate("/", { replace: true });
+				}
 			} catch (err) {
 				setSubmitError(getErrorMessage(err, "Login failed"));
 			}

package/dist/force-app/main/default/webapplications/feature-react-authentication/src/pages/Register.tsx

@@ -13,10 +13,7 @@ import {
 	handleApiResponse,
 	getErrorMessage,
 } from "../utils/helpers";
-
-interface RegistrationResponse {
-	loginUrl: string | null;
-}
+import type { AuthResponse } from "../utils/helpers";
 
 const registerSchema = z
 	.object({
@@ -53,18 +50,15 @@ export default function Register() {
 				// [Dev Note] Calls the custom Apex REST endpoint for user registration.
 				// Ensure your Apex logic handles duplicate checks and user creation (e.g., Site.createExternalUser).
 				const { confirmPassword, ...request } = formFieldValues;
-				const response = await baseClient.post("/sfdcapi/services/apexrest/auth/register/", {
+				const response = await baseClient.post("/sfdcapi/services/apexrest/auth/register", {
 					request,
 				});
-				const result = await handleApiResponse<RegistrationResponse>(
-					response,
-					"Registration failed",
-				);
-				if (result?.loginUrl) {
+				const result = await handleApiResponse<AuthResponse>(response, "Registration failed");
+				if (result?.redirectUrl) {
 					// Hard navigate to the URL which logs the new user in
-					window.location.replace(result.loginUrl);
+					window.location.replace(result.redirectUrl);
 				} else {
-					// In case loginUrl is null, redirect to the login page
+					// In case redirectUrl is null, redirect to the login page
 					navigate(ROUTES.LOGIN.PATH, { replace: true });
 				}
 			} catch (err) {

package/dist/force-app/main/default/webapplications/feature-react-authentication/src/utils/helpers.ts

@@ -112,6 +112,17 @@ export async function handleApiResponse<T = unknown>(
 	return data as T;
 }
 
+/**
+ * Shared response type for authentication endpoints (login/register).
+ * Success responses contain `success: true` and `redirectUrl`.
+ * Error responses contain `errors` array.
+ */
+export interface AuthResponse {
+	success?: boolean;
+	redirectUrl?: string | null;
+	errors?: string[];
+}
+
 /**
  * UI API Record response structure.
  */

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.11.2",
+  "version": "1.13.0",
   "description": "Base SFDX project template",
   "private": true,
   "files": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-feature-react-authentication-experimental",
-  "version": "1.11.2",
+  "version": "1.13.0",
   "description": "Authentication feature for web applications",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",
@@ -19,7 +19,7 @@
     "watch": "npx tsx ../../cli/src/index.ts watch-patches packages/template/feature/feature-react-authentication packages/template/base-app/base-react-app packages/template/feature/feature-react-authentication/dist"
   },
   "devDependencies": {
-    "@salesforce/webapp-experimental": "^1.11.2",
+    "@salesforce/webapp-experimental": "^1.13.0",
     "@tanstack/react-form": "^1.27.7",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
@@ -27,5 +27,5 @@
     "react-router": "^7.10.1",
     "vite": "^7.3.1"
   },
-  "gitHead": "d2bb8a908eca2cff75f421769bf8dbb0a36f698f"
+  "gitHead": "f5823a67b25f01d2c4510377cb4d2c34e7ace922"
 }