skill(fw-react-app): add initial documentation and command structure for React Meta apps #16
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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" | ||
| } | ||
| ] | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| { | ||
| "name": "fw-react-app", | ||
| "displayName": "Freshworks React Meta Apps", | ||
| "version": "1.0.0", | ||
|
Contributor
There was a problem hiding this comment. 📝 Nitpick | P2 — version drift Plugin |
||
| "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" | ||
| } | ||
| ] | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | | ||
| |------|------| | ||
|
Contributor
There was a problem hiding this comment. 🛠️ Refactor suggestion | P2 — not installable yet README describes usage but skill is not in
|
||
| | `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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
|
Contributor
There was a problem hiding this comment. 🛠️ Refactor suggestion | P0 — fw-app-dev conflict
React Meta uses Add a blocking preamble (like fw-ai-actions-app's fw-app-dev override): ## fw-app-dev override (React Meta)
When this skill is active, IGNORE fw-app-dev gates for:
- app/scripts/app.js, app/styles/style.css
- Crayons CDN script tags in HTML
- app/styles/images/icon.svg
Use react-starter-template layout instead.Without this, agents will corrupt scaffolds during validate/fix. |
||
|
|
||
| **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.). | ||
|
Contributor
There was a problem hiding this comment. 📝 Nitpick | P1 — CLI flag Document non-interactive scaffold: fdk create --template react-starter-template --app-dir <target-dir>Use |
||
| 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 | ||
| <script src="{{{appclient}}}"></script> | ||
| ``` | ||
|
|
||
| - Use **triple braces** `{{{appclient}}}` (Handlebars placeholder). Omitting it leaves `window.app` undefined and breaks all platform APIs. | ||
| - Typical shell: `<div id="root"></div>` plus a **module** entry, e.g. | ||
| `<script type="module" src="./components/MyEntry.jsx"></script>` | ||
| (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. | ||
|
Contributor
There was a problem hiding this comment.
Agents may copy the broken token literally. |
||
| - 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). | ||
|
Contributor
There was a problem hiding this comment. References
Template apps validate with 0 platform errors using those paths. Update all skill docs. |
||
|
|
||
| ## 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 | ||
|
Contributor
There was a problem hiding this comment. 📝 Nitpick | P2 — gist vs template References external gist for React Meta narrative while scaffold uses |
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| # Agent: React Meta UI review (optional) | ||
|
Contributor
There was a problem hiding this comment. 💡 Suggestion | P2 — fw-review integration Agent prompt is useful but not wired into |
||
|
|
||
| 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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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`). | ||
|
Contributor
There was a problem hiding this comment. Says icon path is often Use: check |
||
| 4. Create **`app/<url>`** HTML: | ||
| - `<script src="{{{appclient}}}"></script>` in `<head>` or early `<body>`. | ||
| - Mount node (e.g. `<div id="root"></div>`). | ||
| - `<script type="module" src="./components/...jsx"></script>` 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. | ||
|
Contributor
There was a problem hiding this comment. 🛠️ Refactor suggestion | P1 — in-place edits Add explicit rule:
Nested duplicate scaffolds cause platform errors. |
||
|
|
||
| If the user is unsure which module/placement: ask product (Freshdesk vs Freshservice) and surface name. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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). | ||
|
Contributor
There was a problem hiding this comment. 📝 Nitpick | P1 — overlap with /fdk-fix Post-scaffold step says run Add: "If validate fails on missing vanilla files, apply React Meta override from SKILL.md — do not invoke fw-app-dev file-tree fixes." |
||
|
|
||
| Report the app path, validation result, and next steps: **`fdk run`**, product URL with **`?dev=true`**, and **`http://localhost:10001/system_settings`**. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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**. | ||
|
Contributor
There was a problem hiding this comment. References Options:
Until fixed, validate command will route agents to a dead skill. |
||
| 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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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/) |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📝 Nitpick | P2 — version drift
Same as Cursor plugin — align
versionwithfw-app-dev/fw-setup(1.2.0) when adding marketplace entries.