grafana / grafana/faro-javascript-bundler-plugins

Reduce hard dependency on curl for sourcemap uploads

Open
#543 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
10
Forks
10
Avg merge
2h 34m
Merged PRs (30d)
5

Description

## Problem

`faro-cli` (and the bundler plugins that wrap it) shell out to `curl` via `execSync` to POST sourcemaps to the Faro API — see [`packages/faro-cli/src/index.ts:142`](https://github.com/grafana/faro-javascript-bundler-plugins/blob/main/packages/faro-cli/src/index.ts#L142). If `curl` is not on the user's `PATH`, uploads fail with a cryptic shell error.

Environments where this commonly bites:
- Older Windows (curl.exe ships with Windows 10 1803+, but earlier versions and some stripped images don't have it)
- Minimal / Alpine / distroless Docker images used in CI
- Some serverless / build-sandbox environments

## Options to consider

These aren't all mutually exclusive — we could mix and match.

1. **Replace the upload path with Node's built-in `https` / `fetch`.** Removes the dependency entirely. Would need to preserve `--proxy` / `--proxy-user` (e.g., via `https-proxy-agent`) and the `HTTPS_PROXY` / `NO_PROXY` env-var behavior that curl provides for free.

2. **Add an opt-in flag (e.g., `--use-node-http`).** Keep curl as default, let users without curl opt in. Smallest behavior change, but adds a config surface and requires users to know about the flag before they hit the failure.

3. **Auto-detect curl and fall back to Node HTTP.** Best UX (no flags, no surprises), but two upload paths to maintain.

4. **Fail fast with a clear error when curl is missing.** Orthogonal to the above — even if we keep curl, a startup `curl --version` probe could produce an actionable error (\"curl not found on PATH; install curl or use ...\") instead of a generic `execSync` failure.

5. **Postinstall warning.** Emit a warning at `npm install` time if `curl` isn't on `PATH`, so users learn about the requirement before their first build fails.

6. **Improve documentation.** Explicitly call out the curl prerequisite in the README, list known environments where curl isn't shipped, and link to install instructions. Cheapest option; doesn't help users who hit the error before reading the docs.

## Note

The `generateCurlCommand` function (which prints a curl command for users to copy/paste) is a separate use case from the runtime upload — it should remain as-is regardless of which option we choose for the upload path.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.