@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental 1.116.11 → 1.116.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/AGENT.md
CHANGED
|
@@ -1,87 +1,193 @@
|
|
|
1
|
-
# Agent guide:
|
|
1
|
+
# Agent guide: Salesforce web application development
|
|
2
2
|
|
|
3
|
-
This project is a **Salesforce DX (SFDX) project** containing a **React web application**. The
|
|
3
|
+
This project is a **Salesforce DX (SFDX) project** containing a **React web application**. The web app is a standalone Vite + React SPA that runs inside the Salesforce platform. Use this file when working in this project.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Resolving paths
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Read `sfdx-project.json` at the project root. Take the first `packageDirectories[].path` value and append `/main/default` to get `<sfdx-source>`. The web app directory is:
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
<sfdx-source>/webapplications/<appName>/
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Replace `<appName>` with the actual folder name found under `webapplications/`. The source path is **not** always `force-app` — always resolve it from `sfdx-project.json`.
|
|
8
14
|
|
|
9
15
|
## Project layout
|
|
10
16
|
|
|
11
|
-
|
|
12
|
-
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
+
```
|
|
18
|
+
<project-root>/
|
|
19
|
+
├── sfdx-project.json
|
|
20
|
+
├── package.json # SFDX root scripts
|
|
21
|
+
├── scripts/
|
|
22
|
+
│ ├── setup-cli.mjs # One-command setup (deploy, schema, build)
|
|
23
|
+
│ └── graphql-search.sh # Schema entity lookup
|
|
24
|
+
├── config/
|
|
25
|
+
│ └── project-scratch-def.json
|
|
26
|
+
│
|
|
27
|
+
└── <sfdx-source>/
|
|
28
|
+
├── webapplications/
|
|
29
|
+
│ └── <appName>/ # ← React web app (primary workspace)
|
|
30
|
+
│ ├── <appName>.webapplication-meta.xml
|
|
31
|
+
│ ├── webapplication.json
|
|
32
|
+
│ ├── index.html
|
|
33
|
+
│ ├── package.json
|
|
34
|
+
│ ├── vite.config.ts / tsconfig.json
|
|
35
|
+
│ ├── vitest.config.ts / playwright.config.ts
|
|
36
|
+
│ ├── codegen.yml / .graphqlrc.yml
|
|
37
|
+
│ └── src/ # All application code lives here
|
|
38
|
+
│
|
|
39
|
+
├── classes/ # Apex classes (optional)
|
|
40
|
+
├── objects/ # Custom objects and fields (optional)
|
|
41
|
+
├── permissionsets/ # Permission sets (optional)
|
|
42
|
+
├── cspTrustedSites/ # CSP trusted site definitions (optional)
|
|
43
|
+
├── layouts/ # Object layouts (optional)
|
|
44
|
+
├── triggers/ # Apex triggers (optional)
|
|
45
|
+
└── data/ # Sample data for import (optional)
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Web application source structure
|
|
17
49
|
|
|
18
|
-
|
|
50
|
+
All application code lives inside the web app's `src/` directory:
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
src/
|
|
54
|
+
├── app.tsx # Entry point — creates the browser router
|
|
55
|
+
├── appLayout.tsx # Shell layout (header, navigation, Outlet, footer)
|
|
56
|
+
├── routes.tsx # Single route registry for the entire app
|
|
57
|
+
├── navigationMenu.tsx # Navigation component
|
|
58
|
+
├── router-utils.tsx # Router helpers
|
|
59
|
+
├── lib/utils.ts # Utility functions (cn, etc.)
|
|
60
|
+
├── styles/global.css # Tailwind global styles
|
|
61
|
+
├── api/ # GraphQL operations, clients, data services
|
|
62
|
+
├── assets/ # Static SVGs, images
|
|
63
|
+
├── components/
|
|
64
|
+
│ ├── ui/ # Shared primitives (shadcn-style: button, card, input, etc.)
|
|
65
|
+
│ ├── layout/ # Layout components (header, footer, sidebar)
|
|
66
|
+
│ └── <feature>/ # Feature-specific components
|
|
67
|
+
├── features/ # Feature modules (auth, search, etc.)
|
|
68
|
+
├── hooks/ # Custom React hooks
|
|
69
|
+
├── pages/ # Page components (one per route)
|
|
70
|
+
├── public/ # Static assets served as-is
|
|
71
|
+
└── utils/ # Shared utilities
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Key files
|
|
75
|
+
|
|
76
|
+
| File | Role |
|
|
77
|
+
|------|------|
|
|
78
|
+
| `app.tsx` | Creates `BrowserRouter`; do not add UI here |
|
|
79
|
+
| `appLayout.tsx` | Source of truth for navigation, header, footer, and page shell |
|
|
80
|
+
| `routes.tsx` | Single route registry; all pages are children of the layout route |
|
|
81
|
+
| `<appName>.webapplication-meta.xml` | Salesforce deploy descriptor (`masterLabel`, `version`, `isActive`) |
|
|
82
|
+
| `webapplication.json` | Runtime config (`outputDir`, routing) |
|
|
19
83
|
|
|
20
84
|
## Two package.json contexts
|
|
21
85
|
|
|
22
|
-
### 1. Project root
|
|
86
|
+
### 1. Project root
|
|
23
87
|
|
|
24
|
-
Used for SFDX metadata
|
|
88
|
+
Used for SFDX metadata tooling. Scripts here target LWC/Aura, not the React app.
|
|
25
89
|
|
|
26
90
|
| Command | Purpose |
|
|
27
91
|
|---------|---------|
|
|
28
|
-
| `npm run lint` | ESLint for `aura/` and `lwc/` |
|
|
29
92
|
| `npm run test` | LWC Jest (passWithNoTests) |
|
|
30
|
-
| `npm run prettier` | Format
|
|
93
|
+
| `npm run prettier` | Format metadata files |
|
|
31
94
|
| `npm run prettier:verify` | Check Prettier |
|
|
32
95
|
|
|
33
|
-
**One-command setup:**
|
|
34
|
-
|
|
35
|
-
Root **does not** run the React app. The root `npm run build` is a no-op for the base SFDX project.
|
|
96
|
+
**One-command setup:** `node scripts/setup-cli.mjs --target-org <alias>` runs login, deploy, permset assignment, data import, GraphQL schema/codegen, web app build, and optionally the dev server. Use `--help` for all flags.
|
|
36
97
|
|
|
37
|
-
### 2.
|
|
98
|
+
### 2. Web app directory (primary workspace)
|
|
38
99
|
|
|
39
100
|
**Always `cd` into the web app directory for dev/build/lint/test:**
|
|
40
101
|
|
|
41
|
-
```bash
|
|
42
|
-
cd <sfdx-source>/webapplications/<appName>
|
|
43
|
-
```
|
|
44
|
-
|
|
45
102
|
| Command | Purpose |
|
|
46
103
|
|---------|---------|
|
|
47
104
|
| `npm run dev` | Start Vite dev server |
|
|
48
|
-
| `npm run build` | TypeScript
|
|
105
|
+
| `npm run build` | TypeScript check + Vite production build |
|
|
49
106
|
| `npm run lint` | ESLint for the React app |
|
|
50
|
-
| `npm run test` | Vitest |
|
|
107
|
+
| `npm run test` | Vitest unit tests |
|
|
51
108
|
| `npm run preview` | Preview production build |
|
|
52
|
-
| `npm run graphql:codegen` | Generate GraphQL types |
|
|
53
|
-
| `npm run graphql:schema` | Fetch GraphQL schema |
|
|
109
|
+
| `npm run graphql:codegen` | Generate GraphQL types from schema |
|
|
110
|
+
| `npm run graphql:schema` | Fetch GraphQL schema from org |
|
|
111
|
+
|
|
112
|
+
**Before completing any change:** run `npm run build` and `npm run lint` from the web app directory. Both must pass with zero errors.
|
|
113
|
+
|
|
114
|
+
## Development conventions
|
|
115
|
+
|
|
116
|
+
### UI
|
|
117
|
+
|
|
118
|
+
- **Component library:** shadcn/ui primitives in `src/components/ui/`. Always use these over raw HTML equivalents.
|
|
119
|
+
- **Styling:** Tailwind CSS only. No inline `style={{}}`. Use `cn()` from `@/lib/utils` for conditional classes.
|
|
120
|
+
- **Icons:** Lucide React.
|
|
121
|
+
- **Path alias:** `@/*` maps to `src/*`. Use it for all imports.
|
|
122
|
+
- **TypeScript:** No `any`. Use proper types, generics, or `unknown`.
|
|
123
|
+
- **Components:** Accept `className?: string` prop. Extract shared state to custom hooks in `src/hooks/`.
|
|
124
|
+
- **React apps must not** import Salesforce platform modules (`lightning/*`, `@wire`, LWC APIs).
|
|
125
|
+
|
|
126
|
+
### Routing
|
|
54
127
|
|
|
55
|
-
|
|
128
|
+
- React Router with `createBrowserRouter`. Route definitions live exclusively in `routes.tsx`.
|
|
129
|
+
- All page routes are children of the layout route (which renders `appLayout.tsx`).
|
|
130
|
+
- Default-export one component per page file.
|
|
131
|
+
- The catch-all `path: '*'` route must always be last.
|
|
132
|
+
- Navigation uses absolute paths (`/dashboard`). Non-router imports use dot-relative paths (`./utils`).
|
|
133
|
+
- Navigation visibility is driven by `handle.showInNavigation` on route definitions.
|
|
56
134
|
|
|
57
|
-
|
|
135
|
+
### Layout and navigation
|
|
58
136
|
|
|
59
|
-
|
|
137
|
+
- `appLayout.tsx` owns the header, navigation menu, footer, and `<Outlet />`.
|
|
138
|
+
- To modify header or footer, edit `appLayout.tsx` and create components in `src/components/layout/`.
|
|
139
|
+
- To add a page, add a route in `routes.tsx` and create the page component — do not modify `appLayout.tsx` or `app.tsx` for page additions.
|
|
60
140
|
|
|
61
|
-
|
|
62
|
-
- **`.a4drules/webapp-data.md`** — Salesforce data access (Data SDK only, supported APIs, GraphQL workflow, `scripts/graphql-search.sh` for schema lookup).
|
|
141
|
+
### Data access (Salesforce)
|
|
63
142
|
|
|
64
|
-
|
|
143
|
+
- **All data access uses the Data SDK** (`@salesforce/sdk-data`) via `createDataSDK()`.
|
|
144
|
+
- **Never** use `fetch()` or `axios` directly for Salesforce data.
|
|
145
|
+
- **GraphQL is preferred** for record operations (`sdk.graphql`). Use `sdk.fetch` only when GraphQL cannot cover the case (UI API REST, Apex REST, Connect REST, Einstein LLM).
|
|
146
|
+
- Use optional chaining: `sdk.graphql?.()`, `sdk.fetch?.()`.
|
|
147
|
+
- Apply the `@optional` directive to all record fields for field-level security resilience.
|
|
148
|
+
- Verify field and object names via `scripts/graphql-search.sh` before writing queries.
|
|
149
|
+
- Use `__SF_API_VERSION__` global for API version in REST calls.
|
|
150
|
+
- **Blocked APIs:** Enterprise REST query endpoint (`/query` with SOQL), `@AuraEnabled` Apex, Chatter API.
|
|
151
|
+
|
|
152
|
+
### CSP trusted sites
|
|
153
|
+
|
|
154
|
+
Any external domain the app calls (APIs, CDNs, fonts) must have a `.cspTrustedSite-meta.xml` file under `<sfdx-source>/cspTrustedSites/`. Unregistered domains are blocked at runtime. Each subdomain needs its own entry. URLs must be HTTPS with no trailing slash, no path, and no wildcards.
|
|
65
155
|
|
|
66
156
|
## Deploying
|
|
67
157
|
|
|
68
|
-
**Deployment order
|
|
158
|
+
**Deployment order matters.** Metadata (objects, permission sets) must be deployed before fetching the GraphQL schema. After any metadata deployment that changes objects, fields, or permissions, re-run schema fetch and codegen.
|
|
69
159
|
|
|
70
|
-
|
|
160
|
+
**Recommended sequence:**
|
|
71
161
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
162
|
+
1. Authenticate to the target org
|
|
163
|
+
2. Build the web app (`npm run build` in the web app directory)
|
|
164
|
+
3. Deploy metadata (`sf project deploy start --source-dir <packageDir> --target-org <alias>`)
|
|
165
|
+
4. Assign permission sets
|
|
166
|
+
5. Import data (only with user confirmation)
|
|
167
|
+
6. Fetch GraphQL schema + run codegen (`npm run graphql:schema && npm run graphql:codegen`)
|
|
168
|
+
7. Rebuild the web app (schema changes may affect generated types)
|
|
169
|
+
|
|
170
|
+
**Or use the one-command setup:** `node scripts/setup-cli.mjs --target-org <alias>`
|
|
75
171
|
|
|
76
|
-
|
|
172
|
+
```bash
|
|
173
|
+
# Deploy web app only
|
|
77
174
|
sf project deploy start --source-dir <sfdx-source>/webapplications --target-org <alias>
|
|
78
175
|
|
|
79
|
-
# Deploy all metadata
|
|
176
|
+
# Deploy all metadata
|
|
80
177
|
sf project deploy start --source-dir <packageDir> --target-org <alias>
|
|
81
178
|
```
|
|
82
179
|
|
|
83
|
-
##
|
|
180
|
+
## Skills
|
|
181
|
+
|
|
182
|
+
Check for available skills before implementing any of the following:
|
|
183
|
+
|
|
184
|
+
| Area | When to consult |
|
|
185
|
+
|------|----------------|
|
|
186
|
+
| UI generation | Building pages, components, modifying header/footer/layout |
|
|
187
|
+
| Salesforce data access | Reading/writing records, GraphQL queries, REST calls |
|
|
188
|
+
| Metadata and deployment | Scaffolding apps, configuring CSP, deployment sequencing |
|
|
189
|
+
| Feature installation | Before building something from scratch — check if a pre-built feature exists |
|
|
190
|
+
| File upload | Adding file upload with Salesforce ContentVersion |
|
|
191
|
+
| Agentforce conversation | Adding or modifying the Agentforce chat widget |
|
|
84
192
|
|
|
85
|
-
|
|
86
|
-
- **Entry**: Keep `App.tsx` and routes in `src/`; add features as new routes or sections, don't replace the app shell but you may modify it to match the requested design.
|
|
87
|
-
- **Data (Salesforce)**: Follow `.a4drules/webapp-data.md` for all Salesforce data access. Use the Data SDK (`createDataSDK()` + `sdk.graphql` or `sdk.fetch`) — never use `fetch` or `axios` directly. GraphQL is preferred; use `sdk.fetch` when GraphQL is not sufficient.
|
|
193
|
+
Skills are the authoritative source for detailed patterns, constraints, and code examples in each area. This file provides project-level orientation; skills provide implementation depth.
|
package/dist/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,25 @@
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
|
|
5
5
|
|
|
6
|
+
## [1.116.13](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.116.12...v1.116.13) (2026-03-27)
|
|
7
|
+
|
|
8
|
+
**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
## [1.116.12](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.116.11...v1.116.12) (2026-03-27)
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
### Bug Fixes
|
|
18
|
+
|
|
19
|
+
* updating AGENT.md to focus on web application development ([#366](https://github.com/salesforce-experience-platform-emu/webapps/issues/366)) ([59b94d7](https://github.com/salesforce-experience-platform-emu/webapps/commit/59b94d7b995042051e1622c78f8cd562b6f99244))
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
|
|
6
25
|
## [1.116.11](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.116.10...v1.116.11) (2026-03-27)
|
|
7
26
|
|
|
8
27
|
**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
|
|
@@ -15,8 +15,8 @@
|
|
|
15
15
|
"graphql:schema": "node scripts/get-graphql-schema.mjs"
|
|
16
16
|
},
|
|
17
17
|
"dependencies": {
|
|
18
|
-
"@salesforce/sdk-data": "^1.116.
|
|
19
|
-
"@salesforce/webapp-experimental": "^1.116.
|
|
18
|
+
"@salesforce/sdk-data": "^1.116.13",
|
|
19
|
+
"@salesforce/webapp-experimental": "^1.116.13",
|
|
20
20
|
"@tailwindcss/vite": "^4.1.17",
|
|
21
21
|
"class-variance-authority": "^0.7.1",
|
|
22
22
|
"clsx": "^2.1.1",
|
|
@@ -42,7 +42,7 @@
|
|
|
42
42
|
"@graphql-eslint/eslint-plugin": "^4.1.0",
|
|
43
43
|
"@graphql-tools/utils": "^11.0.0",
|
|
44
44
|
"@playwright/test": "^1.49.0",
|
|
45
|
-
"@salesforce/vite-plugin-webapp-experimental": "^1.116.
|
|
45
|
+
"@salesforce/vite-plugin-webapp-experimental": "^1.116.13",
|
|
46
46
|
"@testing-library/jest-dom": "^6.6.3",
|
|
47
47
|
"@testing-library/react": "^16.1.0",
|
|
48
48
|
"@testing-library/user-event": "^14.5.2",
|
package/dist/package-lock.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@salesforce/webapp-template-base-sfdx-project-experimental",
|
|
3
|
-
"version": "1.116.
|
|
3
|
+
"version": "1.116.13",
|
|
4
4
|
"lockfileVersion": 3,
|
|
5
5
|
"requires": true,
|
|
6
6
|
"packages": {
|
|
7
7
|
"": {
|
|
8
8
|
"name": "@salesforce/webapp-template-base-sfdx-project-experimental",
|
|
9
|
-
"version": "1.116.
|
|
9
|
+
"version": "1.116.13",
|
|
10
10
|
"license": "SEE LICENSE IN LICENSE.txt",
|
|
11
11
|
"devDependencies": {
|
|
12
12
|
"@lwc/eslint-plugin-lwc": "^3.3.0",
|
package/dist/package.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental",
|
|
3
|
-
"version": "1.116.
|
|
3
|
+
"version": "1.116.13",
|
|
4
4
|
"description": "Embedded Agentforce conversation client feature for web applications",
|
|
5
5
|
"license": "SEE LICENSE IN LICENSE.txt",
|
|
6
6
|
"author": "",
|
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
"clean": "rm -rf dist"
|
|
27
27
|
},
|
|
28
28
|
"dependencies": {
|
|
29
|
-
"@salesforce/agentforce-conversation-client": "^1.116.
|
|
29
|
+
"@salesforce/agentforce-conversation-client": "^1.116.13"
|
|
30
30
|
},
|
|
31
31
|
"devDependencies": {
|
|
32
32
|
"@types/react": "^19.2.7",
|