@sfdc-webapps/feature-authentication 1.0.2

package/README.md

@@ -0,0 +1,97 @@
+# Feature: Authentication
+
+This feature provides authentication functionality for Salesforce Web Applications, including:
+
+- **AuthContext** - React context for managing authentication state
+- **PrivateRoute** - Route protection component for authenticated-only pages
+- **Authentication Pages** - Login, Register, Profile, Forgot Password, Reset Password
+
+## Features
+
+- Checks authentication status via Salesforce Chatter API (`/chatter/users/me`)
+- Protects routes with automatic redirect to login
+- Supports return URL (`retUrl`) query parameter for post-login navigation
+- Displays user profile information from Salesforce
+
+## Setup
+
+### Prerequisites
+
+1. **Salesforce CLI (`sf`)** - Must be installed and authenticated to a Salesforce org
+2. **@salesforce/webapps packages** - Required for API proxy functionality (see linking instructions below)
+
+### Linking @salesforce/webapps (Required until packages are published)
+
+Since `@salesforce/webapps` and `@salesforce/vite-plugin-webapps` are not yet published to npm, you need to link them locally:
+
+```bash
+# Step 1: In the webapps repo - register packages with yarn's link registry
+cd /path/to/webapps/packages/webapps && yarn link
+cd /path/to/webapps/packages/vite-plugin-webapps && yarn link
+
+# Step 2: In this repo - link the packages
+cd /path/to/webapps-templates/packages/feature-authentication
+yarn link @salesforce/webapps
+yarn link @salesforce/vite-plugin-webapps
+```
+
+### Building and Running
+
+```bash
+# Build the feature (applies patches from template to dist)
+yarn build
+
+# Start the development server
+yarn dev
+```
+
+The `yarn build` command will:
+1. Apply feature patches to create the dist directory
+2. Remove the yarn.lock (to avoid resolution conflicts)
+3. Re-link the @salesforce/webapps packages
+
+## Usage
+
+### Protecting Routes
+
+Wrap routes that require authentication with `PrivateRoute`:
+
+```tsx
+import PrivateRoute from "./components/PrivateRoute";
+
+// In routes.tsx
+{
+  element: <PrivateRoute />,
+  children: [
+    {
+      path: 'profile',
+      element: <Profile />,
+    }
+  ]
+}
+```
+
+### Using Auth Context
+
+Access authentication state in any component:
+
+```tsx
+import { useAuth } from '../context/AuthContext';
+
+function MyComponent() {
+  const { user, isAuthenticated, loading, error } = useAuth();
+
+  if (loading) return <div>Loading...</div>;
+  if (!isAuthenticated) return <div>Please log in</div>;
+
+  return <div>Welcome, {user?.displayName}</div>;
+}
+```
+
+## Notes
+
+- The feature overrides `app.tsx` to wrap the app with `AuthProvider`
+- The feature inherits `appLayout.tsx` from the base app (no override)
+- Routes are merged with the base app's routes (Home, About are preserved)
+- The `webapp.json` manifest is required for the Salesforce proxy to function > ***⚠️ TODO: this should be removed once they are decoupled (webapp.json manifest file should not be required)***
+

package/feature.ts

@@ -0,0 +1,14 @@
+import type { Feature } from '../cli/src/types.js';
+
+const feature: Feature = {
+    packageJson: {
+        dependencies: {
+            '@salesforce/webapps': '*',
+        },
+        devDependencies: {
+            '@salesforce/vite-plugin-webapps': '*',
+        },
+    },
+};
+
+export default feature;

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@sfdc-webapps/feature-authentication",
+  "version": "1.0.2",
+  "description": "Authentication feature for web applications",
+  "license": "ISC",
+  "author": "",
+  "type": "module",
+  "main": "index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "cd dist/digitalExperiences/webApplications/feature-authentication && yarn && yarn dev",
+    "build": "npx tsx ../cli/src/index.ts apply-patches packages/feature-authentication packages/base-react-app packages/feature-authentication/dist --clean --skip-dependency-changes && yarn postbuild",
+    "postbuild": "cd dist/digitalExperiences/webApplications/feature-authentication && yarn link @salesforce/webapps && yarn link @salesforce/vite-plugin-webapps",
+    "watch": "npx tsx ../cli/src/index.ts watch-patches packages/feature-authentication packages/base-react-app packages/feature-authentication/dist --clean"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "react-dom": "^19.2.1",
+    "react-router": "^7.10.1"
+  }
+}

package/template/webApp/src/__inherit__appLayout.tsx

