@salesforce/webapp-template-app-react-template-b2e-experimental 1.83.0 → 1.84.0

package/dist/AGENT.md

@@ -26,6 +26,8 @@ Used for SFDX metadata (LWC, Aura, etc.). Scripts here are for the base SFDX tem
 | `npm run prettier` | Format supported metadata files |
 | `npm run prettier:verify` | Check Prettier |
 
+**One-command setup:** From project root run `node scripts/setup-cli.mjs --target-org <alias>` to run login (if needed), deploy, optional permset/data import, GraphQL schema/codegen, web app build, and optionally the dev server. Use `node scripts/setup-cli.mjs --help` for options (e.g. `--skip-login`, `--skip-data`, `--webapp-name`).
+
 Root **does not** run the React app. The root `npm run build` is a no-op for the base SFDX project.
 
 ### 2. React web app (where you do most work)

package/dist/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.84.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.83.0...v1.84.0) (2026-03-09)
+
+
+### Features
+
+* **template:** add setup-cli and prepare-import-unique-fields scripts ([#240](https://github.com/salesforce-experience-platform-emu/webapps/issues/240)) ([5cad14c](https://github.com/salesforce-experience-platform-emu/webapps/commit/5cad14c9be8176b2faf2429fe8e8a56383aac1ae))
+
+
+
+
+
 # [1.83.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.82.0...v1.83.0) (2026-03-09)
 
 

package/dist/force-app/main/default/webapplications/appreacttemplateb2e/package.json

@@ -15,9 +15,9 @@
     "graphql:schema": "node scripts/get-graphql-schema.mjs"
   },
   "dependencies": {
-    "@salesforce/agentforce-conversation-client": "^1.83.0",
-    "@salesforce/sdk-data": "^1.83.0",
-    "@salesforce/webapp-experimental": "^1.83.0",
+    "@salesforce/agentforce-conversation-client": "^1.84.0",
+    "@salesforce/sdk-data": "^1.84.0",
+    "@salesforce/webapp-experimental": "^1.84.0",
     "@tailwindcss/vite": "^4.1.17",
     "@tanstack/react-form": "^1.28.4",
     "class-variance-authority": "^0.7.1",
@@ -41,7 +41,7 @@
     "@graphql-eslint/eslint-plugin": "^4.1.0",
     "@graphql-tools/utils": "^11.0.0",
     "@playwright/test": "^1.49.0",
-    "@salesforce/vite-plugin-webapp-experimental": "^1.83.0",
+    "@salesforce/vite-plugin-webapp-experimental": "^1.84.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",

package/dist/force-app/main/default/webapplications/appreacttemplateb2e/webapplication.json

@@ -2,6 +2,6 @@
   "outputDir": "dist",
   "routing": {
     "trailingSlash": "never",
-    "fallback": "/index.html"
+    "fallback": "index.html"
   }
 }

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.83.0",
+  "version": "1.84.0",
   "description": "Base SFDX project template",
   "private": true,
   "files": [
@@ -18,7 +18,8 @@
     "test:unit:coverage": "sfdx-lwc-jest --coverage",
     "prettier": "prettier --write \"**/*.{cls,cmp,component,css,html,js,json,md,page,trigger,xml,yaml,yml}\"",
     "prettier:verify": "prettier --check \"**/*.{cls,cmp,component,css,html,js,json,md,page,trigger,xml,yaml,yml}\"",
-    "precommit": "lint-staged"
+    "precommit": "lint-staged",
+    "setup": "node scripts/setup-cli.mjs"
   },
   "devDependencies": {
     "@lwc/eslint-plugin-lwc": "^2.0.0",

package/dist/scripts/prepare-import-unique-fields.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Updates unique fields in data JSON files so "sf data import tree" can be run
+ * repeatedly (e.g. after org already has data). Run before data import.
+ *
+ * Usage:
+ *   node scripts/prepare-import-unique-fields.js
+ *   node scripts/prepare-import-unique-fields.js --data-dir /path/to/force-app/main/default/data
+ *
+ * Expects data dir to contain (optional) JSON files:
+ *   Contact.json (Email with unique domain per run, LastName, FirstName, Phone — standard Contact)
+ *   Agent__c.json (License_Number__c — unique per record)
+ *   Property_Management_Company__c.json (Company_Code__c, max 10 chars)
+ *   Property_Owner__c.json (Email__c)
+ * Missing files are skipped. Customize this script for your app's objects/fields.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// When run from project root: scripts/prepare-import-unique-fields.js → data dir under force-app
+const DEFAULT_DATA_DIR = path.resolve(__dirname, '..', 'force-app/main/default/data');
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let dataDir = DEFAULT_DATA_DIR;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--data-dir' && args[i + 1]) {
+      dataDir = path.resolve(args[++i]);
+      break;
+    }
+  }
+  return dataDir;
+}
+
+const dataDir = parseArgs();
+const runId = Date.now();
+const runSuffix2 = String(runId % 100).padStart(2, '0'); // 00-99 for Company_Code__c (10-char limit)
+
+// Contact: Email (unique domain + local), LastName, FirstName, Phone — avoid duplicate rules
+const contactPath = path.join(dataDir, 'Contact.json');
+if (fs.existsSync(contactPath)) {
+  let contact = JSON.parse(fs.readFileSync(contactPath, 'utf8'));
+  if (contact.records) {
+    contact.records.forEach((r, i) => {
+      if (r.Email && r.Email.includes('@')) {
+        const parts = r.Email.replace(/\+[0-9]+@/, '@').split('@');
+        const local = (parts[0] || 'user') + '+' + runId;
+        const domain = 'run' + runId + '.example.com';
+        r.Email = local + '@' + domain;
+      }
+      if (r.LastName)
+        r.LastName = String(r.LastName).replace(/-[0-9]+$/, '') + '-' + runId;
+      if (r.FirstName)
+        r.FirstName = String(r.FirstName).replace(/-[0-9]+$/, '') + '-' + (i + 1);
+      if (r.Phone)
+        r.Phone = String(r.Phone).replace(/\d{2}$/, runSuffix2);
+    });
+    fs.writeFileSync(contactPath, JSON.stringify(contact, null, 2));
+    console.log('Updated Contact.json (Email, LastName, FirstName, Phone)');
+  }
+}
+
+// Agent__c: License_Number__c — unique per record (field is often unique in org)
+const agentPath = path.join(dataDir, 'Agent__c.json');
+if (fs.existsSync(agentPath)) {
+  let agent = JSON.parse(fs.readFileSync(agentPath, 'utf8'));
+  if (agent.records) {
+    agent.records.forEach((r, i) => {
+      if (r.License_Number__c) {
+        const base = r.License_Number__c.replace(/-[0-9]+(-[0-9]+)?$/, '');
+        r.License_Number__c = base + '-' + runId + '-' + (i + 1);
+      }
+    });
+    fs.writeFileSync(agentPath, JSON.stringify(agent, null, 2));
+    console.log('Updated Agent__c.json (License_Number__c)');
+  }
+}
+
+// Property_Management_Company__c: Company_Code__c — max 10 chars, use 8-char base + 2-digit suffix
+const companyPath = path.join(dataDir, 'Property_Management_Company__c.json');
+if (fs.existsSync(companyPath)) {
+  let company = JSON.parse(fs.readFileSync(companyPath, 'utf8'));
+  if (company.records) {
+    company.records.forEach((r) => {
+      if (r.Company_Code__c)
+        r.Company_Code__c = r.Company_Code__c.slice(0, 8) + runSuffix2;
+    });
+    fs.writeFileSync(companyPath, JSON.stringify(company, null, 2));
+    console.log('Updated Property_Management_Company__c.json (Company_Code__c)');
+  }
+}
+
+// Property_Owner__c: Email__c — add +runId before @
+const ownerPath = path.join(dataDir, 'Property_Owner__c.json');
+if (fs.existsSync(ownerPath)) {
+  let owner = JSON.parse(fs.readFileSync(ownerPath, 'utf8'));
+  if (owner.records) {
+    owner.records.forEach((r) => {
+      if (r.Email__c && r.Email__c.includes('@'))
+        r.Email__c = r.Email__c.replace(/\+[0-9]+@/, '@').replace('@', '+' + runId + '@');
+    });
+    fs.writeFileSync(ownerPath, JSON.stringify(owner, null, 2));
+    console.log('Updated Property_Owner__c.json (Email__c)');
+  }
+}
+
+console.log('Unique fields updated: runId=%s companySuffix=%s', runId, runSuffix2);

