@sonarly/sourcemap-uploader

Upload JavaScript sourcemaps to Sonarly for error deobfuscation in session replays.

Installation

npm install @sonarly/sourcemap-uploader --save-dev

Quick Start

CLI Usage

npx @sonarly/sourcemap-uploader \
  -k YOUR_API_KEY \
  -p YOUR_PROJECT_KEY \
  -m ./dist/assets \
  -u https://myapp.com/assets

Package.json Integration

Add to your package.json:

{
  "scripts": {
    "build": "vite build",
    "postbuild": "sourcemap-uploader -k $SONARLY_API_KEY -p $SONARLY_PROJECT_KEY -m dist/assets -u https://myapp.com/assets"
  }
}

Environment Variables

Instead of CLI arguments, you can use environment variables:

export SONARLY_API_KEY=sk_your_api_key
export SONARLY_PROJECT_KEY=your_project_key
export SONARLY_SERVER=https://sonarly.dev
export PUBLIC_URL=https://myapp.com/assets

npx @sonarly/sourcemap-uploader -m ./dist/assets

CLI Options

| Option | Env Variable | Description | |--------|--------------|-------------| | -k, --api-key | SONARLY_API_KEY | Your Sonarly API key (required) | | -p, --project-key | SONARLY_PROJECT_KEY | Your Sonarly project key (required) | | -s, --server | SONARLY_SERVER | Sonarly server URL (default: https://sonarly.dev) | | -m, --sourcemaps-dir | - | Directory containing .js and .map files (required) | | -u, --public-url | PUBLIC_URL | Public URL where JS files are served (required) | | -v, --verbose | - | Enable verbose logging | | -d, --delete | - | Delete .map files after upload |

Programmatic Usage

const uploadSourcemaps = require('@sonarly/sourcemap-uploader');
const fs = require('fs');

const sourcemaps = [
  {
    js_file_url: 'https://myapp.com/assets/main.abc123.js',
    body: JSON.parse(fs.readFileSync('./dist/assets/main.abc123.js.map', 'utf8'))
  },
  {
    js_file_url: 'https://myapp.com/assets/vendor.def456.js',
    body: JSON.parse(fs.readFileSync('./dist/assets/vendor.def456.js.map', 'utf8'))
  }
];

uploadSourcemaps(
  'sk_your_api_key',
  'your_project_key',
  sourcemaps,
  'https://sonarly.dev'
)
  .then((uploadedUrls) => {
    console.log('Uploaded:', uploadedUrls);
  })
  .catch((error) => {
    console.error('Failed:', error);
  });

Framework Examples

Vite

// vite.config.js
import { defineConfig } from 'vite';
import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

export default defineConfig({
  build: {
    sourcemap: true, // Required!
  },
  plugins: [
    {
      name: 'upload-sourcemaps',
      async closeBundle() {
        if (process.env.NODE_ENV === 'production') {
          await execAsync('npx @sonarly/sourcemap-uploader -m dist/assets -u https://myapp.com/assets');
        }
      }
    }
  ]
});

Create React App

{
  "scripts": {
    "build": "GENERATE_SOURCEMAP=true react-scripts build && npm run upload-sourcemaps",
    "upload-sourcemaps": "sourcemap-uploader -m build/static/js -u https://myapp.com/static/js"
  }
}

Next.js

// next.config.js
module.exports = {
  productionBrowserSourceMaps: true,
  // Add a postbuild script in package.json
};

Getting Your API Key

1. Go to your Sonarly dashboard
2. Navigate to Settings → API Keys
3. Create a new API key with "sourcemaps" permission

Security

• Never commit your API key to version control
• Use environment variables or CI/CD secrets
• Consider using -d flag to delete .map files after upload (prevents exposing source code)

Troubleshooting

"Authorization rejected"

• Check your API key is correct
• Ensure the API key has "sourcemaps" permission
• Verify the project key matches your project

"Server Error"

• Check the server URL is correct
• Ensure your network can reach the Sonarly server
• Use -v flag to see detailed error messages

"No sourcemap files found"

• Ensure your build generates .map files
• Check the directory path is correct
• Vite: Set build.sourcemap: true
• CRA: Set GENERATE_SOURCEMAP=true

License

MIT