Documentation Grafana Cloud Monitor applications Frontend Observability Source map uploads Upload with the CLI

Upload source maps with the CLI

Use the Faro CLI to upload source maps separately from your build process, particularly useful for CI/CD pipelines.

Install the CLI

Install the Faro CLI tool.

Bash Copy

npm install --save-dev @grafana/faro-cli

or

Bash Copy

yarn add --dev @grafana/faro-cli

Upload source maps

Upload source maps using the CLI

Bash Copy

npx faro-cli upload \
  --endpoint "$your-faro-sourcemap-api-url" \
  --app-id "$your-app-id" \
  --api-key "$your-api-key" \
  --stack-id "$your-stack-id" \
  --bundle-id env \
  --app-name "$your-app-name" \
  --output-path "./dist" \
  --verbose

File size handling

The CLI handles large files automatically within the Faro API’s 30MB per file limit:

• Checks file sizes and warns about oversized files
• Streams files and creates upload batches as they approach size limits
• Supports tuning with --max-upload-size while respecting backend limits

Compression options

Reduce bandwidth usage with these compression strategies:

Compress tarred contents for multiple files:

Bash Copy

npx faro-cli upload \
  --endpoint "$your-faro-sourcemap-api-url" \
  --app-id "$your-app-id" \
  --api-key "$your-api-key" \
  --stack-id "$your-stack-id" \
  --bundle-id "$your-bundle-id" \
  --output-path "./dist" \
  --patterns "*.map" \
  --gzip-contents \
  --verbose

Compress HTTP payload for large individual files:

Bash Copy

npx faro-cli upload \
  --endpoint "$your-faro-sourcemap-api-url" \
  --app-id "$your-app-id" \
  --api-key "$your-api-key" \
  --stack-id "$your-stack-id" \
  --bundle-id "$your-bundle-id" \
  --output-path "./dist" \
  --patterns "*.map" \
  --gzip-payload \
  --verbose

Combine both compression methods for maximum efficiency:

Bash Copy

npx faro-cli upload \
  --endpoint "$your-faro-sourcemap-api-url" \
  --app-id "$your-app-id" \
  --api-key "$your-api-key" \
  --stack-id "$your-stack-id" \
  --bundle-id "$your-bundle-id" \
  --output-path "./dist" \
  --patterns "*.map" \
  --gzip-contents \
  --gzip-payload \
  --verbose

Inject bundle ID into JavaScript files

Add bundle IDs to built JavaScript files:

Bash Copy

npx faro-cli inject-bundle-id \
  --bundle-id "$your-bundle-id" \
  --app-name "$your-app-name" \
  --files "dist/**/*.js" \
  --verbose

Test the injection without making changes:

Bash Copy

npx faro-cli inject-bundle-id \
  --bundle-id "$your-bundle-id" \
  --app-name "$your-app-name" \
  --files "dist/**/*.js" \
  --dry-run \
  --verbose

Generate cURL commands

Create ready-to-run cURL commands for source map uploads:

Bash Copy

npx faro-cli curl \
  --endpoint "$your-faro-sourcemap-api-url" \
  --app-id "$your-app-id" \
  --api-key "$your-api-key" \
  --stack-id "$your-stack-id" \
  --bundle-id "$your-bundle-id" \
  --file "./dist/main.js.map"

Upload command options

Required options:

• -e, --endpoint <url> - Faro API endpoint URL from Frontend Observability > Settings > Source Maps > Configure source map uploads
• -a, --app-id <id> - Faro application ID
• -k, --api-key <key> - Faro API key
• -s, --stack-id <id> - Faro stack ID from Frontend Observability > Settings > Source Maps > Configure source map uploads
• -b, --bundle-id <id> - Bundle ID. Set to env to read from environment variable
• -o, --output-path <path> - Path to directory containing source maps

Optional options:

• -n, --app-name <name> - Application name for finding bundle ID in environment variables
• -k, --keep-sourcemaps - Keep source maps after uploading. Default: false
• -g, --gzip-contents - Compress source maps as tarball before uploading. Default: false
• -z, --gzip-payload - Gzip HTTP payload for smaller uploads. Default: false
• -v, --verbose - Enable detailed logging. Default: false
• -r, --recursive - Recursively search subdirectories for source maps. Default: false
• -x, --max-upload-size <size> - Maximum upload size in bytes. Default: 30MB

cURL command options

Required options:

• -e, --endpoint <url> - Faro API endpoint URL from Frontend Observability > Settings > Source Maps > Configure source map uploads
• -a, --app-id <id> - Faro application ID
• -k, --api-key <key> - Faro API key
• -s, --stack-id <id> - Faro stack ID from Frontend Observability > Settings > Source Maps > Configure source map uploads
• -b, --bundle-id <id> - Bundle ID. Set to env to read from environment variable
• -f, --file <path> - Path to source map file

Optional options:

• -n, --app-name <name> - Application name for finding bundle ID in environment variables
• -t, --content-type <type> - Content type for upload. Default: application/json
• -z, --gzip-payload - Generate command that compresses payload. Default: false

After uploading, verify your source maps in Frontend Observability by navigating to Settings > Source Maps. For troubleshooting common issues, refer to Troubleshooting.