sf webapp dev command @W-20242483@

[deepu-mungamuri94]

Work Item: @W-20242483@

This PR implements the sf webapp dev command, a local development proxy server that enables seamless webapp development with Salesforce authentication and dev server integration.

🎯 What This Does

Provides developers with a local proxy server that:

• Handles Authentication: Automatically injects Salesforce CLI tokens into requests
• Routes Traffic: Intelligently routes requests between Salesforce APIs and local dev servers
• Manages Dev Servers: Spawns, monitors, and manages local dev server lifecycle (Vite, CRA, Next.js)
• Provides Great UX: Shows beautiful error pages, auto-detects server URLs, and handles failures gracefully

✨ Key Features

For Developers:

• Single command to start authenticated development: sf webapp dev --name myapp --target-org myorg --open
• Automatic browser launch with working authentication
• Support for multiple dev server types (Vite, Create React App, Next.js, custom servers)
• Beautiful HTML error pages when dev server is down (auto-refresh every 5s)
• Real-time configuration updates when webapp.json changes

For Webapp Architecture:

• WebSocket support for Hot Module Replacement (HMR)
• Code Builder environment detection and special URI handling
• Configurable proxy port with conflict detection
• Graceful shutdown and cleanup on Ctrl+C

🏗️ Architecture

Built with modular components:

• ProxyServer: Core HTTP proxy with auth injection and health monitoring
• DevServerManager: Spawns and monitors dev servers with automatic URL detection
• AuthManager: Manages Salesforce authentication and token refresh
• RequestRouter: Intelligent routing between Salesforce and dev server
• ManifestWatcher: Loads and watches webapp.json for changes
• ErrorHandler: Standardized, user-friendly error messages

📝 Usage Example

# Start proxy with automatic dev server management
sf webapp dev --name myapp --target-org myorg --open

# Or use existing dev server
sf webapp dev --name myapp --target-org myorg --url http://localhost:5173 --open

🔍 What to Review

1. Core proxy functionality (src/proxy/ProxyServer.ts, src/proxy/RequestRouter.ts)
2. Dev server management (src/server/DevServerManager.ts) - especially URL detection with ANSI stripping
3. Error handling and UX (src/error/ErrorHandler.ts, src/templates/error-page.html)
4. Configuration management (src/config/ManifestWatcher.ts)
5. Command integration (src/commands/webapp/dev.ts)

🚀 Technical Highlights

• ANSI Color Code Stripping: Robust URL detection even when dev servers output colored text
• Line-by-Line Processing: Handles chunked stdout from spawned processes
• Organized URL Patterns: Easy to add support for new dev server types
• Unicode Support: Properly detects Vite's Unicode arrow character (➜)
• HTML Error Pages: Beautiful, informative error pages with auto-refresh
• Health Monitoring: Periodic checks with automatic status updates

---

[salesforce-cla]

Thanks for the contribution! Unfortunately we can't verify the commit author(s): dmungamuri <d***@s***.com>. One possible solution is to add that email to your GitHub account. Alternatively you can change your commits to another email and force push the change. After getting your commits associated with your GitHub account, refresh the status of this Pull Request.

[nrkruk]

why do we need this?

[deepu-mungamuri94]

This is outdated after review comments. We are now only copying error html from templates folder.

Why lib/templates/ is needed

TypeScript compiler (tsc) only converts .ts → .js files. It does NOT copy .html, .json, or other non-TS files.

The Problem

At runtime, ErrorPageRenderer.js loads the template relative to itself:

const currentDir = dirname(fileURLToPath(import.meta.url));
const templatePath = join(currentDir, 'error-page.html');Since the compiled code runs from lib/templates/, it looks for templates in lib/templates/, not src/templates/.

Additionally

The src/ folder is not published to npm (only lib/ is in the files array). When users install the plugin, they only get lib/. Templates must be there for the plugin to work.

Solution

