mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-07-30 03:09:50 +08:00
Rename webapplication skills to ui-bundle @W-21338965@ (#136)
* Rename webapplication skills to ui-bundle
Rename all 7 webapplication skill directories and their content to use
the "ui-bundle" / "UIBundle" naming convention, aligning with the
New++ (TDX) naming strategy.
Directory renames:
- deploying-webapplication → deploying-ui-bundle
- generating-webapplication-{features,metadata,ui} → generating-ui-bundle-*
- implementing-webapplication-{agentforce-conversation-client,file-upload} → implementing-ui-bundle-*
- using-webapplication-salesforce-data → using-ui-bundle-salesforce-data
Content updates across all skills:
- Frontmatter name fields
- Prose: "web application" → "UI bundle"
- Metadata refs: WebApplication → UIBundle, webapplications/ → uiBundles/
- CLI: sf webapp → sf ui-bundle
- NPM packages per rename table
- Cross-skill references and generating-experience-react-site refs
* Rename generating-ui-bundle-ui skill to building-ui-bundle-frontend
The "ui-bundle-ui" name was confusing. "building-ui-bundle-frontend"
better conveys that this skill handles the React frontend layer
within a UI bundle.
---------
Co-authored-by: gbockus-sf <76090802+gbockus-sf@users.noreply.github.com>
This commit is contained in:
k-j-kim
GitHub
parent
e125e92ae5
commit
c611126c2f
@ -1,9 +1,9 @@
|
||||
---
|
||||
name: generating-webapplication-ui
|
||||
description: "Build and modify React UI for Salesforce web applications — pages, components, layout, navigation, and headers/footers. Use whenever creating or editing TSX/JSX files or making visual/layout changes. Triggers on: add page, add component, header, footer, navigation, layout, styling, Tailwind, shadcn, React component, appLayout."
|
||||
name: building-ui-bundle-frontend
|
||||
description: "Build and modify React UI for Salesforce UI bundles — pages, components, layout, navigation, and headers/footers. Use whenever creating or editing TSX/JSX files or making visual/layout changes. Triggers on: add page, add component, header, footer, navigation, layout, styling, Tailwind, shadcn, React component, appLayout."
|
||||
---
|
||||
|
||||
# Web Application UI
|
||||
# UI Bundle UI
|
||||
|
||||
## Identify the Task
|
||||
|
||||
@ -61,7 +61,7 @@ Apps run behind dynamic base paths. Router navigation (`<Link to>`, `navigate()`
|
||||
|
||||
### Module Restrictions
|
||||
|
||||
React apps must not import Salesforce platform modules like `lightning/*` or `@wire` (LWC-only). For data access, use the `using-webapplication-salesforce-data` skill.
|
||||
React UI bundles must not import Salesforce platform modules like `lightning/*` or `@wire` (LWC-only). For data access, use the `using-ui-bundle-salesforce-data` skill.
|
||||
|
||||
---
|
||||
|
||||
@ -119,4 +119,4 @@ Ask one question at a time and stop when you have enough context.
|
||||
|
||||
## Verification
|
||||
|
||||
Before completing, run lint and build from the web application directory. Lint must result in 0 errors and build must succeed.
|
||||
Before completing, run lint and build from the UI bundle directory. Lint must result in 0 errors and build must succeed.
|
||||
@ -64,7 +64,7 @@ export default function HomePage() {
|
||||
|
||||
### Useful Patterns — Component
|
||||
|
||||
- **Programmatic navigation:** use `useNavigate` from `react-router`; call `navigate(path)` — consistent with GlobalSearchInput, SearchResultCard, MaintenanceTable, and other components in the web application.
|
||||
- **Programmatic navigation:** use `useNavigate` from `react-router`; call `navigate(path)` — consistent with GlobalSearchInput, SearchResultCard, MaintenanceTable, and other components in the UI bundle.
|
||||
- **Page container:** `max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-12`
|
||||
- **Icons:** `lucide-react`; add `aria-hidden="true"` on decorative icons
|
||||
- **Focus styles:** use `focus-visible:` variants
|
||||
@ -1,9 +1,9 @@
|
||||
---
|
||||
name: deploying-webapplication
|
||||
description: "Deploy a Salesforce web application to an org — the full deployment sequence including org authentication, pre-deploy build, metadata deployment, permission set assignment, data import, GraphQL schema fetch, and codegen. Use whenever the user wants to deploy, push to org, assign permission sets, import data, fetch GraphQL schema, run codegen, or set up an org after development. Triggers on: deploy, push to org, deploy metadata, assign permission set, import data, schema fetch, codegen, org auth, authenticate org, build and deploy, post-deploy, org setup."
|
||||
name: deploying-ui-bundle
|
||||
description: "Deploy a Salesforce UI bundle to an org — the full deployment sequence including org authentication, pre-deploy build, metadata deployment, permission set assignment, data import, GraphQL schema fetch, and codegen. Use whenever the user wants to deploy, push to org, assign permission sets, import data, fetch GraphQL schema, run codegen, or set up an org after development. Triggers on: deploy, push to org, deploy metadata, assign permission set, import data, schema fetch, codegen, org auth, authenticate org, build and deploy, post-deploy, org setup."
|
||||
---
|
||||
|
||||
# Deploying a Web Application
|
||||
# Deploying a UI Bundle
|
||||
|
||||
The order of operations is critical when deploying to a Salesforce org. This sequence reflects the canonical flow.
|
||||
|
||||
@ -11,17 +11,17 @@ The order of operations is critical when deploying to a Salesforce org. This seq
|
||||
|
||||
Check if the org is connected. If not, authenticate. All subsequent steps require an authenticated org.
|
||||
|
||||
## Step 2: Pre-deploy Web Application Build
|
||||
## Step 2: Pre-deploy UI Bundle Build
|
||||
|
||||
Install dependencies and build the web application to produce `dist/`. Required before deploying web application entities.
|
||||
Install dependencies and build the UI bundle to produce `dist/`. Required before deploying UI bundle entities.
|
||||
|
||||
Run when: deploying web applications and `dist/` is missing or source has changed.
|
||||
Run when: deploying UI bundles and `dist/` is missing or source has changed.
|
||||
|
||||
## Step 3: Deploy Metadata
|
||||
|
||||
Check for a manifest (`manifest/package.xml` or `package.xml`) first. If present, deploy using the manifest. If not, deploy all metadata from the project.
|
||||
|
||||
Deploys objects, layouts, permission sets, Apex classes, web applications, and all other metadata. Must complete before schema fetch — the schema reflects org state.
|
||||
Deploys objects, layouts, permission sets, Apex classes, UI bundles, and all other metadata. Must complete before schema fetch — the schema reflects org state.
|
||||
|
||||
## Step 4: Post-deploy Configuration
|
||||
|
||||
@ -47,19 +47,19 @@ Always ask the user before importing or cleaning data.
|
||||
|
||||
Run when: schema missing, or metadata/permissions changed since last fetch.
|
||||
|
||||
## Step 7: Final Web Application Build
|
||||
## Step 7: Final UI Bundle Build
|
||||
|
||||
Build the web application if not already done in Step 2.
|
||||
Build the UI bundle if not already done in Step 2.
|
||||
|
||||
## Summary: Interaction Order
|
||||
|
||||
1. Check/authenticate org
|
||||
2. Build web application (if deploying web applications)
|
||||
2. Build UI bundle (if deploying UI bundles)
|
||||
3. Deploy metadata
|
||||
4. Assign permissions and configure
|
||||
5. Import data (if data plan exists, with user confirmation)
|
||||
6. Fetch GraphQL schema and run codegen
|
||||
7. Build web application (if needed)
|
||||
7. Build UI bundle (if needed)
|
||||
|
||||
## Critical Rules
|
||||
|
||||
@ -74,4 +74,4 @@ After every successful metadata deploy:
|
||||
|
||||
1. Discover and assign permission sets (or ask the user)
|
||||
2. If `data/data-plan.json` exists, ask the user about data import
|
||||
3. Re-run schema fetch and codegen from the web application directory
|
||||
3. Re-run schema fetch and codegen from the UI bundle directory
|
||||
@ -1,12 +1,12 @@
|
||||
---
|
||||
name: generating-experience-react-site
|
||||
description: "Use this skill when users need to create or configure a Salesforce Digital Experience Site specifically for hosting a React web application. Trigger when users mention creating an Experience site for a React app, setting up a React site on Salesforce, configuring Network/CustomSite/DigitalExperience metadata for a web app, or deploying site infrastructure for a React application. Also trigger when users mention site URL path prefixes, app namespaces, appDevName, guest access configuration, DigitalExperienceConfig, DigitalExperienceBundle, or sfdc_cms__site content types in the context of React apps. Always use this skill for any React web application site creation or site infrastructure configuration work, even if the user just says \"create a site for my React app\" or \"set up the site for my web application.\""
|
||||
description: "Use this skill when users need to create or configure a Salesforce Digital Experience Site specifically for hosting a React UI bundle. Trigger when users mention creating an Experience site for a React app, setting up a React site on Salesforce, configuring Network/CustomSite/DigitalExperience metadata for a UI bundle, or deploying site infrastructure for a React application. Also trigger when users mention site URL path prefixes, app namespaces, appDevName, guest access configuration, DigitalExperienceConfig, DigitalExperienceBundle, or sfdc_cms__site content types in the context of React apps. Always use this skill for any React UI bundle site creation or site infrastructure configuration work, even if the user just says \"create a site for my React app\" or \"set up the site for my UI bundle.\""
|
||||
---
|
||||
|
||||
# Digital Experience Site for React Web Applications
|
||||
Create and configure Digital Experience Sites that host React web applications on Salesforce. This skill generates the minimum necessary site infrastructure — Network, CustomSite, DigitalExperienceConfig, DigitalExperienceBundle, and the `sfdc_cms__site` content type — so a React app can be served from Salesforce.
|
||||
# Digital Experience Site for React UI Bundles
|
||||
Create and configure Digital Experience Sites that host React UI bundles on Salesforce. This skill generates the minimum necessary site infrastructure — Network, CustomSite, DigitalExperienceConfig, DigitalExperienceBundle, and the `sfdc_cms__site` content type — so a React app can be served from Salesforce.
|
||||
|
||||
React sites differ from standard LWR sites: they don't need routes, views, theme layouts, or branding sets. The site acts as a thin container (`appContainer: true`) that delegates rendering to the React application referenced by `appSpace`.
|
||||
React sites differ from standard LWR sites: they don't need routes, views, theme layouts, or branding sets. The site acts as a thin container (`appContainer: true`) that delegates rendering to the React UI bundle referenced by `appSpace`.
|
||||
|
||||
## Required Properties
|
||||
Resolve all five properties before generating any metadata. Each has a fallback chain — work through each option in order until a value is found.
|
||||
@ -16,7 +16,7 @@ Resolve all five properties before generating any metadata. Each has a fallback
|
||||
| **siteName** | `UpperCamelCase` (e.g., `MyCommunity`) | Ask user or derive from context |
|
||||
| **siteUrlPathPrefix** | `All lowercase` (e.g., `mycommunity`) | User-provided, or convert siteName to all lowercase with alphanumeric characters only |
|
||||
| **appNamespace** | String | `namespace` in `sfdx-project.json` → `sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias}` → default `c` |
|
||||
| **appDevName** | String | `webApplication` metadata in the project → `sf data query -q "SELECT DeveloperName FROM WebApplication" --target-org ${usernameOrAlias}` → default to siteName |
|
||||
| **appDevName** | String | `UIBundle` metadata in the project → `sf data query -q "SELECT DeveloperName FROM UIBundle" --target-org ${usernameOrAlias}` → default to siteName |
|
||||
| **enableGuestAccess** | Boolean | Ask user whether unauthenticated guest users can access site APIs → default `false` |
|
||||
|
||||
The `appNamespace` and `appDevName` properties connect the site to the correct React application. Getting these wrong means the site deploys but shows a blank page, so take care to resolve them from real project data.
|
||||
@ -71,7 +71,7 @@ Before deploying, confirm:
|
||||
- [ ] All five required properties are resolved
|
||||
- [ ] All metadata directories and files exist per the project structure
|
||||
- [ ] All metadata fields are populated per the templates and user requests
|
||||
- [ ] `appSpace` in `content.json` matches an existing `WebApplication` metadata record
|
||||
- [ ] `appSpace` in `content.json` matches an existing `UIBundle` metadata record
|
||||
- [ ] Deployment validates successfully:
|
||||
```bash
|
||||
sf project deploy validate --metadata Network CustomSite DigitalExperienceConfig DigitalExperienceBundle DigitalExperience --target-org ${usernameOrAlias}
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
## Purpose
|
||||
These configuration files create **net-new, default** DigitalExperience content records (`sfdc_cms__site` type) for a Digital Experience React Site. They are not intended to edit or modify existing DigitalExperience content. Use these templates only when provisioning a brand-new React site.
|
||||
|
||||
The `appContainer: true` and `appSpace` fields in `content.json` are what make this a React site rather than a standard LWR site. The `appSpace` value follows the format `{namespace}__{developerName}` and must match a deployed `WebApplication` metadata record.
|
||||
The `appContainer: true` and `appSpace` fields in `content.json` are what make this a React site rather than a standard LWR site. The `appSpace` value follows the format `{namespace}__{developerName}` and must match a deployed `UIBundle` metadata record.
|
||||
|
||||
## File Location
|
||||
The DigitalExperience directory contains only `_meta.json` and `content.json`. Do not create any directories other than `sfdc_cms__site` inside the bundle.
|
||||
|
||||
@ -1,23 +1,23 @@
|
||||
---
|
||||
name: generating-webapplication-features
|
||||
description: "Search and install pre-built features into Salesforce React web applications — authentication, shadcn, search, navigation, GraphQL, Agentforce AI, and more. Use whenever searching for or installing features. Always check for an existing feature before building from scratch. Triggers on: install feature, add authentication, add shadcn, add feature, search features, list features."
|
||||
name: generating-ui-bundle-features
|
||||
description: "Search and install pre-built features into Salesforce React UI bundles — authentication, shadcn, search, navigation, GraphQL, Agentforce AI, and more. Use whenever searching for or installing features. Always check for an existing feature before building from scratch. Triggers on: install feature, add authentication, add shadcn, add feature, search features, list features."
|
||||
---
|
||||
|
||||
# Web Application Features
|
||||
# UI Bundle Features
|
||||
|
||||
## Installing Pre-built Features
|
||||
|
||||
Always check for an existing feature before building something from scratch. The features CLI installs pre-built, tested packages into Salesforce web applications — from foundational UI libraries (shadcn/ui) to full-stack capabilities (authentication, search, navigation, GraphQL, Agentforce AI).
|
||||
Always check for an existing feature before building something from scratch. The features CLI installs pre-built, tested packages into Salesforce UI bundles — from foundational UI libraries (shadcn/ui) to full-stack capabilities (authentication, search, navigation, GraphQL, Agentforce AI).
|
||||
|
||||
### Workflow
|
||||
|
||||
1. **Search project code first** — check `src/` for existing implementations before installing anything. Scope searches to `src/` to avoid matching `node_modules/` or `dist/`.
|
||||
|
||||
2. **Search available features** — use `npx @salesforce/webapps-features-experimental list` with `--search <query>` to filter by keyword. Use `--verbose` for full descriptions.
|
||||
2. **Search available features** — use `npx @salesforce/ui-bundle-features list` with `--search <query>` to filter by keyword. Use `--verbose` for full descriptions.
|
||||
|
||||
3. **Describe a feature** — use `npx @salesforce/webapps-features-experimental describe <feature>` to see components, dependencies, copy operations, and example files.
|
||||
3. **Describe a feature** — use `npx @salesforce/ui-bundle-features describe <feature>` to see components, dependencies, copy operations, and example files.
|
||||
|
||||
4. **Install** — use `npx @salesforce/webapps-features-experimental install <feature> --webapp-dir <name>`. Key options:
|
||||
4. **Install** — use `npx @salesforce/ui-bundle-features install <feature> --ui-bundle-dir <name>`. Key options:
|
||||
- `--dry-run` to preview changes
|
||||
- `--yes` for non-interactive mode (skips conflicts)
|
||||
- `--on-conflict error` to detect conflicts, then `--conflict-resolution <file>` to resolve them
|
||||
@ -1,30 +1,30 @@
|
||||
---
|
||||
name: generating-webapplication-metadata
|
||||
description: "Scaffold new Salesforce web applications and configure their metadata — sf webapp generate, WebApplication bundles (meta XML, webapplication.json with routing/headers/outputDir), and CSP Trusted Sites for external domains. Use whenever creating a new web application, setting up web application metadata structure, configuring routing or headers, setting outputDir, adding external domains that need CSP registration, or editing bundle configuration. Triggers on: create web application, create webapp, new app, sf webapp generate, metadata, webapplication.json, CSP, trusted site, bundle configuration, meta XML, routing config, external domain, headers config, outputDir."
|
||||
name: generating-ui-bundle-metadata
|
||||
description: "Scaffold new Salesforce UI bundles and configure their metadata — sf ui-bundle generate, UIBundle bundles (meta XML, ui-bundle.json with routing/headers/outputDir), and CSP Trusted Sites for external domains. Use whenever creating a new UI bundle, setting up UI bundle metadata structure, configuring routing or headers, setting outputDir, adding external domains that need CSP registration, or editing bundle configuration. Triggers on: create UI bundle, create ui-bundle, new app, sf ui-bundle generate, metadata, ui-bundle.json, CSP, trusted site, bundle configuration, meta XML, routing config, external domain, headers config, outputDir."
|
||||
---
|
||||
|
||||
# Web Application Metadata
|
||||
# UI Bundle Metadata
|
||||
|
||||
## Scaffolding a New Web Application
|
||||
## Scaffolding a New UI Bundle
|
||||
|
||||
Use `sf webapp generate` to create new apps — not create-react-app, Vite, or other generic scaffolds.
|
||||
Use `sf ui-bundle generate` to create new apps — not create-react-app, Vite, or other generic scaffolds.
|
||||
|
||||
**Web application name (`-n`):** Alphanumerical only — no spaces, hyphens, underscores, or special characters. Example: `CoffeeBoutique` (not `Coffee Boutique`).
|
||||
**UI bundle name (`-n`):** Alphanumerical only — no spaces, hyphens, underscores, or special characters. Example: `CoffeeBoutique` (not `Coffee Boutique`).
|
||||
|
||||
After generation:
|
||||
1. Replace all default boilerplate — "React App", "Vite + React", default `<title>`, placeholder text
|
||||
2. Populate the home page with real content (landing section, banners, hero, navigation)
|
||||
3. Update navigation and placeholders (see the `generating-webapplication-ui` skill)
|
||||
3. Update navigation and placeholders (see the `building-ui-bundle-frontend` skill)
|
||||
|
||||
Always install dependencies before running any scripts in the web application directory.
|
||||
Always install dependencies before running any scripts in the UI bundle directory.
|
||||
|
||||
---
|
||||
|
||||
## WebApplication Bundle
|
||||
## UIBundle Bundle
|
||||
|
||||
A WebApplication bundle lives under `webapplications/<AppName>/` and must contain:
|
||||
A UIBundle bundle lives under `uiBundles/<AppName>/` and must contain:
|
||||
|
||||
- `<AppName>.webapplication-meta.xml` — filename must exactly match the folder name
|
||||
- `<AppName>.uibundle-meta.xml` — filename must exactly match the folder name
|
||||
- A build output directory (default: `dist/`) with at least one file
|
||||
|
||||
### Meta XML
|
||||
@ -32,7 +32,7 @@ A WebApplication bundle lives under `webapplications/<AppName>/` and must contai
|
||||
Required fields: `masterLabel`, `version` (max 20 chars), `isActive` (boolean).
|
||||
Optional: `description` (max 255 chars).
|
||||
|
||||
### webapplication.json
|
||||
### ui-bundle.json
|
||||
|
||||
Optional file. Allowed top-level keys: `outputDir`, `routing`, `headers`.
|
||||
|
||||
@ -1,10 +1,10 @@
|
||||
---
|
||||
name: implementing-webapplication-agentforce-conversation-client
|
||||
name: implementing-ui-bundle-agentforce-conversation-client
|
||||
description: "Adds or modifies AgentforceConversationClient in React apps (.tsx or .jsx files). Use when user says \"add chat widget\", \"embed agentforce\", \"add agent\", \"add chatbot\", \"integrate conversational AI\", or asks to change colors, dimensions, styling, or configure agentId, width, height, inline mode, or styleTokens for travel agent, HR agent, employee agent, or any Salesforce agent chat."
|
||||
metadata:
|
||||
author: ACC Components
|
||||
version: 1.0.0
|
||||
package: "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental"
|
||||
package: "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client"
|
||||
sdk-package: "@salesforce/agentforce-conversation-client"
|
||||
last-updated: 2025-03-18
|
||||
---
|
||||
@ -58,13 +58,13 @@ Skip this step if:
|
||||
Use this import path by default in app code:
|
||||
|
||||
```tsx
|
||||
import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
|
||||
import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";
|
||||
```
|
||||
|
||||
If the package is not installed, install it:
|
||||
|
||||
```bash
|
||||
npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental
|
||||
npm install @salesforce/ui-bundle-template-feature-react-agentforce-conversation-client
|
||||
```
|
||||
|
||||
Only use a local relative import (for example, `./components/AgentforceConversationClient`) when the user explicitly asks to use a patched/local component in that app.
|
||||
@ -79,7 +79,7 @@ Add to the target React component file using the canonical package import:
|
||||
|
||||
```tsx
|
||||
import { Outlet } from "react-router";
|
||||
import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
|
||||
import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";
|
||||
|
||||
export default function AgentChatHost() {
|
||||
return (
|
||||
@ -8,7 +8,7 @@ This document lists all invalid approaches and patterns to avoid when working wi
|
||||
|
||||
- ✅ **DO edit**: Any React files that import and use `<AgentforceConversationClient />` (for example, shared shells, route components, or feature pages)
|
||||
- ❌ **DO NOT edit**: AgentforceConversationClient.tsx, AgentforceConversationClient.jsx, index.tsx, index.jsx, or any files inside:
|
||||
- `node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/src/`
|
||||
- `node_modules/@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client/src/`
|
||||
- `packages/template/feature/feature-react-agentforce-conversation-client/src/`
|
||||
- `src/components/AgentforceConversationClient.tsx` (patched templates)
|
||||
- Any path containing `/components/AgentforceConversationClient.`
|
||||
@ -127,7 +127,7 @@ import "./agent-styles.css";
|
||||
|
||||
### ❌ Wrong - Editing implementation file
|
||||
|
||||
Reading or editing: `node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/src/AgentforceConversationClient.tsx`
|
||||
Reading or editing: `node_modules/@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client/src/AgentforceConversationClient.tsx`
|
||||
|
||||
### ✅ Correct - Editing usage file
|
||||
|
||||
@ -109,7 +109,7 @@ export default function SupportPage() {
|
||||
|
||||
```tsx
|
||||
import { Outlet } from "react-router";
|
||||
import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
|
||||
import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";
|
||||
|
||||
export default function AgentChatHost() {
|
||||
return (
|
||||
@ -1,11 +1,11 @@
|
||||
---
|
||||
name: implementing-webapplication-file-upload
|
||||
description: "Add file upload functionality to React web applications with progress tracking and Salesforce ContentVersion integration. Use when the user wants to upload files, attach documents, handle file input, create file dropzones, track upload progress, or link files to Salesforce records. This feature provides programmatic APIs ONLY — no components or hooks are exported. Build your own custom UI using the upload() API. ALWAYS use this feature instead of building file upload from scratch with FormData or XHR."
|
||||
name: implementing-ui-bundle-file-upload
|
||||
description: "Add file upload functionality to React UI bundles with progress tracking and Salesforce ContentVersion integration. Use when the user wants to upload files, attach documents, handle file input, create file dropzones, track upload progress, or link files to Salesforce records. This feature provides programmatic APIs ONLY — no components or hooks are exported. Build your own custom UI using the upload() API. ALWAYS use this feature instead of building file upload from scratch with FormData or XHR."
|
||||
---
|
||||
|
||||
# File Upload API (workflow)
|
||||
|
||||
When the user wants file upload functionality in a React web application, follow this workflow. This feature provides **APIs only** — you must build the UI components yourself using the provided APIs.
|
||||
When the user wants file upload functionality in a React UI bundle, follow this workflow. This feature provides **APIs only** — you must build the UI components yourself using the provided APIs.
|
||||
|
||||
## CRITICAL: This is an API-only package
|
||||
|
||||
@ -26,12 +26,12 @@ The source code contains reference components for demonstration, but they are **
|
||||
## 1. Install the package
|
||||
|
||||
```bash
|
||||
npm install @salesforce/webapp-template-feature-react-file-upload-experimental
|
||||
npm install @salesforce/ui-bundle-template-feature-react-file-upload
|
||||
```
|
||||
|
||||
Dependencies are automatically installed:
|
||||
|
||||
- `@salesforce/webapp-experimental` (API client)
|
||||
- `@salesforce/ui-bundle` (API client)
|
||||
- `@salesforce/sdk-data` (data SDK)
|
||||
|
||||
## 2. Understand the three upload patterns
|
||||
@ -47,7 +47,7 @@ Upload files to Salesforce and get back `contentBodyId` for each file. No Conten
|
||||
- Deferred record linking scenarios
|
||||
|
||||
```tsx
|
||||
import { upload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
|
||||
import { upload } from "@salesforce/ui-bundle-template-feature-react-file-upload";
|
||||
|
||||
const results = await upload({
|
||||
files: [file1, file2],
|
||||
@ -71,7 +71,7 @@ Upload files and immediately link them to an existing Salesforce record by creat
|
||||
- Direct upload-and-attach scenarios
|
||||
|
||||
```tsx
|
||||
import { upload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
|
||||
import { upload } from "@salesforce/ui-bundle-template-feature-react-file-upload";
|
||||
|
||||
const results = await upload({
|
||||
files: [file1, file2],
|
||||
@ -99,7 +99,7 @@ Upload files without a record, then link them after the record is created.
|
||||
import {
|
||||
upload,
|
||||
createContentVersion,
|
||||
} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
|
||||
} from "@salesforce/ui-bundle-template-feature-react-file-upload";
|
||||
|
||||
// Step 1: Upload files (no recordId)
|
||||
const uploadResults = await upload({
|
||||
@ -128,7 +128,7 @@ The package provides the backend — you build the frontend. Here's a minimal ex
|
||||
import {
|
||||
upload,
|
||||
type FileUploadProgress,
|
||||
} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
|
||||
} from "@salesforce/ui-bundle-template-feature-react-file-upload";
|
||||
import { useState } from "react";
|
||||
|
||||
function CustomFileUpload({ recordId }: { recordId?: string }) {
|
||||
@ -212,7 +212,7 @@ If the user wants to upload files to their own profile or personal library:
|
||||
import {
|
||||
upload,
|
||||
getCurrentUserId,
|
||||
} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
|
||||
} from "@salesforce/ui-bundle-template-feature-react-file-upload";
|
||||
|
||||
const userId = await getCurrentUserId();
|
||||
await upload({ files, recordId: userId });
|
||||
@ -366,7 +366,7 @@ The package includes a reference implementation in `src/features/fileupload/` wi
|
||||
|
||||
**Upload fails with CORS error:**
|
||||
|
||||
- Ensure the web application is properly deployed to Salesforce or running on `localhost`
|
||||
- Ensure the UI bundle is properly deployed to Salesforce or running on `localhost`
|
||||
- Check that the org allows the origin in CORS settings
|
||||
|
||||
**No progress updates:**
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
name: using-webapplication-salesforce-data
|
||||
description: "Salesforce data access for reading, writing, and querying records via REST, GraphQL, Apex, or Platform SDK. Use when the user wants to fetch, search, filter, sort, display, create, update, delete, or attach files to Salesforce records (standard objects like Accounts, Contacts, Opportunities, Cases, Quotes, or any custom object) in a web app or UI component (React, Angular, Vue, etc.); call Chatter, Connect, or Apex REST APIs; or invoke AuraEnabled Apex methods from an external app. Does not apply to authentication/OAuth setup, schema changes (adding fields, relationships), Bulk/Tooling/Metadata API usage, declarative automation (Flows, Process Builder), general LWC/Apex coding guidance without a specific data operation, or Salesforce admin/configuration tasks."
|
||||
name: using-ui-bundle-salesforce-data
|
||||
description: "Salesforce data access for reading, writing, and querying records via REST, GraphQL, Apex, or Platform SDK. Use when the user wants to fetch, search, filter, sort, display, create, update, delete, or attach files to Salesforce records (standard objects like Accounts, Contacts, Opportunities, Cases, Quotes, or any custom object) in a UI bundle or UI component (React, Angular, Vue, etc.); call Chatter, Connect, or Apex REST APIs; or invoke AuraEnabled Apex methods from an external app. Does not apply to authentication/OAuth setup, schema changes (adding fields, relationships), Bulk/Tooling/Metadata API usage, declarative automation (Flows, Process Builder), general LWC/Apex coding guidance without a specific data operation, or Salesforce admin/configuration tasks."
|
||||
---
|
||||
|
||||
# Salesforce Data Access
|
||||
@ -48,7 +48,7 @@ const res = await sdk.fetch?.("/services/apexrest/my-resource");
|
||||
**Not supported:**
|
||||
|
||||
- **Enterprise REST query endpoint** (`/services/data/v*/query` with SOQL) — blocked at the proxy level. Use GraphQL for record reads; use Apex REST if server-side SOQL aggregates are required.
|
||||
- **Aura-enabled Apex** (`@AuraEnabled`) — an LWC/Aura pattern with no invocation path from React web applications.
|
||||
- **Aura-enabled Apex** (`@AuraEnabled`) — an LWC/Aura pattern with no invocation path from React UI bundles.
|
||||
- **Chatter API** (`/chatter/users/me`) — use `uiapi { currentUser { ... } }` in a GraphQL query instead.
|
||||
- **Any other Salesforce REST endpoint** not listed in the supported table above.
|
||||
|
||||
@ -92,7 +92,7 @@ These rules exist because Salesforce GraphQL has platform-specific behaviors tha
|
||||
The `schema.graphql` file (265K+ lines) is the source of truth. **Never open or parse it directly.**
|
||||
|
||||
1. Check if `schema.graphql` exists at the SFDX project root
|
||||
2. If missing, run from the **web application dir**: `npm run graphql:schema`
|
||||
2. If missing, run from the **UI bundle dir**: `npm run graphql:schema`
|
||||
3. Custom objects appear only after metadata is deployed
|
||||
|
||||
### Step 2: Look Up Entity Schema
|
||||
@ -233,7 +233,7 @@ const fields = response?.data?.uiapi?.objectInfos?.[0]?.fields ?? [];
|
||||
|
||||
### Step 4: Validate & Test
|
||||
|
||||
1. **Lint**: `npx eslint <file>` from web application dir
|
||||
1. **Lint**: `npx eslint <file>` from UI bundle dir
|
||||
2. **Test**: Ask user before testing. For mutations, request input values — never fabricate data.
|
||||
|
||||
**If ESLint reports a GraphQL error** (e.g. `Cannot query field`, `Unknown type`, `Unknown argument`), the field or type name is wrong. Re-run the schema search script to find the correct name — do not guess:
|
||||
@ -247,7 +247,7 @@ Then fix the query using the exact names from the script output. For detailed er
|
||||
|
||||
---
|
||||
|
||||
## Web Application Integration (React)
|
||||
## UI Bundle Integration (React)
|
||||
|
||||
Two integration patterns are available:
|
||||
|
||||
@ -284,7 +284,7 @@ if (response?.errors?.length) {
|
||||
const accounts = response?.data?.uiapi?.query?.Account?.edges?.map(e => e.node) ?? [];
|
||||
```
|
||||
|
||||
For detailed patterns (external .graphql files, codegen, error handling strategies, quality checklists), see [Webapp Integration](references/webapp-integration.md).
|
||||
For detailed patterns (external .graphql files, codegen, error handling strategies, quality checklists), see [UI Bundle Integration](references/ui-bundle-integration.md).
|
||||
|
||||
---
|
||||
|
||||
@ -335,15 +335,15 @@ const response = await sdk.graphql?.(GET_CURRENT_USER);
|
||||
<project-root>/ ← SFDX project root
|
||||
├── schema.graphql ← grep target (lives here)
|
||||
├── sfdx-project.json
|
||||
└── force-app/main/default/webapplications/<app-name>/ ← web application dir
|
||||
└── force-app/main/default/uiBundles/<app-name>/ ← UI bundle dir
|
||||
├── package.json ← npm scripts
|
||||
└── src/
|
||||
```
|
||||
|
||||
| Command | Run From | Why |
|
||||
|---------|----------|-----|
|
||||
| `npm run graphql:schema` | web application dir | Script in web application's package.json |
|
||||
| `npx eslint <file>` | web application dir | Reads eslint.config.js |
|
||||
| `npm run graphql:schema` | UI bundle dir | Script in UI bundle's package.json |
|
||||
| `npx eslint <file>` | UI bundle dir | Reads eslint.config.js |
|
||||
| `bash scripts/graphql-search.sh <Entity>` | project root | Schema lookup |
|
||||
| `sf api request rest` | project root | Needs sfdx-project.json |
|
||||
|
||||
@ -49,5 +49,5 @@ Use a maximum of **3 introspection cycles** to resolve all entities and their de
|
||||
|
||||
The schema reflects the **current org state**. Custom objects and fields appear only after metadata is deployed.
|
||||
|
||||
- **Before** running `npm run graphql:schema`: Deploy all metadata and assign permission sets. Invoke the `deploying-webapp-to-salesforce` skill for the full sequence.
|
||||
- **Before** running `npm run graphql:schema`: Deploy all metadata and assign permission sets. Invoke the `deploying-ui-bundle` skill for the full sequence.
|
||||
- **After** any metadata deployment: Re-run `npm run graphql:schema` and `npm run graphql:codegen` so types and queries stay in sync.
|
||||
@ -1,8 +1,8 @@
|
||||
# Webapp Integration
|
||||
# UI Bundle Integration
|
||||
|
||||
## When to Use
|
||||
|
||||
This guide applies when integrating GraphQL queries into a React webapp using `createDataSDK` + codegen from `@salesforce/sdk-data`.
|
||||
This guide applies when integrating GraphQL queries into a React UI bundle using `createDataSDK` + codegen from `@salesforce/sdk-data`.
|
||||
|
||||
## Core Types & Function Signatures
|
||||
|
||||
@ -133,7 +133,7 @@ For dynamic fieldsets with **known** fields, use `@include(if: $condition)` and
|
||||
After writing the query into a source file, validate it against the schema:
|
||||
|
||||
```bash
|
||||
# Run from webapp dir (force-app/main/default/webapplications/<app-name>/)
|
||||
# Run from UI bundle dir (force-app/main/default/uiBundles/<app-name>/)
|
||||
npx eslint <path-to-file-containing-query>
|
||||
```
|
||||
|
||||
@ -150,7 +150,7 @@ npx eslint <path-to-file-containing-query>
|
||||
Generate TypeScript types from `.graphql` files and inline `gql` queries:
|
||||
|
||||
```bash
|
||||
# Run from webapp dir (force-app/main/default/webapplications/<app-name>/)
|
||||
# Run from UI bundle dir (force-app/main/default/uiBundles/<app-name>/)
|
||||
npm run graphql:codegen
|
||||
```
|
||||
|
||||
@ -201,7 +201,7 @@ const QUERY = gql`query { ... }`;
|
||||
6. [ ] Use `sdk.graphql?.<ResponseType>()` with proper generic
|
||||
7. [ ] Handle `response.errors` and destructure `response.data`
|
||||
8. [ ] Use `NodeOfConnection` for cleaner node types when needed
|
||||
9. [ ] Run `npx eslint <file>` from webapp dir — fix all GraphQL errors
|
||||
9. [ ] Run `npx eslint <file>` from UI bundle dir — fix all GraphQL errors
|
||||
|
||||
### For Pattern 2 (inline with gql):
|
||||
|
||||
@ -211,7 +211,7 @@ const QUERY = gql`query { ... }`;
|
||||
4. [ ] Import generated types for the query
|
||||
5. [ ] Use `sdk.graphql?.<ResponseType>()` with proper generic
|
||||
6. [ ] Handle `response.errors` and destructure `response.data`
|
||||
7. [ ] Run `npx eslint <file>` from webapp dir — fix all GraphQL errors
|
||||
7. [ ] Run `npx eslint <file>` from UI bundle dir — fix all GraphQL errors
|
||||
|
||||
### General:
|
||||
|
||||
@ -60,8 +60,8 @@ if [ ! -f "$SCHEMA" ]; then
|
||||
echo "ERROR: schema.graphql not found at $SCHEMA"
|
||||
echo " Make sure you are running from the SFDX project root, or pass the path explicitly:"
|
||||
echo " bash $0 --schema <path/to/schema.graphql> <EntityName>"
|
||||
echo " If the file is missing entirely, generate it from the webapp dir:"
|
||||
echo " cd force-app/main/default/webapplications/<app-name> && npm run graphql:schema"
|
||||
echo " If the file is missing entirely, generate it from the UI bundle dir:"
|
||||
echo " cd force-app/main/default/uiBundles/<app-name> && npm run graphql:schema"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
@ -73,8 +73,8 @@ fi
|
||||
|
||||
if [ ! -s "$SCHEMA" ]; then
|
||||
echo "ERROR: schema.graphql is empty at $SCHEMA"
|
||||
echo " Regenerate it from the webapp dir:"
|
||||
echo " cd force-app/main/default/webapplications/<app-name> && npm run graphql:schema"
|
||||
echo " Regenerate it from the UI bundle dir:"
|
||||
echo " cd force-app/main/default/uiBundles/<app-name> && npm run graphql:schema"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
Loading…
Reference in New Issue
Block a user