fdk-react-migrate

FDK React Migrate — Vanilla JS → React Meta

Usage: /fdk-react-migrate

Converts a Platform 3.0 vanilla JS app (Crayons + app/scripts/app.js) to the Meta framework with React + DEW.

Not for Platform 2.x: If platform-version is not "3.0", run /fdk-migrate first, then return to this command.

Step 1: Locate app and verify platform version

1. Find manifest.json in the workspace.
2. If multiple apps → ask user which to migrate.
3. Read platform-version:
   • Not "3.0" → STOP → /fdk-migrate first.
   • metaConfig.framework already "react" → inform user; offer /fdk-fix only.

Step 2: Prerequisites

Follow SKILL.md toolchain gate: Node 24.x + FDK 10.x (10.1.0+ for Meta).

Step 3: Inventory existing app

Document before changing files:

• Locations and HTML shells (app/index.html, multi-placeholder names)
• Server handlers in server/server.js — keep all needed SMI/events
• config/requests.json, oauth_config.json, iparams.json
• Frontend logic in app/scripts/app.js — map to React components

See references/react-meta/js-to-react-migration-checklist.md.

Step 4: Add Meta manifest + package

1. Add to manifest.json:

   "metaConfig": {
     "framework": "react",
     "packageManager": "npm"
   }
   

2. Raise engines.fdk to 10.1.0 minimum if lower.
3. Create/update package.json:
   • react, react-dom (^19)
   • @freshworks/dew-components, @freshworks/dew-styles
   • react-router-dom
   • Preserve other legitimate deps (axios manifest-pinned, etc.)

Step 5: Restructure frontend

1. Keep app/index.html at app root (update to #root shell; retain {{{appclient}}} if SMI/Data/Request used).
2. Remove Crayons CDN scripts from HTML.
3. Create app/index.jsx entry importing DEW styles + App component.
4. Move UI logic from app/scripts/app.js into app/components/ as React components.
5. Add React Router with path="*" home route and /app/... feature routes — specific /app/... routes before the path="*" catch-all.
6. Remap all navigation paths (CRITICAL — UI breaks if skipped):
   • Grep app/ for old paths: href=, window.location, navigate(, <Link to=, click handlers that change views.
   • Map each vanilla page/view to a React Router route under /app/... (e.g. /demo → /app/demo).
   • Add a matching <Route path="/app/..."> for every feature page; update every Link / navigate() to the new path.
   • Do not leave stale vanilla-only paths — fdk validate can pass while the UI stays blank or routes fail.
7. Multi-location HTML: For each manifest location.url (e.g. index.html, ticketSidebar.html), ensure the file exists at app/ root (not under components/) with #root and {{{appclient}}} when SMI/Data/Request is used.
8. Replace Crayons / plain HTML with DEW components from @freshworks/dew-components + @freshworks/dew-styles.
9. Delete or archive app/scripts/app.js after logic is ported (Meta bundles via Vite).
10. Update icon path in manifest if moving icon to app/icon.svg.