@salesforce/webapp-template-feature-graphql-experimental 1.35.1 → 1.36.0

package/README.md

@@ -1,46 +1,50 @@
 # Feature: GraphQL Data Access
 
-This package provides Salesforce GraphQL data access utilities, codegen tooling, an example component, agent skills, and rules.
+> **Note:** GraphQL is now built into `@salesforce/webapp-template-base-react-app-experimental` by default. This package provides AI agent skills, rules, and documentation for GraphQL development.
 
-A "feature" can be composed of any of the following:
+This package provides:
 
-- Extension of the base app via [@salesforce/webapp-template-cli-experimental](../../cli/README.md)
-- [Components](#components)
-- [Rules](#rules)
-- [Skills](#skills)
+- **Agent skills** for AI-assisted GraphQL development (schema exploration, query generation, mutation generation)
+- **Rules** for consistent GraphQL patterns across AI coding agents
+- **Documentation** and best practices for using GraphQL with Salesforce
 
-## Components
+## What's in the Base App
 
-This feature ships the core GraphQL data access layer and an example component:
+The base React app (`@salesforce/webapp-template-base-react-app-experimental`) includes all GraphQL tooling out of the box:
 
-- **`executeGraphQL<T>(query, variables?)`**: Type-safe GraphQL execution against the Salesforce UIAPI
-- **`gql` template tag**: Inline GraphQL query definitions with editor syntax highlighting
-- **`NodeOfConnection<T>` utility type**: Extract node types from Salesforce connection (edges/node) patterns
-- **`AccountsTable`**: Example component that fetches and displays high-revenue Accounts via GraphQL
-- **Generated types**: Auto-generated TypeScript types from `.graphql` files via codegen
+- `@salesforce/sdk-data` dependency
+- GraphQL ESLint plugin and rules
+- GraphQL codegen dependencies and configuration (`codegen.yml`)
+- `executeGraphQL<T>()` utility and `gql` template tag
+- Example components: `AccountsTable`, `AccountsPage`
+- Type-safe GraphQL patterns with codegen
+- `npm run graphql:schema` — download schema from a connected Salesforce org
+- `npm run graphql:codegen` — generate TypeScript types from `.graphql` files and `gql` queries
 
-### Example Usage
+All new apps built from `base-react-app` get GraphQL support out of the box.
 
-```tsx
-import {
-  executeGraphQL,
-  gql,
-  AccountsTable,
-} from "@salesforce/webapp-template-feature-graphql-experimental";
+---
 
-// Use the ready-made component
-<AccountsTable />;
+## Skills
 
-// Or use the utilities directly
-const data = await executeGraphQL<MyQuery>(MY_QUERY, variables);
-```
+> [https://docs.cline.bot/features/skills](https://docs.cline.bot/features/skills)
+
+This package includes a **skill** for AI agents to generate GraphQL data access code:
+
+- **graphql-data-access**: End-to-end workflow from schema exploration → query generation → type generation → implementation
+- Includes knowledge docs for schema exploration, read query generation, and mutation query generation
+- Includes the shared Salesforce GraphQL schema definition (`shared-schema.graphqls`)
 
-### Reference Examples
+**Installation:**
 
-- `src/.../components/AccountsTable.tsx` — Component using GraphQL to fetch and render Accounts
-- `src/.../pages/AccountsPage.tsx` — Page wrapping the AccountsTable
-- `src/.../api/utils/accounts.ts` — Pattern 1 (external `.graphql` file + codegen types)
-- `src/.../api/utils/user.ts` — Pattern 2 (inline `gql` tag)
+```bash
+# Copy skill to your coding agent's skills directory
+cp -r skills/graphql-data-access ~/.cursor/skills/
+# Or for Cline:
+cp -r skills/graphql-data-access ~/.cline/skills/
+```
+
+The skill references the base app's `npm run graphql:codegen` and `npm run graphql:schema` scripts — no additional setup needed.
 
 ---
 
@@ -48,57 +52,40 @@ const data = await executeGraphQL<MyQuery>(MY_QUERY, variables);
 
 > [https://docs.cline.bot/features/cline-rules](https://docs.cline.bot/features/cline-rules)
 
-The feature includes **rules** that define conventions for GraphQL data access:
+This package includes **rules** that define conventions for GraphQL data access:
 
 - Use `executeGraphQL<T>()` (never raw fetch/axios)
 - Always provide response type generics
 - Use `gql` tag or `.graphql` files (never plain strings)
 - Follow the two-pattern workflow (external file vs. inline)
 
-Copy `rules/graphql-data-access-rule.md` into your project's `.clinerules/` (Cline) or `.cursor/rules/` (Cursor).
-
----
-
-## Skills
-
-> [https://docs.cline.bot/features/skills](https://docs.cline.bot/features/skills)
-
-The feature includes a **skill** for AI agents to generate GraphQL data access code:
-
-- **graphql-data-access**: End-to-end workflow from schema exploration → query generation → type generation → implementation
-- Includes knowledge docs for schema exploration, read query generation, and mutation query generation
-- Includes the shared Salesforce GraphQL schema definition (`shared-schema.graphqls`)
-- Includes scripts for codegen and downloading org schema via introspection (`scripts/codegen.js`, `scripts/get-graphql-schema.mjs`)
+**Installation:**
 
-Copy the `skills/graphql-data-access/` folder into `.cline/skills/` (Cline) or `.cursor/skills/` (Cursor). The skill is fully self-contained — scripts, docs, and schema all travel with it.
+```bash
+# Copy rules to your coding agent's rules directory
+cp rules/graphql-data-access-rule.md ~/.cursor/rules/
+# Or for Cline:
+cp rules/graphql-data-access-rule.md ~/.clinerules/
+```
 
 ---
 
-## Dependencies
+## Reference Examples
 
-**Runtime:**
+The base React app includes reference examples:
 
-- `@salesforce/sdk-data` — Salesforce data SDK (provides `sdk.graphql()` and `gql`)
-
-**Dev/Codegen:**
-
-- `@graphql-codegen/cli` — GraphQL code generation CLI
-- `@graphql-codegen/typescript` — TypeScript type generation plugin
-- `@graphql-codegen/typescript-operations` — Operations type generation plugin
-- `graphql-codegen-typescript-operation-types` — Operation types plugin
-- `vite-plugin-graphql-codegen` — Vite integration for automatic codegen
-- `graphql` — the official JavaScript implementation of the GraphQL Specification
+- `src/api/graphql.ts` — Core `executeGraphQL()` utility
+- `src/api/utils/accounts.ts` — Pattern 1 (external `.graphql` file + codegen types)
+- `src/api/utils/user.ts` — Pattern 2 (inline `gql` tag)
+- `src/components/AccountsTable.tsx` — Component using GraphQL to fetch and render Accounts
+- `src/pages/AccountsPage.tsx` — Page wrapping the AccountsTable
 
 ---
 
-## Build & Testing
-
-You can test the extension of the base app and the components via the following:
+## Installation
 
 ```bash
-npm run build   # apply patches → dist
-npm run dev     # run from dist
-npm run watch   # watch and re-apply
+npm install @salesforce/webapp-template-feature-graphql-experimental
 ```
 
-Note that this does not test rules and skills. To do so, you need to copy the rules and skills to the appropriate folders for your coding agent.
+Then copy the skills and rules to your coding agent's directories (see above).

package/package.json

@@ -1,57 +1,20 @@
 {
   "name": "@salesforce/webapp-template-feature-graphql-experimental",
-  "version": "1.35.1",
-  "description": "GraphQL data access feature with executeGraphQL utilities, codegen tooling, agent skills, and rules",
+  "version": "1.36.0",
+  "description": "GraphQL documentation, agent skills, and rules for Salesforce web applications",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",
   "type": "module",
-  "main": "src/force-app/main/default/webapplications/feature-graphql/src/index.ts",
-  "types": "src/force-app/main/default/webapplications/feature-graphql/src/index.ts",
-  "exports": {
-    ".": {
-      "types": "./src/force-app/main/default/webapplications/feature-graphql/src/index.ts",
-      "import": "./src/force-app/main/default/webapplications/feature-graphql/src/index.ts",
-      "default": "./src/force-app/main/default/webapplications/feature-graphql/src/index.ts"
-    }
-  },
   "files": [
-    "dist",
-    "src",
     "rules",
-    "skills"
+    "skills",
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "clean": "rm -rf dist",
-    "dev": "cd dist/force-app/main/default/webapplications/feature-graphql && npm install && npm run dev",
-    "watch": "npx tsx ../../cli/src/index.ts watch-patches packages/template/feature/feature-graphql packages/template/base-app/base-react-app packages/template/feature/feature-graphql/dist"
-  },
-  "devDependencies": {
-    "@graphql-codegen/cli": "^6.1.0",
-    "@graphql-codegen/typescript": "^5.0.6",
-    "@graphql-codegen/typescript-operations": "^5.0.6",
-    "@salesforce/sdk-data": "^1.35.1",
-    "@salesforce/webapp-experimental": "^1.35.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
-    "graphql": "^16.11.0",
-    "graphql-codegen-typescript-operation-types": "^2.0.2",
-    "react-dom": "^19.2.1",
-    "react-router": "^7.10.1",
-    "vite": "^7.3.1",
-    "vite-plugin-graphql-codegen": "^3.6.3"
-  },
-  "nx": {
-    "targets": {
-      "build": {
-        "executor": "@salesforce/webapp-template-cli-experimental:apply-patches"
-      },
-      "test": {
-        "executor": "@salesforce/webapp-template-cli-experimental:build-dist-app"
-      }
-    }
+    "clean": "echo 'No build artifacts to clean'"
   },
-  "gitHead": "e16e1218a56c6c03b8c71ec2e2057b3ecc4eb2e2"
+  "gitHead": "b777854a57e42c3f676507c4b1ad27e23fbbd0d0"
 }

package/rules/graphql-data-access-rule.md

@@ -17,12 +17,12 @@ Types are auto-generated at: `src/api/graphql-operations-types.ts`
 ### Generation Command
 
 ```bash
-npx graphql-codegen --config <path-to-codegen-config>/codegen.js
+npm run graphql:codegen
 ```
 
-The codegen configuration is provided by the `graphql-data-access` skill at `scripts/codegen.js` and generates types from:
+The codegen configuration is at `codegen.yml` and generates types from:
 
-- Schema: `schema.graphql` (root level)
+- Schema: `schema.graphql` (project root)
 - Documents: `src/**/*.{graphql,ts,tsx}`
 
 ### Type Naming Convention
@@ -151,7 +151,7 @@ query GetMyData($myVariable: String) {
 #### Step 2: Run Code Generation
 
 ```bash
-npx graphql-codegen --config <path-to-codegen-config>/codegen.js
+npm run graphql:codegen
 ```
 
 This generates types in `graphql-operations-types.ts`:
@@ -387,7 +387,7 @@ Before completing GraphQL data access code:
 ### For Pattern 1 (.graphql files):
 
 1. [ ] Create `.graphql` file for the query/mutation
-2. [ ] Run `npx graphql-codegen --config <path-to-codegen-config>/codegen.js` to generate types
+2. [ ] Run `npm run graphql:codegen` to generate types
 3. [ ] Import query with `?raw` suffix
 4. [ ] Import generated types from `graphql-operations-types.ts`
 5. [ ] Use `executeGraphQL<ResponseType>()` with proper generic

package/skills/graphql-data-access/SKILL.md

@@ -14,52 +14,29 @@ Add or modify Salesforce GraphQL data access code using the established `execute
 - User wants to add a new GraphQL operation (query or mutation)
 - User asks to add data access for a Salesforce object (Account, Contact, Opportunity, etc.)
 
-## Dependencies
-
-Before using this skill, ensure the following packages are installed in the project.
-
-**Runtime** (required for `executeGraphQL` and `gql`):
-
-```bash
-npm install @salesforce/sdk-data
-```
-
-**Codegen** (required for type generation from `.graphql` files and inline `gql` queries):
-
-```bash
-npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations graphql-codegen-typescript-operation-types graphql
-```
+## Prerequisites
 
-**Schema introspection** (required for downloading the schema from a Salesforce org):
+The base React app (`base-react-app`) ships with all GraphQL dependencies and tooling pre-configured:
 
-```bash
-npm install -D @salesforce/webapp-experimental
-```
+- `@salesforce/sdk-data` — runtime SDK for `executeGraphQL` and `gql`
+- `@graphql-codegen/cli` + plugins — type generation from `.graphql` files and inline `gql` queries
+- `@graphql-eslint/eslint-plugin` — linting for `.graphql` files and `gql` template literals
+- `graphql` — shared by codegen, ESLint, and schema introspection
 
-> `graphql` is shared by both codegen and schema introspection — only needs to be installed once.
+Before using this skill, ensure:
 
-## Prerequisites
-
-1. The `api/graphql.ts` utility must exist in the project (provided by this feature)
-2. A `schema.graphql` file should exist at the project root. If missing, generate it:
+1. The `api/graphql.ts` utility exists in the project (provided by the base app)
+2. A `schema.graphql` file exists at the project root. If missing, generate it:
    ```bash
-   node <this-skill>/scripts/get-graphql-schema.mjs
+   npm run graphql:schema
    ```
 
-> In all commands below, replace `<this-skill>` with the actual path to this skill's directory (e.g., `.cursor/skills/graphql-data-access`).
-
-## Scripts
+## npm Scripts
 
-This skill includes standalone scripts in its `scripts/` directory. Run them directly — no npm script setup required.
+The base app provides two npm scripts for GraphQL tooling:
 
-- **`scripts/codegen.js`** — GraphQL codegen configuration. Generates TypeScript types from `.graphql` files and inline `gql` queries.
-  ```bash
-  npx graphql-codegen --config <this-skill>/scripts/codegen.js
-  ```
-- **`scripts/get-graphql-schema.mjs`** — Downloads the full GraphQL schema from a connected Salesforce org via introspection. Outputs `schema.graphql` to the project root.
-  ```bash
-  node <this-skill>/scripts/get-graphql-schema.mjs
-  ```
+- **`npm run graphql:schema`** — Downloads the full GraphQL schema from a connected Salesforce org via introspection. Outputs `schema.graphql` to the project root.
+- **`npm run graphql:codegen`** — Generates TypeScript types from `.graphql` files and inline `gql` queries. Outputs to `src/api/graphql-operations-types.ts`.
 
 ## Workflow
 
@@ -107,7 +84,7 @@ For **Pattern 2**:
 ### Step 4: Generate Types
 
 ```bash
-npx graphql-codegen --config <this-skill>/scripts/codegen.js
+npm run graphql:codegen
 ```
 
 This updates `src/api/graphql-operations-types.ts` with:
@@ -163,5 +140,5 @@ export async function getSimpleData(): Promise<SomeType> {
 - Read query generation: `docs/generate-read-query.md`
 - Mutation query generation: `docs/generate-mutation-query.md`
 - Shared GraphQL schema types: `docs/shared-schema.graphqls`
-- Codegen config: `scripts/codegen.js`
-- Schema download script: `scripts/get-graphql-schema.mjs`
+- Schema download: `npm run graphql:schema` (in the base app)
+- Type generation: `npm run graphql:codegen` (in the base app)

package/skills/graphql-data-access/docs/explore-schema.md

@@ -11,7 +11,7 @@ This document provides guidance for AI agents working with the Salesforce GraphQ
 If the file is not present, generate it by running:
 
 ```bash
-node <this-skill>/scripts/get-graphql-schema.mjs
+npm run graphql:schema
 ```
 
 ## Required Pre-Flight Check
@@ -20,7 +20,7 @@ node <this-skill>/scripts/get-graphql-schema.mjs
 
 1. **Check if schema exists**: Look for `schema.graphql` in the project root
 2. **If schema is missing**:
-   - Run `node <this-skill>/scripts/get-graphql-schema.mjs` to download it
+   - Run `npm run graphql:schema` to download it
    - Wait for the command to complete successfully
    - Then proceed with schema exploration
 3. **If schema exists**: Proceed with targeted searches as described below
@@ -229,7 +229,7 @@ Salesforce GraphQL returns field values wrapped in typed objects:
 **Pre-requisites (MANDATORY):**
 
 - [ ] Verified `schema.graphql` exists in project root
-- [ ] If missing, ran `node <this-skill>/scripts/get-graphql-schema.mjs` and waited for completion
+- [ ] If missing, ran `npm run graphql:schema` and waited for completion
 - [ ] Confirmed connection to correct Salesforce org (if downloading fresh schema)
 
 **Workflow Steps:**

package/dist/.a4drules/build-validation.md

@@ -1,81 +0,0 @@
-# AI Rule: Build Validation
-
-Build validation for successful deployments with minimal friction.
-
-## Targets
-- `force-app/main/default/webapplications/*/**/*`
-- `**/*.{js,ts,jsx,tsx}`
-
-## MANDATORY: Build Success
-
-**Before completing any coding session:**
-```bash
-npm run build  # MUST succeed with no errors
-```
-
-## Quick Quality Checks
-```bash
-npm run format:check  # Auto-fixable
-npm run lint          # Most issues auto-fixable
-tsc -b               # Catches major issues
-```
-
-## Requirements
-
-**Must Pass:**
-- `npm run build` completes successfully
-- No TypeScript compilation errors
-- No critical ESLint errors
-
-**Can Be Warnings:**
-- ESLint warnings
-- Prettier formatting issues
-- Minor TypeScript warnings
-
-## Auto-Fix Commands
-```bash
-npm run fix-all      # Fix formatting + linting
-npm run format       # Fix Prettier issues
-npm run lint:fix     # Fix ESLint issues
-```
-
-## Workflow
-
-**During Development:**
-1. Write code with AI assistance
-2. Save frequently (auto-format on save)
-3. Check periodically: `npm run lint` (optional)
-
-**Before Completion:**
-1. Run `npm run build`
-2. If fails: Run `npm run fix-all`, fix TypeScript errors, retry build
-
-## Error Priority
-
-**Fix Immediately:**
-- TypeScript compilation errors
-- Import/export errors
-- Syntax errors
-
-**Fix When Convenient:**
-- ESLint warnings
-- Prettier formatting
-- Unused variables
-
-## Hard Requirements
-- Build must complete without errors
-- No broken imports
-- Basic TypeScript type safety
-
-## Key Commands
-```bash
-npm run dev          # Start development
-npm run build        # Check deployment readiness
-npm run fix-all      # Fix common issues
-```
-
-## Troubleshooting Import Errors
-```bash
-npm install          # Check missing dependencies
-# Verify file exists, case sensitivity, export/import match
-```

package/dist/.a4drules/code-quality.md

@@ -1,150 +0,0 @@
-# AI Rule: Code Quality Standards
-
-Enforces ESLint, Prettier, and coding best practices for consistent, maintainable code.
-
-## Targets
-- `force-app/main/default/webapplications/*/**/*`
-- `**/*.{js,ts,jsx,tsx,json,md}`
-
-## MANDATORY Checks
-
-**Before writing code:**
-```bash
-npm run lint         # MUST result in: 0 problems (0 errors, 0 warnings)
-npm run format:check # MUST result in: All matched files use Prettier code style!
-```
-
-## Prettier Config (.prettierrc)
-```json
-{
-  "semi": true,
-  "trailingComma": "es5",
-  "singleQuote": true,
-  "printWidth": 80,
-  "tabWidth": 2,
-  "useTabs": false,
-  "bracketSpacing": true,
-  "arrowParens": "avoid",
-  "endOfLine": "lf"
-}
-```
-
-## Auto-Fix Commands
-```bash
-npm run fix-all      # Fix formatting + linting (recommended)
-npm run format       # Fix Prettier issues
-npm run lint:fix     # Fix ESLint issues
-```
-
-## Import Order (MANDATORY)
-```typescript
-// 1. React ecosystem
-import { useState, useEffect } from 'react';
-
-// 2. External libraries (alphabetical)
-import axios from 'axios';
-import clsx from 'clsx';
-
-// 3. UI components (alphabetical)
-import { Button } from '@/components/ui/button';
-import { Card } from '@/components/ui/card';
-
-// 4. Internal utilities (alphabetical)
-import { useAuth } from '../hooks/useAuth';
-import { formatDate } from '../utils/dateUtils';
-
-// 5. Relative imports
-import { ComponentA } from './ComponentA';
-
-// 6. Type imports (separate, at end)
-import type { User, ApiResponse } from '../types';
-```
-
-## Naming Conventions
-```typescript
-// PascalCase: Components, classes
-const UserProfile = () => {};
-const ApiClient = class {};
-
-// camelCase: Variables, functions, properties
-const userName = 'john';
-const fetchUserData = async () => {};
-
-// SCREAMING_SNAKE_CASE: Constants
-const API_BASE_URL = 'https://api.example.com';
-
-// kebab-case: Files
-// user-profile.tsx, api-client.ts
-```
-
-## React Component Structure
-```typescript
-interface ComponentProps {
-  // Props interface first
-}
-
-const Component: React.FC<ComponentProps> = ({ prop1, prop2 }) => {
-  // 1. Hooks
-  // 2. Computed values
-  // 3. Event handlers
-  // 4. JSX return
-
-  return <div />;
-};
-
-export default Component;
-```
-
-## JSX Standards
-```typescript
-// Self-closing tags
-<Button onClick={handleClick} />
-
-// Conditional rendering
-{isLoading && <Spinner />}
-{error ? <ErrorMessage error={error} /> : <Content />}
-
-// Lists with keys
-{items.map(item => <Item key={item.id} data={item} />)}
-```
-
-## Error Handling
-```typescript
-// Async functions with try-catch
-const fetchData = async (id: string): Promise<Data> => {
-  try {
-    const response = await api.get(`/data/${id}`);
-    return response.data;
-  } catch (error) {
-    console.error('Failed to fetch data:', error);
-    throw error;
-  }
-};
-```
-
-## Anti-Patterns (FORBIDDEN)
-```typescript
-// NEVER disable ESLint without justification
-// eslint-disable-next-line
-
-// NEVER mutate state directly
-state.items.push(newItem); // Wrong
-setItems(prev => [...prev, newItem]); // Correct
-
-// NEVER use magic numbers/strings
-setTimeout(() => {}, 5000); // Wrong
-const DEBOUNCE_DELAY = 5000; // Correct
-```
-
-## Quality Workflow
-
-**Before Committing:**
-1. `npm run check-all` - All checks must pass
-2. `npm run fix-all` - Auto-fix issues if needed
-3. `npm run build` - Build must succeed
-
-## Zero Tolerance Policy
-- ESLint errors: MUST be 0
-- ESLint warnings: MUST be 0
-- Prettier violations: MUST be 0
-- TypeScript errors: MUST be 0