package/dist/scripts/setup-cli.mjs

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+/**
+ * One-command setup: login, deploy, optional permset/data, GraphQL schema/codegen, web app build.
+ * Use this script to make setup easier for each app generated from this template.
+ *
+ * Usage:
+ *   node scripts/setup-cli.mjs --target-org <alias>   # run all steps
+ *   node scripts/setup-cli.mjs --target-org afv5 --skip-login
+ *   node scripts/setup-cli.mjs --target-org afv5 --skip-data --skip-webapp-build
+ *   node scripts/setup-cli.mjs --target-org myorg --webapp-name my-app
+ *
+ * Steps (in order):
+ *   1. login     — sf org login web only if org not already connected (skip with --skip-login)
+ *   2. deploy    — sf project deploy start --target-org <alias>
+ *   3. permset   — sf org assign permset (skip with --skip-permset; name via --permset-name)
+ *   4. data      — prepare unique fields + sf data import tree (skipped if no data dir/plan)
+ *   5. graphql   — (in webapp) npm run graphql:schema then npm run graphql:codegen
+ *   6. webapp    — (in webapp) npm install && npm run build
+ *   7. dev       — (in webapp) npm run dev — launch dev server (skip with --skip-dev)
+ */
+
+import { spawnSync } from 'node:child_process';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readdirSync, existsSync } from 'node:fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+const WEBAPPLICATIONS_DIR = resolve(ROOT, 'force-app/main/default/webapplications');
+const DATA_DIR = resolve(ROOT, 'force-app/main/default/data');
+const DATA_PLAN = resolve(ROOT, 'force-app/main/default/data/data-plan.json');
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let targetOrg = null;
+  let webappName = null;
+  let permsetName = 'Property_Management_Access';
+  const flags = {
+    skipLogin: false,
+    skipDeploy: false,
+    skipPermset: false,
+    skipData: false,
+    skipGraphql: false,
+    skipWebappBuild: false,
+    skipDev: false,
+  };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--target-org' && args[i + 1]) {
+      targetOrg = args[++i];
+    } else if (args[i] === '--webapp-name' && args[i + 1]) {
+      webappName = args[++i];
+    } else if (args[i] === '--permset-name' && args[i + 1]) {
+      permsetName = args[++i];
+    } else if (args[i] === '--skip-login') flags.skipLogin = true;
+    else if (args[i] === '--skip-deploy') flags.skipDeploy = true;
+    else if (args[i] === '--skip-permset') flags.skipPermset = true;
+    else if (args[i] === '--skip-data') flags.skipData = true;
+    else if (args[i] === '--skip-graphql') flags.skipGraphql = true;
+    else if (args[i] === '--skip-webapp-build') flags.skipWebappBuild = true;
+    else if (args[i] === '--skip-dev') flags.skipDev = true;
+    else if (args[i] === '--help' || args[i] === '-h') {
+      console.log(`
+Setup CLI — one-command setup for apps in this project
+
+Usage:
+  node scripts/setup-cli.mjs --target-org <alias> [options]
+
+Required:
+  --target-org <alias>   Target Salesforce org alias (e.g. myorg)
+
+Options:
+  --webapp-name <name>   Web app folder name under webapplications/ (default: auto-detect)
+  --permset-name <name>  Permission set to assign (default: Property_Management_Access)
+  --skip-login           Skip login step (login is auto-skipped if org is already connected)
+  --skip-deploy          Do not deploy metadata
+  --skip-permset         Do not assign permission set
+  --skip-data            Do not prepare data or run data import
+  --skip-graphql         Do not fetch schema or run GraphQL codegen
+  --skip-webapp-build    Do not npm install / build the web application
+  --skip-dev             Do not launch the dev server at the end
+  -h, --help             Show this help
+`);
+      process.exit(0);
+    }
+  }
+  if (!targetOrg) {
+    console.error('Error: --target-org <alias> is required.');
+    process.exit(1);
+  }
+  return { targetOrg, webappName, permsetName, ...flags };
+}
+
+function discoverWebappDir(webappName) {
+  if (webappName) {
+    const dir = resolve(WEBAPPLICATIONS_DIR, webappName);
+    if (!existsSync(dir)) {
+      console.error(`Error: Web app directory not found: ${dir}`);
+      process.exit(1);
+    }
+    return dir;
+  }
+  if (!existsSync(WEBAPPLICATIONS_DIR)) {
+    console.error(`Error: webapplications directory not found: ${WEBAPPLICATIONS_DIR}`);
+    process.exit(1);
+  }
+  const entries = readdirSync(WEBAPPLICATIONS_DIR, { withFileTypes: true });
+  const dirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith('.'));
+  if (dirs.length === 0) {
+    console.error(`Error: No web app folder found under ${WEBAPPLICATIONS_DIR}`);
+    process.exit(1);
+  }
+  if (dirs.length > 1) {
+    console.log(`Multiple web apps found; using first: ${dirs[0].name}`);
+  }
+  return resolve(WEBAPPLICATIONS_DIR, dirs[0].name);
+}
+
+function isOrgConnected(targetOrg) {
+  const result = spawnSync('sf', ['org', 'display', '--target-org', targetOrg, '--json'], {
+    cwd: ROOT,
+    stdio: 'pipe',
+    shell: true,
+  });
+  return result.status === 0;
+}
+
+function run(name, cmd, args, opts = {}) {
+  const { cwd = ROOT, optional = false } = opts;
+  console.log('\n---', name, '---');
+  const result = spawnSync(cmd, args, {
+    cwd,
+    stdio: 'inherit',
+    shell: true,
+    ...(opts.timeout && { timeout: opts.timeout }),
+  });
+  if (result.status !== 0 && !optional) {
+    console.error(`\nSetup failed at step: ${name}`);
+    process.exit(result.status ?? 1);
+  }
+  return result;
+}
+
+function main() {
+  const {
+    targetOrg,
+    webappName,
+    permsetName,
+    skipLogin,
+    skipDeploy,
+    skipPermset,
+    skipData,
+    skipGraphql,
+    skipWebappBuild,
+    skipDev,
+  } = parseArgs();
+
+  const webappDir = discoverWebappDir(webappName);
+  const hasDataPlan = existsSync(DATA_PLAN) && existsSync(DATA_DIR);
+  const doData = !skipData && hasDataPlan;
+
+  console.log('Setup — target org:', targetOrg, '| web app:', webappDir);
+  console.log(
+    'Steps: login=%s deploy=%s permset=%s data=%s graphql=%s webapp=%s dev=%s',
+    !skipLogin,
+    !skipDeploy,
+    !skipPermset,
+    doData,
+    !skipGraphql,
+    !skipWebappBuild,
+    !skipDev
+  );
+  if (skipData && hasDataPlan) {
+    console.log('(Data dir present; use without --skip-data to run data import.)');
+  } else if (!hasDataPlan && !skipData) {
+    console.log('(No data plan found; skipping data step.)');
+  }
+
+  if (!skipLogin) {
+    if (isOrgConnected(targetOrg)) {
+      console.log('\n--- Login ---');
+      console.log(`Org ${targetOrg} is already authenticated; skipping browser login.`);
+    } else {
+      run('Login (browser)', 'sf', ['org', 'login', 'web', '--alias', targetOrg], { optional: true });
+    }
+  }
+
+  if (!skipDeploy) {
+    run('Deploy metadata', 'sf', ['project', 'deploy', 'start', '--target-org', targetOrg], {
+      timeout: 180000,
+    });
+  }
+
+  if (!skipPermset && permsetName) {
+    console.log('\n--- Assign permission set ---');
+    const permsetResult = spawnSync(
+      'sf',
+      ['org', 'assign', 'permset', '--name', permsetName, '--target-org', targetOrg],
+      {
+        cwd: ROOT,
+        stdio: 'pipe',
+        shell: true,
+      }
+    );
+    if (permsetResult.status === 0) {
+      console.log('Permission set assigned.');
+    } else {
+      const out =
+        (permsetResult.stderr?.toString() || '') + (permsetResult.stdout?.toString() || '');
+      if (out.includes('Duplicate') && out.includes('PermissionSet')) {
+        console.log('Permission set already assigned; skipping.');
+      } else if (out.includes('not found') && out.includes('target org')) {
+        console.log(`Permission set "${permsetName}" not in org; skipping.`);
+      } else {
+        process.stdout.write(permsetResult.stdout?.toString() || '');
+        process.stderr.write(permsetResult.stderr?.toString() || '');
+        console.error('\nSetup failed at step: Assign permission set');
+        process.exit(permsetResult.status ?? 1);
+      }
+    }
+  }
+
+  if (doData) {
+    // Prepare data for uniqueness (run before import so repeat imports don't conflict)
+    const prepareScript = resolve(__dirname, 'prepare-import-unique-fields.js');
+    run('Prepare data (unique fields)', 'node', [prepareScript, '--data-dir', DATA_DIR], {
+      cwd: ROOT,
+    });
+    // Data import tree: if only DUPLICATES_DETECTED (org duplicate rules), warn and continue
+    console.log('\n--- Data import tree ---');
+    const importResult = spawnSync(
+      'sf',
+      ['data', 'import', 'tree', '--plan', DATA_PLAN, '--target-org', targetOrg, '--json'],
+      { cwd: ROOT, stdio: 'pipe', shell: true, timeout: 120000 }
+    );
+    const out = (importResult.stdout?.toString() || '') + (importResult.stderr?.toString() || '');
+    if (importResult.status !== 0) {
+      let onlyDuplicates = false;
+      try {
+        const j = JSON.parse(out);
+        const errors = Array.isArray(j?.data) ? j.data : [];
+        onlyDuplicates =
+          errors.length > 0 &&
+          errors.every((e) => e.StatusCode === 'DUPLICATES_DETECTED' || e.statusCode === 'DUPLICATES_DETECTED');
+      } catch (_) {
+        onlyDuplicates = out.includes('DUPLICATES_DETECTED') && /Use one of these records\?/.test(out);
+      }
+      if (onlyDuplicates) {
+        console.warn(
+          'Data import hit org duplicate rules (e.g. Contact). Skipping import; rest of setup continues.'
+        );
+      } else {
+        process.stdout.write(importResult.stdout?.toString() || '');
+        process.stderr.write(importResult.stderr?.toString() || '');
+        console.error('\nSetup failed at step: Data import tree');
+        process.exit(importResult.status ?? 1);
+      }
+    }
+  }
+
+  if (!skipGraphql || !skipWebappBuild) {
+    run('Web app npm install', 'npm', ['install'], { cwd: webappDir });
+  }
+
+  if (!skipGraphql) {
+    run('Set default org for schema', 'sf', ['config', 'set', 'target-org', targetOrg, '--global']);
+    run('GraphQL schema (introspect)', 'npm', ['run', 'graphql:schema'], { cwd: webappDir });
+    run('GraphQL codegen', 'npm', ['run', 'graphql:codegen'], { cwd: webappDir });
+  }
+
+  if (!skipWebappBuild) {
+    run('Web app build', 'npm', ['run', 'build'], { cwd: webappDir });
+  }
+
+  console.log('\n--- Setup complete ---');
+
+  if (!skipDev) {
+    console.log('\n--- Launching dev server (Ctrl+C to stop) ---\n');
+    run('Dev server', 'npm', ['run', 'dev'], { cwd: webappDir });
+  }
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-app-react-template-b2e-experimental",
-  "version": "1.83.0",
+  "version": "1.84.0",
   "description": "B2E template app (from BYO)",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",