The copy-resources wireit task copies src/templates/*.html → lib/templates/ during build.

[nrkruk]

I'm not able to run this locally with sf plugins link . How are you testing this?

[deepu-mungamuri94]

I have used the vibe-coding-starter & my workspace orgfarm org in vscode for validation

Build & Link Plugin

Build

cd /path/to/plugin-webapp
yarn build

Link to SF CLI

sf plugins link .

Verify

sf plugins

Setup webapp.json

Create webapp.json in your project(vibe-coding-starter) root:

{
  "name": "myWebApp",
  "label": "My Web App",
  "version": "1.0.0",
  "outputDir": "dist",
  "dev": {
    "url": "http://localhost:5173"
  }
}

Or with a command to start dev server:

{
  "name": "myWebApp",
  "label": "My Web App", 
  "version": "1.0.0",
  "outputDir": "dist",
  "dev": {
    "command": "cd static-app && npm run dev"
  }
}

Usage

cd /path/to/vibe-coding-starter
sf webapp dev --name myWebApp --open

[deepu-mungamuri94]

https://github.com/salesforcecli/plugin-webapp/blob/sf-webapp-dev-command/SF_WEBAPP_DEV_GUIDE.md - This best depicts the flow and implementation.

[nrkruk]

Not confident this will be the final schema so I don't know that we need to be validating the webapp.json at this point.

[deepu-mungamuri94]

the schema file is no longer here. I'm using the similar approach as that of the packages/webapps.

[nrkruk]

On proxy server startup, this error occurs:

[ErrorPageRenderer] Failed to load template from /Users/nkruk/git/cli/plugin-webapp/lib/templates/error-page.html: Error: ENOENT: no such file or directory, open '/Users/nkruk/git/cli/plugin-webapp/lib/templates/error-page.html'
at readFileSync (node:fs:441:20)
at new ErrorPageRenderer (file:///Users/nkruk/git/cli/plugin-webapp/lib/templates/ErrorPageRenderer.js:32:29)
at new ProxyServer (file:///Users/nkruk/git/cli/plugin-webapp/lib/proxy/ProxyServer.js:51:34)
at WebappDev.run (file:///Users/nkruk/git/cli/plugin-webapp/lib/commands/webapp/dev.js:207:32)
at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
at async WebappDev._run (/Users/nkruk/git/cli/plugin-webapp/node_modules/@oclif/core/lib/command.js:182:22)
at async Config.runCommand (/Users/nkruk/.local/share/sf/client/2.108.6-399bc9e/node_modules/@oclif/core/lib/config/config.js:456:25)
at async run (/Users/nkruk/.local/share/sf/client/2.108.6-399bc9e/node_modules/@oclif/core/lib/main.js:97:16)
at async file:///Users/nkruk/.local/share/sf/client/2.108.6-399bc9e/bin/run.js:15:1 {
errno: -2,
code: 'ENOENT',
syscall: 'open',
path: '/Users/nkruk/git/cli/plugin-webapp/lib/templates/error-page.html'
}

[deepu-mungamuri94]

This issue was fixed, pls retry. The copy-resources task is now included in the build dependencies, which copies src/templates/error-page.html to lib/templates/.
npm run build

Running only npm run compile won't copy the HTML templates - use npm run build for a complete build.

[nrkruk]

Might still need more work when runnning from installed CLI vs linked locally. We can address in followup PR

[nrkruk]

Is it possible this error page could just be part of @salesforce/webapp proxy package?

[nrkruk]

not a high priority though, we can look at in follow up PR

[nrkruk]

TODO: need more thorough nut tests.

• Need to have an SFDX test project with multiple webapps
• Some of those are invalid configs
• 1 -> launches the devserver
• 2 -> specify the URL
• 3 -> dev server fails to launch
• 4 -> dev server specified with URL isnt running
• 5 -> webapp.json is misconfigured missing
• 6 -> Launching command from different directories (root vs webapp folder)

[nrkruk]

Also a test to verify we properly forward the auth header and that matches the SFCLI token for the org

[nrkruk]

Any other tests to check manifest changes -> change manifest and verify it works with proxy

[nrkruk]

Can we use Logger.childFromRoot() (which is not an async function) and initialize the logger in constructor?

[deepu-mungamuri94]

Done

[nrkruk]

Is this still used at all?

[deepu-mungamuri94]

Yes, It is used.
How to validate ? When the preview opens.. try to stop the dev server.

errorPageRenderer renders error pages when the dev server fails or isn't running, and workspaceScript is displayed in those error pages to help users run the correct command.

[nrkruk]

We should remove this

[deepu-mungamuri94]

We don't need the schemas and oclif.lock files. but we still need the oclif.manifest.json
`Without it, the CLI has to dynamically discover commands at runtime:

• Scan the commands/ directory

• Load each TypeScript/JavaScript file

• Parse the command class to extract flags, args, descriptions

• Build the command tree

With the manifest, all that metadata is pre-computed:

• Read one JSON file

• Instantly know all available commands and their structure`

[deepu-mungamuri94]

Removed /npm-shrinkwrap.json and /oclif.lock from the files array

[deepu-mungamuri94]

Took reference from here and hence those were added : https://github.com/salesforcecli/plugin-lightning-dev/blob/main/package.json#L53

[nrkruk]

ok thats fine, I just want to be sure we are consistent with other plugins. We can leave these in

[nrkruk]

Added back. Turns out this was just an issue with our dependencies being out of date

[nrkruk]

Added volta config to ensure we are building locally with consistent tooling

[nrkruk]

Our build issues we were hitting were due to out of date dependencies / hence the issues with oclif manifest not linking properly with latest CLI. These updates resolve the issue.

[nrkruk]

Should be good enough for M2. We can address any code complexity / nut tests / other bugs that arise as part of M3