skills: fw-new-react-app and fw-react-migrate by rohankokkula · Pull Request #24 · freshworks-developers/fw-dev-tools

rohankokkula · 2026-06-15T11:44:19Z

Splits React Meta guidance into two public fw-dev-tools skills and registers them in the umbrella marketplace.

fw-new-react-app — greenfield React Meta apps (fdk create, Crayons/Tailwind/Router, multi-surface placeholders, CTI, OAuth sidebar, hybrid SMI)
fw-react-migrate — migrate existing PF 3.0 vanilla or pre-meta frontends to React Meta while preserving server, OAuth, and requests.json
Also updates AGENTS.md, README.md, CONTRIBUTING.md, and Cursor/Claude/Codex marketplace manifests.

…or React Meta apps - Introduced README.md and SKILL.md to outline the purpose and usage of the fw-react-app skill for Freshworks Platform 3.0. - Added command documentation for `/react-meta-scaffold`, `/react-meta-add-surface`, and `/react-meta-validate` to facilitate app creation and validation. - Included plugin manifests for Cursor and Claude, detailing commands and descriptions. - Established rules for React Meta HTML shells and orchestration, ensuring compliance with platform standards. - Created quick reference and agent documentation to assist developers in implementing React Meta features effectively.

- Added documentation for the new skills: **fw-new-react-app** for creating greenfield React Meta apps and **fw-react-migrate** for migrating existing PF3 frontends to React Meta. - Updated AGENTS.md to include new skills and their functionalities. - Enhanced README.md to reflect the addition of new skills and their usage. - Updated contributing guidelines to include new skills in the development workflow. - Removed deprecated fw-react-app skill and its associated files to streamline the repository.

rapchic

Review — `fw-new-react-app` + `fw-react-migrate`

Scope: 62 files, +5479 lines. Splits the earlier monolithic fw-react-app draft into greenfield + migrate skills and registers both in marketplace manifests.

Summary

Two-skill split resolves the phantom migrate skill reference; marketplace + AGENTS.md wiring is present, and the pattern library is thorough.

Blockers before merge to current main:

fw-app-dev conflict — always-on vanilla gates (app/scripts/app.js, Crayons CDN, app/styles/images/icon.svg) still win; React skills delegate to fw-app-dev without an explicit override block.
Icon path inconsistency — validate autofix + generation order still create app/styles/images/icon.svg; react-starter-template uses app/public/icon.svg + manifest "icon": "icon.svg".
Branch staleness — PR predates installer/, tests/skill-eval, and shipped routing spec on main; npx @freshworks/fw-dev-tools install won't ship these skills until rebased and integrated.
Version/engine drift — new skills at 1.0.0 / fdk: 10.0.0 while main siblings use 1.2.0 / fdk: 10.0.1.

Findings by priority

Priority	Issue
P0	No `fw-app-dev override (React Meta)` preamble — agents will corrupt scaffolds during validate/fix
P0	Icon autofix table + quick-reference table contradict react-starter-template layout
P1	Document `fdk create --template react-starter-template --app-dir <dir>`
P1	All React rules `alwaysApply: false` — fw-app-dev always wins
P1	`/fdk-review` typo in migrate gates (skill is fw-review)
P2	Rebase + update `installer/src/utils.js` `FW_SKILLS`, routing spec, static/eval tests
P2	`.meta.json` contract + skill-eval scenarios per `CONTRIBUTING.md`

Suggested next steps

Rebase on main and resolve installer/tests/spec gaps.
Add React Meta exception block at top of fw-new-react-app/SKILL.md (mirror fw-ai-actions-app pattern).
Fix icon paths in validate command, fw-new-react-app.md, and quick-reference.
Align versions/engines with main; add eval scenarios for scaffold + migrate flows.

rapchic · 2026-07-15T07:30:11Z

+**Scope:** **Greenfield** React Meta apps via `fdk create` → `react-starter-template`, or **add a surface** to an app that already has `metaConfig.framework: "react"`.
+
+**Does not:** migrate vanilla `app/scripts/*.js` → use **`fw-react-migrate`**. Does not install FDK/Node → **`fw-setup`**. Does not own OAuth/security/complex serverless → **`fw-app-dev`**.
+


🛠️ Refactor suggestion | P0 — fw-app-dev conflict

Skill defers OAuth/server/manifest to fw-app-dev, but does not override fw-app-dev's alwaysApply: true gates (app-building-blocking-gates, validation-workflow, freshworks-platform3).