@@ -0,0 +1,9 @@
+import { Outlet } from "react-router";
+
+export default function AppLayout() {
+    return (
+        <>
+            <Outlet />
+        </>
+    );
+}

package/template/webApp/src/app.tsx

@@ -0,0 +1,17 @@
+import { createBrowserRouter, RouterProvider } from 'react-router';
+import { routes } from '@/routes';
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { AuthProvider } from './context/AuthContext';
+import './styles/global.css'
+
+const router = createBrowserRouter(routes);
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <AuthProvider>
+      <RouterProvider router={router} />
+    </AuthProvider>
+  </StrictMode>,
+)
+

package/template/webApp/src/components/AuthError.tsx

@@ -0,0 +1,20 @@
+interface AuthErrorProps {
+    error: string;
+}
+
+export default function AuthError({ error }: AuthErrorProps) {
+    return (
+        <div className="mb-6 p-4 bg-red-50 border border-red-200 rounded-md">
+            <div className="flex items-start gap-3">
+                <svg className="w-5 h-5 text-red-600 mt-0.5 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+                </svg>
+                <div>
+                    <p className="text-sm font-medium text-red-800">Authentication Error</p>
+                    <p className="text-sm text-red-700 mt-1">{error}</p>
+                </div>
+            </div>
+        </div>
+    );
+}
+

package/template/webApp/src/components/PrivateRoute.tsx

@@ -0,0 +1,19 @@
+import { Navigate, Outlet, useLocation } from 'react-router';
+import { useAuth } from '../context/AuthContext';
+
+export default function PrivateRoute() {
+    const { isAuthenticated, loading } = useAuth();
+    const location = useLocation();
+
+    if (loading) {
+        return null;
+    }
+
+    if (!isAuthenticated) {
+        // Build the return URL with the current path
+        const returnUrl = encodeURIComponent(location.pathname + location.search);
+        return <Navigate to={`/login?retUrl=${returnUrl}`} replace />;
+    }
+
+    return <Outlet />;
+}

package/template/webApp/src/context/AuthContext.tsx

