diff --git a/skills/fw-react-app/.claude-plugin/plugin.json b/skills/fw-react-app/.claude-plugin/plugin.json new file mode 100644 index 0000000..9303e82 --- /dev/null +++ b/skills/fw-react-app/.claude-plugin/plugin.json @@ -0,0 +1,45 @@ +{ + "name": "fw-react-app", + "displayName": "Freshworks React Meta Apps", + "version": "1.0.0", + "description": "Creates and extends Freshworks Platform 3.0 apps using the React Meta framework (metaConfig.framework react, JSX, FDK bundler). Slash commands: /react-meta-scaffold, /react-meta-add-surface, /react-meta-validate. Platform rules and fdk validate depth live in fw-app-dev; use fw-setup for Node/FDK installation.", + "author": { + "name": "Freshworks Developers", + "email": "skills@dev-assist.freshservice.com" + }, + "homepage": "https://github.com/freshworks-developers/fw-dev-tools", + "repository": "https://github.com/freshworks-developers/fw-dev-tools/tree/main/skills/fw-react-app", + "license": "MIT", + "category": "developer-tools", + "strict": false, + "keywords": [ + "freshworks", + "platform-3.0", + "react-meta", + "fdk", + "marketplace", + "react" + ], + "interface": { + "displayName": "Freshworks React Meta Apps", + "shortDescription": "Scaffold React Meta apps, add placeholder surfaces, validate with FDK.", + "longDescription": "FDK react-starter-template workflows, HTML shells with {{{appclient}}}, per-surface JSX entries, and metaConfig. Defers manifest, requests, OAuth, and server lint rules to fw-app-dev." + }, + "commands": [ + { + "name": "react-meta-scaffold", + "description": "Create a new React Meta app using fdk create + react-starter-template", + "file": "commands/react-meta-scaffold.md" + }, + { + "name": "react-meta-add-surface", + "description": "Add a new placeholder/HTML surface with a dedicated JSX entry", + "file": "commands/react-meta-add-surface.md" + }, + { + "name": "react-meta-validate", + "description": "Run fdk validate and auto-fix loop for a React Meta app", + "file": "commands/react-meta-validate.md" + } + ] +} diff --git a/skills/fw-react-app/.cursor-plugin/plugin.json b/skills/fw-react-app/.cursor-plugin/plugin.json new file mode 100644 index 0000000..dfb596e --- /dev/null +++ b/skills/fw-react-app/.cursor-plugin/plugin.json @@ -0,0 +1,48 @@ +{ + "name": "fw-react-app", + "displayName": "Freshworks React Meta Apps", + "version": "1.0.0", + "description": "Creates and extends Freshworks Platform 3.0 apps using the React Meta framework (metaConfig.framework react, JSX, FDK bundler). Slash commands: /react-meta-scaffold, /react-meta-add-surface, /react-meta-validate. Platform rules and fdk validate depth live in fw-app-dev; use fw-setup for Node/FDK installation.", + "author": { + "name": "Freshworks Developers", + "email": "skills@dev-assist.freshservice.com" + }, + "homepage": "https://github.com/freshworks-developers/fw-dev-tools", + "repository": "https://github.com/freshworks-developers/fw-dev-tools/tree/main/skills/fw-react-app", + "license": "MIT", + "keywords": [ + "freshworks", + "platform-3.0", + "react-meta", + "fdk", + "marketplace", + "react" + ], + "strict": false, + "interface": { + "displayName": "Freshworks React Meta Apps", + "shortDescription": "Scaffold React Meta apps, add placeholder surfaces, validate with FDK.", + "longDescription": "FDK react-starter-template workflows, HTML shells with {{{appclient}}}, per-surface JSX entries, and metaConfig. Defers manifest, requests, OAuth, and server lint rules to fw-app-dev." + }, + "category": "developer-tools", + "tags": ["freshworks", "react", "fdk"], + "rulesDirectory": "./rules", + "commandsDirectory": "./commands", + "commands": [ + { + "name": "react-meta-scaffold", + "description": "Create a new React Meta app using fdk create + react-starter-template", + "file": "commands/react-meta-scaffold.md" + }, + { + "name": "react-meta-add-surface", + "description": "Add a new placeholder/HTML surface with a dedicated JSX entry", + "file": "commands/react-meta-add-surface.md" + }, + { + "name": "react-meta-validate", + "description": "Run fdk validate and auto-fix loop for a React Meta app", + "file": "commands/react-meta-validate.md" + } + ] +} diff --git a/skills/fw-react-app/README.md b/skills/fw-react-app/README.md new file mode 100644 index 0000000..4fcb57f --- /dev/null +++ b/skills/fw-react-app/README.md @@ -0,0 +1,38 @@ +# fw-react-app + +Freshworks **Platform 3.0** skill for **React Meta** apps: `metaConfig.framework` `"react"`, JSX entries, FDK bundler, and per-surface HTML shells. + +## Layout (matches [fw-app-dev](https://github.com/freshworks-developers/fw-dev-tools/tree/main/skills/fw-app-dev)) + +| Path | Role | +|------|------| +| `SKILL.md` | Main instructions | +| `README.md` | This file | +| `.cursor-plugin/plugin.json` | Cursor plugin manifest + slash commands | +| `.claude-plugin/plugin.json` | Claude Code plugin manifest + slash commands | +| `commands/` | Slash command docs (`/react-meta-*`) | +| `rules/` | Cursor rules (bootstrap, orchestration) | +| `references/` | Quick reference tables, doc links | +| `agents/` | Optional focused review prompts | +| `assets/templates/` | Notes; official scaffold = `fdk create` → `react-starter-template` | + +## Slash commands (Cursor / Claude plugin) + +- **`/react-meta-scaffold`** — new app via **react-starter-template** +- **`/react-meta-add-surface`** — add placeholder + HTML + JSX entry +- **`/react-meta-validate`** — **`fdk validate`** with zero-error discipline + +## Dependencies + +- **Toolchain:** **fw-setup** (Node 24 + FDK 10). +- **Platform semantics + validate depth:** **fw-app-dev** (or **app-dev** skill). + +## Install (illustrative) + +If this skill is published under **fw-dev-tools**: + +```bash +npx skills add https://github.com/freshworks-developers/fw-dev-tools --skill fw-react-app +``` + +For local development, point your skills path at this folder. diff --git a/skills/fw-react-app/SKILL.md b/skills/fw-react-app/SKILL.md new file mode 100644 index 0000000..621052a --- /dev/null +++ b/skills/fw-react-app/SKILL.md @@ -0,0 +1,98 @@ +--- +name: fw-react-app +version: "1.0.0" +description: Scaffolds and extends Freshworks Platform 3.0 marketplace apps that use the React Meta framework (manifest metaConfig.framework react, JSX entries, FDK bundler). Use when creating a new React-based FDK app, adding React Meta to a greenfield 3.0 app, adding placeholder surfaces with per-surface HTML + JSX entries, or when the user mentions react-starter-template, React Meta, or FDK React frontend. +compatibility: "Freshworks Platform 3.0; Node.js 24.x + FDK 10.x (see fw-setup). Defers manifest/requests/server/OAuth rules to fw-app-dev." +argument-hint: "[react-meta-scaffold|react-meta-add-surface|react-meta-validate]" +--- + +# Freshworks React Meta app creation + +**Orchestration:** Treat **`fw-app-dev`** (or **`app-dev`**) as the source of truth for Platform 3.0 rules—manifest shape, `fdk validate` loops, request templates (`<%= %>`), OAuth, SMI, security, lint/complexity, and `app/styles/images/icon.svg`. This skill adds **React Meta–specific** structure and workflows on top of that baseline. + +**Related upstream patterns:** [fw-dev-tools/skills](https://github.com/freshworks-developers/fw-dev-tools/tree/main/skills) (`fw-app-dev`, `fw-setup`). + +## Prerequisites + +- **Node.js 24.x** and **FDK 10.x** installed (`node --version`, `fdk version`). If the toolchain is wrong or missing, use **`fw-setup`** / install docs—do not pretend `fdk` exists. +- Target **Platform 3.0** only (`"platform-version": "3.0"`, `modules` not `product`). + +## Canonical create path + +1. Empty folder for the app; **do not** scatter app files in an unrelated repo root. +2. Run **`fdk create`** and select **`react-starter-template`** (official scaffold: `package.json`, `app/index.html`, `app/components/*.jsx`, `vitest.config.js`, etc.). +3. After generation: **`npm install`** if needed, then **`fdk validate`** and fix until **0 platform + 0 lint** errors (same discipline as `fw-app-dev`—up to 6 fix iterations). + +**Local run:** `fdk run` → append `?dev=true` to the product URL (use `&dev=true` if the URL already has query parameters). First-time browser prompt: allow local network access. + +**Local helper URLs** (while `fdk run` is active): `http://localhost:10001/system_settings`, `http://localhost:10001/custom_configs`, `http://localhost:10001/web/test`. + +## React Meta identification + +In **`manifest.json`**, require: + +```json +"metaConfig": { + "framework": "react" +} +``` + +- **`package.json`** is the npm project manifest; list **`react`** and **`react-dom`** as dependencies (versions per template/current FDK expectations—not platform-provided). +- **`engines`:** For new apps, align with **`fw-app-dev`** defaults (**FDK 10.x**, **Node 24.x**) unless the user’s environment forces the documented last-resort path in that skill. + +## HTML entry files (`app/*.html`) + +Every surface (`full_page_app`, `ticket_sidebar`, modals, **`config/iparams.html`**, etc.) **must** include the App SDK script: + +```html + +``` + +- Use **triple braces** `{{{appclient}}}` (Handlebars placeholder). Omitting it leaves `window.app` undefined and breaks all platform APIs. +- Typical shell: `
` plus a **module** entry, e.g. + `` + (exact path matches the surface). + +## Bootstrapping React + +- **Do not** mount the real UI until **`window.app.initialized()`** resolves (iframe channel setup). +- Pattern: call `window.app.initialized().then((client) => { window.client = client; ... })`, then render (often via `createRoot` on `#root`). +- For sidebars and other placeholders, prefer a **small entry file** per surface and optionally a shared wrapper (e.g. lifecycle via `client.events.on('app.activated' | 'app.deactivated')`). Do **not** load the full-page bundle inside a sidebar entry. + +## Surfaces and manifest locations + +- Each placeholder/surface = **its own HTML file** under `app/` + **its own JSX entry**—lightweight and purpose-specific. +- **`full_page_app`** (and other **common** locations) live under **`modules.common.location`**. +- Product-specific placeholders (e.g. Freshdesk **`ticket_sidebar`**) live under the correct product module (e.g. **`modules.support_ticket.location`**). See placement tables in official docs and in [references/react-meta-quick-reference.md](references/react-meta-quick-reference.md). + +**Routing:** Use client-side routing (e.g. React Router) **only** in **`full_page_app`**. Other surfaces should be single-purpose (no multi-page router). + +## Backend and config (unchanged vs vanilla 3.0) + +- **`config/requests.json`**, **`server/server.js`**, events, SMI, **`client.request.invokeTemplate`**, **`client.request.invoke`**, and **`renderData`** behave the same as non-React apps. +- Every **`requests.json`** key must appear under **`modules.common.requests`** in `manifest.json`. +- Secrets stay in **iparams**, request templates, or server code—never in frontend source. + +## Installation parameters + +- Simple forms: **`config/iparams.json`**. +- **Custom React iparams UI:** `config/iparams.html` (with `{{{appclient}}}`) + React under e.g. **`config/assets/components/`**, implementing **`window.getConfigs`**, **`window.postConfigs`**, and **`window.validate`** as required by the platform (see [references/react-meta-quick-reference.md](references/react-meta-quick-reference.md)). + +## Testing and quality bar + +- Run **`fdk validate`** before claiming the app is ready; fix platform and **lint** issues. +- Use **`tests/`** + **`vitest.config.js`** from the template as the starting point for unit tests. +- Optional hooks patterns (`useFreshworksData`, `useInvokeTemplate`, `useServerMethod`, lifecycle context): see [references/react-meta-quick-reference.md](references/react-meta-quick-reference.md). + +## Do not + +- Generate **Platform 2.x** manifests or **`$request.post|get`|** patterns. +- Use **`{{variable}}`** in request templates—use **`<%= iparam.* %>`, `<%= context.* %>`, `<%= access_token %>`** only. +- Ship frontend apps without a manifest **`icon`** path that resolves to an existing file (commonly **`app/styles/images/icon.svg`** per `fw-app-dev`—keep manifest paths and disk layout in sync). + +## Progressive disclosure + +- **Rules:** [rules/react-meta-bootstrap.mdc](rules/react-meta-bootstrap.mdc), [rules/react-meta-orchestration.mdc](rules/react-meta-orchestration.mdc) +- **Commands:** [commands/](commands/) +- **Quick reference:** [references/react-meta-quick-reference.md](references/react-meta-quick-reference.md) +- Full React Meta narrative (bootstrap, templates, SMI, troubleshooting): **React Meta gist** PDF / internal docs diff --git a/skills/fw-react-app/agents/react-meta-review.md b/skills/fw-react-app/agents/react-meta-review.md new file mode 100644 index 0000000..681b620 --- /dev/null +++ b/skills/fw-react-app/agents/react-meta-review.md @@ -0,0 +1,14 @@ +# Agent: React Meta UI review (optional) + +Use when a **large** React Meta change needs a second pass focused on **frontend** correctness—not as a substitute for **`fdk validate`**. + +## Scope + +- Every **`app/*.html`** and **`config/iparams.html`**: **`{{{appclient}}}`** present. +- **`window.app.initialized()`** before dependent UI on **each** JSX entry. +- **Per-surface** entries: no full-page SPA loaded in **sidebar** surfaces. +- **Custom iparams**: **`window.getConfigs`**, **`window.validate`**, **`window.postConfigs`** if applicable. + +## Out of scope + +Repeat **fw-app-dev** / **app-security-scanner** for **server**, **secrets**, **request templates**, **OAuth**—this agent is UI-structure focused. diff --git a/skills/fw-react-app/assets/templates/README.md b/skills/fw-react-app/assets/templates/README.md new file mode 100644 index 0000000..bd63961 --- /dev/null +++ b/skills/fw-react-app/assets/templates/README.md @@ -0,0 +1,10 @@ +# Templates (assets) + +Official React Meta project skeletons come from the **FDK**: + +```bash +fdk create +# select react-starter-template +``` + +This directory is reserved for **optional** snippets or checklists maintained alongside the skill. Prefer generating apps via **`fdk create`** so templates match the installed FDK version. diff --git a/skills/fw-react-app/commands/react-meta-add-surface.md b/skills/fw-react-app/commands/react-meta-add-surface.md new file mode 100644 index 0000000..6507c41 --- /dev/null +++ b/skills/fw-react-app/commands/react-meta-add-surface.md @@ -0,0 +1,22 @@ +--- +name: react-meta-add-surface +description: Add a new app surface (placeholder) with its own app/*.html shell and dedicated JSX entry for Freshworks React Meta. +globs: ["**/manifest.json", "**/app/*.html"] +always: false +--- + +# React Meta — add surface + +**Usage:** `/react-meta-add-surface` + +1. Read **`manifest.json`**: confirm **`platform-version`** `3.0` and **`metaConfig.framework`** `"react"`. +2. Choose **placement** (e.g. `ticket_sidebar`) and the correct **module** (see **`references/react-meta-quick-reference.md`** or **fw-app-dev** `rules/platform3-modules-locations.mdc`). +3. Add **`location`** entry with **`url`** (e.g. `ticketSidebar.html`) and **`icon`** path that **exists** on disk (often `styles/images/icon.svg`). +4. Create **`app/`** HTML: + - `` in `` or early ``. + - Mount node (e.g. `
`). + - `` for a **dedicated** entry (not the full-page bundle). +5. Add **JSX entry** component: wait for **`window.app.initialized()`**, set **`window.client`**, then render. +6. Run **`fdk validate`** and fix issues. + +If the user is unsure which module/placement: ask product (Freshdesk vs Freshservice) and surface name. diff --git a/skills/fw-react-app/commands/react-meta-scaffold.md b/skills/fw-react-app/commands/react-meta-scaffold.md new file mode 100644 index 0000000..c54a236 --- /dev/null +++ b/skills/fw-react-app/commands/react-meta-scaffold.md @@ -0,0 +1,20 @@ +--- +name: react-meta-scaffold +description: Scaffold a new Freshworks React Meta app with fdk create and react-starter-template. Use when starting a greenfield React UI app or reproducing the official template layout. +globs: ["**/manifest.json"] +always: false +--- + +# React Meta scaffold + +**Usage:** `/react-meta-scaffold` + +Follow **SKILL.md** in this skill end-to-end. Summary: + +1. Confirm **Node 24.x** + **FDK 10.x** (otherwise **fw-setup** first). +2. Create an **empty** app directory; run **`fdk create`** → **`react-starter-template`**. +3. Run **`npm install`** if needed. +4. Ensure **`manifest.json`** includes **`metaConfig.framework`: `"react"`** (template usually does). +5. Run **`fdk validate`**; fix until **0 platform + 0 lint** per **fw-app-dev** (up to 6 iterations). + +Report the app path, validation result, and next steps: **`fdk run`**, product URL with **`?dev=true`**, and **`http://localhost:10001/system_settings`**. diff --git a/skills/fw-react-app/commands/react-meta-validate.md b/skills/fw-react-app/commands/react-meta-validate.md new file mode 100644 index 0000000..ea8fb95 --- /dev/null +++ b/skills/fw-react-app/commands/react-meta-validate.md @@ -0,0 +1,18 @@ +--- +name: react-meta-validate +description: Run fdk validate on a React Meta app with auto-fix discipline (platform + lint to zero). +globs: ["**/manifest.json"] +always: false +--- + +# React Meta validate + +**Usage:** `/react-meta-validate` + +1. Locate app root (folder with **`manifest.json`**). If multiple, ask which app. +2. Confirm **`metaConfig.framework`** is **`react`**; if missing, this may be the wrong workflow—surface **fw-react-app** SKILL.md or **fw-migrate-to-react-app**. +3. Apply **fw-app-dev** *Manifest + toolchain gate* before validation (**Node 24** + **FDK 10**, Platform **3.0**, **engines** aligned). +4. From app root run **`fdk validate`**. Capture output. +5. Fix **platform** and **lint** errors; re-run up to **6** iterations or until **0 / 0**, matching **fw-app-dev** rules (**complexity**, **async/await**, **unused params**, **requests** manifest sync, **icon** path, etc.). + +Output a short verdict: pass/fail and remaining issues if any. diff --git a/skills/fw-react-app/references/react-meta-quick-reference.md b/skills/fw-react-app/references/react-meta-quick-reference.md new file mode 100644 index 0000000..0f004ab --- /dev/null +++ b/skills/fw-react-app/references/react-meta-quick-reference.md @@ -0,0 +1,48 @@ +# React Meta — quick reference + +## Location module map (common) + +| Surface | Typical module key | +|--------|---------------------| +| `full_page_app` | `modules.common.location` | +| `cti_global_sidebar` | `modules.common.location` | +| `ticket_sidebar` (Freshdesk) | `modules.support_ticket.location` | +| `ticket_top_navigation`, `ticket_background` | `modules.support_ticket.location` | +| `contact_sidebar` | `modules.support_contact.location` | +| `company_background` | `modules.support_company.location` | +| `ticket_sidebar` (Freshservice) | `modules.service_ticket.location` | + +Always confirm against current product docs if unsure. + +## Custom iparams React contract + +The platform calls these on **`window`** (assign inside your React tree): + +1. **`window.getConfigs(configs)`** — populate form state from saved configs. +2. **`window.postConfigs()`** — return a plain object of values to persist on Save. +3. **`window.validate()`** — return boolean **`true`** to allow save, **`false`** to block; runs before `postConfigs`. + +Bootstrap still waits on **`window.app.initialized()`** before mounting the form UI. + +## Hook patterns (sketches) + +- **`useFreshworksData(key)`** — wraps `window.client.data.get(key)` with loading/error state. +- **`useInvokeTemplate(name)`** — wraps `client.request.invokeTemplate` + JSON parse. +- **`useServerMethod(name)`** — wraps `client.request.invoke`. +- **`AppLifecycleProvider`** — subscribes to `app.activated` / `app.deactivated` for placeholder refreshes. + +Implement in project code as needed; keep complexity ≤ 7 per function for server lint rules. + +## Client APIs (after init) + +Illustrative list: `request.invokeTemplate`, `request.invoke`, `data.get`, `db.*`, `iparams.get`, `interface.trigger`, `instance.*`, `events.on/off`. + +Data keys depend on surface (e.g. `ticket`, `contact`, `loggedInUser`, `domainName`, …). + +## Official docs (indices) + +- [App SDK overview](https://developers.freshworks.com/docs/app-sdk/v3.0/) +- [Placeholders](https://developers.freshworks.com/docs/app-sdk/v3.0/freshdesk/front-end-apps/placeholders/) +- [Request templates](https://developers.freshworks.com/docs/app-sdk/v3.0/freshdesk/front-end-apps/requests/) +- [SMI](https://developers.freshworks.com/docs/app-sdk/v3.0/freshdesk/serverless-apps/server-method-invocation/) +- [Installation parameters](https://developers.freshworks.com/docs/app-sdk/v3.0/freshdesk/installation-parameters/) diff --git a/skills/fw-react-app/rules/react-meta-bootstrap.mdc b/skills/fw-react-app/rules/react-meta-bootstrap.mdc new file mode 100644 index 0000000..ba1a962 --- /dev/null +++ b/skills/fw-react-app/rules/react-meta-bootstrap.mdc @@ -0,0 +1,44 @@ +--- +description: React Meta HTML shells, SDK bootstrap, and per-surface JSX entries for Freshworks Platform 3.0. +globs: ["**/app/**/*.html", "**/app/**/*.jsx", "**/config/iparams.html"] +alwaysApply: false +--- + +# React Meta frontend rules + +## Mandatory App SDK script + +Every HTML entry (including **`config/iparams.html`**) must include: + +```html + +``` + +Triple braces. Without it, **`window.app`** is undefined. + +## Bootstrap order + +1. Load **`{{{appclient}}}`**. +2. Call **`window.app.initialized()`** and wait for the **client** before platform API usage or primary UI that depends on the client. +3. Common pattern: assign **`window.client = client`** after init. + +## One surface = one HTML + one JSX entry + +- **`manifest`** **`location.url`** points to **`app/.html`**. +- That HTML mounts **one** React tree via **`type="module"`** pointing at a **surface-specific** JSX file. +- Do **not** load the full-page router bundle in **`ticket_sidebar`** or other compact surfaces. + +## metaConfig + +```json +"metaConfig": { "framework": "react" } +``` + +## Routing + +- **Client-side routing** (e.g. React Router): **only** in **`full_page_app`** (or equivalent full-iframe surface). +- Other surfaces: single-purpose UI. + +## Delegation + +**Request templates**, **OAuth**, **SMI**, **manifest** structure, **`fdk validate`** autofix, and **server** lint: follow **fw-app-dev** (`freshworks-platform3`, `validation-workflow`, etc.). This file is **not** a substitute for Platform 3.0 rules. diff --git a/skills/fw-react-app/rules/react-meta-orchestration.mdc b/skills/fw-react-app/rules/react-meta-orchestration.mdc new file mode 100644 index 0000000..f7d56ad --- /dev/null +++ b/skills/fw-react-app/rules/react-meta-orchestration.mdc @@ -0,0 +1,21 @@ +--- +description: Orchestration—use fw-app-dev for Platform 3.0 and fw-setup for toolchain when working with React Meta. +globs: ["**/manifest.json", "**/server/**/*.js", "**/config/**"] +alwaysApply: false +--- + +# React Meta orchestration + +## Toolchain + +- **Node 24.x** + **FDK 10.x** before **`fdk run`** / **`fdk validate`** / **`fdk pack`**. +- Installing or upgrading **Node/FDK**: **fw-setup** skill—not this skill. + +## Platform semantics + +- **manifest**, **modules**, **requests.json ↔ manifest sync**, **OAuth**, **`renderData`**, **events**, **complexity ≤ 7**, **async/await**, **unused parameters**: **fw-app-dev** (or **app-dev** skill) is authoritative. +- **React Meta** skills only add: **metaConfig**, **JSX/bundler** conventions, **HTML shells**, **migration** from vanilla UI. + +## Validation + +- An app is not "done" until **`fdk validate`**: **0 platform + 0 lint** (same bar as **fw-app-dev**).