Those rules still mandate:

app/scripts/app.js + app/styles/style.css

Crayons CDN script tags in HTML

app/styles/images/icon.svg

React Meta (react-starter-template) uses app/components/*.jsx, Vite, @freshworks/crayons/react, and app/public/icon.svg.

Add a blocking section at the top (see fw-ai-actions-app's fw-app-dev override):

## fw-app-dev override (React Meta active) IGNORE fw-app-dev file-tree gates for vanilla frontend. Use react-starter-template layout; never create app/scripts/app.js for React apps.

fw-app-dev autofix can corrupt React scaffolds when both skills load.

rapchic · 2026-07-15T07:30:11Z

+
+1. Classify features + surfaces from prompt.
+2. Create empty app folder (kebab-case).
+3. `fdk create` → **`react-starter-template`**.


📝 Nitpick | P1 — non-interactive scaffold

Step 3 shows interactive fdk create only. Document:

fdk create --template react-starter-template --app-dir <target-dir>

Agents in CI/automation will hang on interactive prompts without this.

rapchic · 2026-07-15T07:30:11Z

+## Engines (manifest example)
+
+```json
+"engines": { "node": "24.11.0", "fdk": "10.0.0" }


⚠️ Potential issue | P1 — engine pin drift

Example shows "fdk": "10.0.0". Current main fw-app-dev defaults to 10.0.1 + Node 24.11.0.

After rebase, align engines example and react-meta-dependencies.mdc with docs/engine-matrix.md on main to avoid agents pinning an older FDK than sibling skills require.

rapchic · 2026-07-15T07:30:11Z

+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Icon '...icon.svg' not found` | File missing on disk | Create `app/styles/images/icon.svg` with a 64×64 SVG; ensure `icon` path in manifest matches the disk path |


⚠️ Potential issue | P0 — wrong icon autofix

Autofix says: Create app/styles/images/icon.svg.

react-starter-template ships app/public/icon.svg with manifest "icon": "icon.svg".

This table will actively break greenfield scaffolds when fw-app-dev and this command both fire. Fix:

Resolve manifest icon path on disk — for template apps use app/public/icon.svg, not fw-app-dev vanilla path.

rapchic · 2026-07-15T07:30:11Z

+
+1. `manifest.json` (multi-module if needed; never empty `requests`/`functions`/`events` blocks).
+2. `package.json` (base deps from the template + only the feature-flag adds from [../rules/react-meta-dependencies.mdc](../rules/react-meta-dependencies.mdc)).
+3. `app/styles/images/icon.svg` (default 64×64 SVG, see SKILL.md or fw-app-dev rules — required).


⚠️ Potential issue | P0 — wrong file in generation order

Step 6 mandates app/styles/images/icon.svg (fw-app-dev vanilla tree).

Greenfield React Meta from react-starter-template already has app/public/icon.svg. Creating the vanilla path duplicates/conflicts with template layout and triggers platform errors on add-surface (nested scaffold copies).

Change to: verify existing template icon; only create if manifest path is missing on disk.

rapchic · 2026-07-15T07:30:12Z


 **Commands:** none. **Rules:** none. Playbooks in `SKILL.md`, `references/`, and `subagents/`; MCP in repo root **`.mcp.json`**.

+### fw-new-react-app — `skills/fw-new-react-app/`


📝 Nitpick | P2 — repo maintenance checklist

New skill inventory is documented — good. Per CONTRIBUTING.md / AGENTS.md maintenance table, also need on merge:

skills/shared/.meta.template.json blocks for both skills (if they write metrics)

tests/skill-eval.test.js scenarios (scaffold, add-surface, migrate light/full path)

tests/TESTING.md scenario table rows

Behavioral eval attach to PR (tests/eval-report.html)

None present on this branch yet (likely rebase gap).

rapchic · 2026-07-15T07:30:12Z

+
+## After migration
+
+- **fw-new-react-app** **`/fw-new-react-app-validate`** or **fw-app-dev** **`/fdk-review`** for hard validation passes.


⚠️ Potential issue | P1 — wrong command name

References fw-app-dev /fdk-review for hard validation passes.

There is no /fdk-review slash command in this repo — structured review is fw-review skill (no slash commands; pipeline in SKILL.md).

Change to: fw-review (mandatory before fw-publish) or /fw-new-react-app-validate for toolchain validation only.

rapchic · 2026-07-15T07:30:12Z

+6. **DOM → React** — state/hooks; extract pure logic to `app/utils/` + tests ([utils-extraction-and-tests.md](references/patterns/utils-extraction-and-tests.md)).
+7. **Init gate** — `app.initialized()` on every entry; sidebar: `instance.resize` + `app.activated`.
+8. **Custom iparams** — React under `config/assets/components/` if applicable.
+9. **Cleanup** — delete `app/scripts/*.js` **only after** `fdk validate` 0/0.


✅ Good pattern | P1 note

Step 9 — delete app/scripts/*.js only after fdk validate 0/0 — excellent guardrail for migrations.

Consider cross-linking this in fw-new-react-app-validate.md as a do-not for migrate-in-progress apps (autofix might recreate scripts if fw-app-dev wins).

rapchic · 2026-07-15T07:30:12Z

+| [**fw-publish**](skills/fw-publish/) | Upload and publish your app to the Freshworks Marketplace | Core + umbrella marketplace |
+
+> [!NOTE]
+> **Distribution status:** umbrella marketplace manifests include the core seven skills (setup, app-dev, ai-actions, review, publish, **fw-new-react-app**, **fw-react-migrate**).


🛠️ Refactor suggestion | P2 — distribution completeness

Note says umbrella marketplace includes seven core skills — accurate for Cursor/Claude plugin install from repo.

Missing for end-developer npx @freshworks/fw-dev-tools install path:

installer/ FW_SKILLS + routing spec update

Rebase onto current main (this branch predates installer/tests folders)

Suggest: "Requires rebase + installer integration before npm install distribution."

rapchic · 2026-07-15T07:30:12Z

@@ -0,0 +1,14 @@
+# Agent: React Meta UI review (optional)


💡 Suggestion | P2 — fw-review integration

Optional review agent covers React UI structure well, but is not wired into fw-review scripts/*.js pipeline.

Consider adding deterministic checks: metaConfig.framework === 'react', {{{appclient}}} on all shells, no nested duplicate scaffolds, HashRouter-only-in-full-page — or document this agent as pre-fw-review only.

rohankokkula added 2 commits May 6, 2026 12:45

rapchic reviewed Jul 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

skills: fw-new-react-app and fw-react-migrate#24

skills: fw-new-react-app and fw-react-migrate#24
rohankokkula wants to merge 2 commits into
mainfrom
fw-react-new+migrate

rohankokkula commented Jun 15, 2026

Uh oh!

rapchic left a comment •

edited

Loading

Uh oh!

rapchic Jul 15, 2026 •

edited

Loading

Uh oh!

rapchic Jul 15, 2026 •

edited

Loading

Uh oh!

rapchic Jul 15, 2026

Uh oh!

rapchic Jul 15, 2026 •

edited

Loading

Uh oh!

rapchic Jul 15, 2026

Uh oh!

rapchic Jul 15, 2026

Uh oh!

rapchic Jul 15, 2026

Uh oh!

rapchic Jul 15, 2026

Uh oh!

rapchic Jul 15, 2026

Uh oh!

rapchic Jul 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		Scope: Greenfield React Meta apps via `fdk create` → `react-starter-template`, or add a surface to an app that already has `metaConfig.framework: "react"`.

		Does not: migrate vanilla `app/scripts/.js` → use `fw-react-migrate`. Does not install FDK/Node → `fw-setup`. Does not own OAuth/security/complex serverless → `fw-app-dev`*.


		Commands: none. Rules: none. Playbooks in `SKILL.md`, `references/`, and `subagents/`; MCP in repo root `.mcp.json`.

		### fw-new-react-app — `skills/fw-new-react-app/`


		## After migration

		- fw-new-react-app `/fw-new-react-app-validate` or fw-app-dev `/fdk-review` for hard validation passes.

Uh oh!

Conversation

rohankokkula commented Jun 15, 2026

Uh oh!

rapchic left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Review — fw-new-react-app + fw-react-migrate

Summary

Findings by priority

Suggested next steps

Uh oh!

rapchic Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rapchic Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rapchic Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

rapchic Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rapchic Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

rapchic Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

rapchic Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

rapchic Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

rapchic Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

rapchic Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rapchic left a comment •

edited

Loading

Review — `fw-new-react-app` + `fw-react-migrate`

rapchic Jul 15, 2026 •

edited

Loading

rapchic Jul 15, 2026 •

edited

Loading

rapchic Jul 15, 2026 •

edited

Loading