@@ -0,0 +1,64 @@
+import { createContext, useContext, useState, useEffect, useCallback, type ReactNode } from 'react';
+import { getCurrentUser, type User } from '@salesforce/webapps/api';
+
+interface AuthContextType {
+    user: User | null;
+    isAuthenticated: boolean;
+    loading: boolean;
+    error: string | null;
+    checkAuth: () => Promise<void>;
+}
+
+const AuthContext = createContext<AuthContextType | undefined>(undefined);
+
+interface AuthProviderProps {
+    children: ReactNode;
+}
+
+export function AuthProvider({ children }: AuthProviderProps) {
+    const [user, setUser] = useState<User | null>(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState<string | null>(null);
+
+    const checkAuth = useCallback(async () => {
+        setLoading(true);
+        setError(null);
+
+        try {
+            const userData = await getCurrentUser();
+            setUser(userData);
+        } catch (err) {
+            const errorMessage = err instanceof Error ? err.message : 'Authentication failed';
+            setError(errorMessage);
+            setUser(null);
+        } finally {
+            setLoading(false);
+        }
+    }, []);
+
+    useEffect(() => {
+        checkAuth();
+    }, [checkAuth]);
+
+    const value: AuthContextType = {
+        user,
+        isAuthenticated: user !== null,
+        loading,
+        error,
+        checkAuth,
+    };
+
+    return (
+        <AuthContext.Provider value={value}>
+            {children}
+        </AuthContext.Provider>
+    );
+}
+
+export function useAuth(): AuthContextType {
+    const context = useContext(AuthContext);
+    if (context === undefined) {
+        throw new Error('useAuth must be used within an AuthProvider');
+    }
+    return context;
+}

package/template/webApp/src/pages/ForgotPassword.tsx

@@ -0,0 +1,39 @@
+import { Link } from "react-router";
+
+export default function ForgotPassword() {
+    return (
+        <div className="max-w-md mx-auto p-6">
+            <div className="bg-white shadow rounded-lg p-8">
+                <h1 className="text-3xl font-bold text-center mb-4">Forgot Password</h1>
+                <p className="text-gray-600 text-center mb-6">
+                    Enter your username and we'll send you a link to reset your password.
+                </p>
+                <form className="space-y-6">
+                    <div>
+                        <label htmlFor="username" className="block text-sm font-medium mb-2">
+                            Username
+                        </label>
+                        <input
+                            type="text"
+                            id="username"
+                            className="w-full px-3 py-2 border rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+                            placeholder="Enter your username"
+                        />
+                    </div>
+                    <button
+                        type="submit"
+                        className="w-full bg-blue-600 text-white py-2 rounded-md hover:bg-blue-700"
+                    >
+                        Send Reset Link
+                    </button>
+                </form>
+                <p className="mt-6 text-center text-sm text-gray-600">
+                    Remember your password?{' '}
+                    <Link to="/login" className="text-blue-600 hover:underline">
+                        Sign in
+                    </Link>
+                </p>
+            </div>
+        </div>
+    );
+}

package/template/webApp/src/pages/Login.tsx

@@ -0,0 +1,57 @@
+import { Link } from 'react-router';
+
+export default function Login() {
+    return (
+        <div className="max-w-md mx-auto p-6">
+            <div className="bg-white shadow rounded-lg p-8">
+                <h1 className="text-3xl font-bold text-center mb-6">Login</h1>
+
+                <form className="space-y-6">
+                    <div>
+                        <label htmlFor="email" className="block text-sm font-medium mb-2">
+                            Email
+                        </label>
+                        <input
+                            type="email"
+                            id="email"
+                            className="w-full px-3 py-2 border rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+                            placeholder="Enter your email"
+                        />
+                    </div>
+                    <div>
+                        <label htmlFor="password" className="block text-sm font-medium mb-2">
+                            Password
+                        </label>
+                        <input
+                            type="password"
+                            id="password"
+                            className="w-full px-3 py-2 border rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+                            placeholder="Enter your password"
+                        />
+                    </div>
+                    <div className="flex items-center justify-between">
+                        <label className="flex items-center gap-2 text-sm">
+                            <input type="checkbox" className="rounded" />
+                            Remember me
+                        </label>
+                        <Link to="/forgot-password" className="text-sm text-blue-600 hover:underline">
+                            Forgot password?
+                        </Link>
+                    </div>
+                    <button
+                        type="submit"
+                        className="w-full bg-blue-600 text-white py-2 rounded-md hover:bg-blue-700"
+                    >
+                        Sign In
+                    </button>
+                </form>
+                <p className="mt-6 text-center text-sm text-gray-600">
+                    Don't have an account?{' '}
+                    <Link to="/register" className="text-blue-600 hover:underline">
+                        Sign up
+                    </Link>
+                </p>
+            </div>
+        </div>
+    );
+}

package/template/webApp/src/pages/Profile.tsx

@@ -0,0 +1,37 @@
+import { useAuth } from "../context/AuthContext";
+
+export default function Profile() {
+    const { user } = useAuth();
+
+    if (!user) {
+        return null;
+    }
+
+    return (
+        <div className="max-w-4xl mx-auto p-6">
+            <div className="bg-white shadow rounded-lg p-8">
+                <h1 className="text-3xl font-bold mb-8">User Profile</h1>
+                
+                <div className="space-y-6">
+                    <section>
+                        <h2 className="text-xl font-semibold mb-4">Profile Information</h2>
+                        <div className="space-y-4">
+                            <div>
+                                <label className="block text-sm font-medium text-gray-500 mb-1">
+                                    User ID
+                                </label>
+                                <p className="text-gray-900 font-mono text-sm">{user.id}</p>
+                            </div>
+                            <div>
+                                <label className="block text-sm font-medium text-gray-500 mb-1">
+                                    Name
+                                </label>
+                                <p className="text-gray-900">{user.name}</p>
+                            </div>
+                        </div>
+                    </section>
+                </div>
+            </div>
+        </div>
+    );
+}

package/template/webApp/src/pages/Register.tsx

@@ -0,0 +1,69 @@
+import { Link } from "react-router";
+
+export default function Register() {
+    return (
+        <div className="max-w-md mx-auto p-6">
+            <div className="bg-white shadow rounded-lg p-8">
+                <h1 className="text-3xl font-bold text-center mb-6">Create Account</h1>
+                <form className="space-y-6">
+                    <div>
+                        <label htmlFor="name" className="block text-sm font-medium mb-2">
+                            Full Name
+                        </label>
+                        <input
+                            type="text"
+                            id="name"
+                            className="w-full px-3 py-2 border rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+                            placeholder="Enter your full name"
+                        />
+                    </div>
+                    <div>
+                        <label htmlFor="email" className="block text-sm font-medium mb-2">
+                            Email
+                        </label>
+                        <input
+                            type="email"
+                            id="email"
+                            className="w-full px-3 py-2 border rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+                            placeholder="Enter your email"
+                        />
+                    </div>
+                    <div>
+                        <label htmlFor="password" className="block text-sm font-medium mb-2">
+                            Password
+                        </label>
+                        <input
+                            type="password"
+                            id="password"
+                            className="w-full px-3 py-2 border rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+                            placeholder="Create a password"
+                        />
+                    </div>
+                    <div>
+                        <label htmlFor="confirmPassword" className="block text-sm font-medium mb-2">
+                            Confirm Password
+                        </label>
+                        <input
+                            type="password"
+                            id="confirmPassword"
+                            className="w-full px-3 py-2 border rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+                            placeholder="Confirm your password"
+                        />
+                    </div>
+                    <button
+                        type="submit"
+                        className="w-full bg-blue-600 text-white py-2 rounded-md hover:bg-blue-700"
+                    >
+                        Create Account
+                    </button>
+                </form>
+                <p className="mt-6 text-center text-sm text-gray-600">
+                    Already have an account?{' '}
+                    <Link to="/login" className="text-blue-600 hover:underline">
+                        Sign in
+                    </Link>
+                </p>
+            </div>
+        </div>
+    );
+}

package/template/webApp/src/pages/ResetPassword.tsx

@@ -0,0 +1,49 @@
+import { Link } from "react-router";
+
+export default function ResetPassword() {
+    return (
+        <div className="max-w-md mx-auto p-6">
+            <div className="bg-white shadow rounded-lg p-8">
+                <h1 className="text-3xl font-bold text-center mb-4">Reset Password</h1>
+                <p className="text-gray-600 text-center mb-6">
+                    Enter your new password below.
+                </p>
+                <form className="space-y-6">
+                    <div>
+                        <label htmlFor="password" className="block text-sm font-medium mb-2">
+                            New Password
+                        </label>
+                        <input
+                            type="password"
+                            id="password"
+                            className="w-full px-3 py-2 border rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+                            placeholder="Enter new password"
+                        />
+                    </div>
+                    <div>
+                        <label htmlFor="confirmPassword" className="block text-sm font-medium mb-2">
+                            Confirm New Password
+                        </label>
+                        <input
+                            type="password"
+                            id="confirmPassword"
+                            className="w-full px-3 py-2 border rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+                            placeholder="Confirm new password"
+                        />
+                    </div>
+                    <button
+                        type="submit"
+                        className="w-full bg-blue-600 text-white py-2 rounded-md hover:bg-blue-700"
+                    >
+                        Reset Password
+                    </button>
+                </form>
+                <p className="mt-6 text-center text-sm text-gray-600">
+                    <Link to="/login" className="text-blue-600 hover:underline">
+                        Back to Sign in
+                    </Link>
+                </p>
+            </div>
+        </div>
+    );
+}

package/template/webApp/src/routes.tsx

@@ -0,0 +1,48 @@
+import type { RouteObject } from "react-router";
+import AppLayout from "./__inherit__appLayout";
+import Login from "./pages/Login";
+import Register from "./pages/Register";
+import ForgotPassword from "./pages/ForgotPassword";
+import ResetPassword from "./pages/ResetPassword";
+import Profile from "./pages/Profile";
+import PrivateRoute from "./components/PrivateRoute";
+
+export const routes: RouteObject[] = [
+    {
+        path: '/',
+        element: <AppLayout />,
+        children: [
+            {
+                path: 'login',
+                element: <Login />,
+                handle: { showInNavigation: true, label: 'Login' }
+            },
+            {
+                path: 'register',
+                element: <Register />,
+                handle: { showInNavigation: false }
+            },
+            {
+                path: 'forgot-password',
+                element: <ForgotPassword />,
+                handle: { showInNavigation: false }
+            },
+            {
+                path: 'reset-password',
+                element: <ResetPassword />,
+                handle: { showInNavigation: false }
+            },
+            // Protected routes - requires authentication
+            {
+                element: <PrivateRoute />,
+                children: [
+                    {
+                        path: 'profile',
+                        element: <Profile />,
+                        handle: { showInNavigation: true, label: 'Profile' }
+                    }
+                ]
+            }
+        ]
+    }
+]

package/template/webApp/webapp.json

@@ -0,0 +1,12 @@
+{
+  "name": "feature-authentication",
+  "label": "Feature Authentication",
+  "description": "Authentication feature for Salesforce Web Applications",
+  "version": "1.0.0",
+  "outputDir": "dist",
+  "routing": {
+    "trailingSlash": "never",
+    "fallback": "/index.html"
+  }
+}
+

package/tsconfig.app.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["template/webApp"]
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

package/tsconfig.node.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts"]
+}