Sentry Plugin

The Sentry plugin integrates Sentry error tracking and monitoring into your Scully-generated static site. This allows you to track JavaScript errors and performance issues in your production static site.

Overview

Type: Post-Render Plugin
Function: Injects Sentry SDK script into HTML
Service: Sentry.io error tracking

Installation

Install the plugin as a dev dependency:

npm install -D @scullyio/scully-plugin-sentry

Configuration

Configure the plugin in your Scully configuration file:

// scully.<project-name>.config.ts
import { setPluginConfig, ScullyConfig } from '@scullyio/scully';
import { Sentry } from '@scullyio/scully-plugin-sentry';

const defaultPostRenderers = [];

setPluginConfig(Sentry, {
  key: 'your-key',
  org: 'your-org',
  project: 'your-project'
});

defaultPostRenderers.push(Sentry);

export const config: ScullyConfig = {
  projectRoot: './src',
  projectName: 'my-app',
  outDir: './dist/static',
  defaultPostRenderers,
  routes: {}
};

Configuration Options

The plugin accepts configuration in two formats:

Option 1: Individual Parameters

Provide key, org, and project separately:

setPluginConfig(Sentry, {
  key: 'abc123def456',
  org: 'my-company',
  project: 'my-project'
});

These values construct the DSN: https://{key}@{org}.ingest.sentry.io/{project}

Option 2: DSN String

Provide the complete DSN directly:

setPluginConfig(Sentry, {
  dsn: 'https://[email protected]/1234567'
});

Additional Options

src (optional)

Custom Sentry SDK source URL:

setPluginConfig(Sentry, {
  dsn: 'https://...',
  src: 'https://browser.sentry-cdn.com/7.0.0/bundle.min.js'
});

Default: https://browser.sentry-cdn.com/5.20.1/bundle.min.js

integrity (optional)

Subresource integrity hash for the Sentry SDK:

setPluginConfig(Sentry, {
  dsn: 'https://...',
  integrity: 'sha384-xxx...'
});

Default: sha384-O8HdAJg1h8RARFowXd2J/r5fIWuinSBtjhwQoPesfVILeXzGpJxvyY/77OaPPXUo

crossorigin (optional)

Control the crossorigin attribute:

setPluginConfig(Sentry, {
  dsn: 'https://...',
  crossorigin: false // Removes crossorigin attribute
});

Default: true (adds crossorigin="anonymous")

Getting Your Sentry Configuration

Sign up for Sentry.io
Create a new project or select an existing one
Go to Settings > Projects > [Your Project] > Client Keys (DSN)
Copy the DSN, which looks like:
```
https://[email protected]/7890123
```
Extract the values:
- key: abc123def456 (between https:// and @)
- org: o123456 (between @ and .ingest)
- project: 7890123 (after the last /)

Usage

Basic Setup

import { setPluginConfig, ScullyConfig } from '@scullyio/scully';
import { Sentry } from '@scullyio/scully-plugin-sentry';

setPluginConfig(Sentry, {
  dsn: 'https://[email protected]/7890123'
});

export const config: ScullyConfig = {
  defaultPostRenderers: [Sentry],
  routes: {}
};

Route-Specific Configuration

Apply Sentry only to specific routes:

export const config: ScullyConfig = {
  routes: {
    '/': {
      type: 'default',
      postRenderers: [Sentry]
    },
    '/blog/:slug': {
      type: 'contentFolder',
      slug: {
        folder: './blog'
      },
      postRenderers: [Sentry]
    }
  }
};

Environment Variables

Store sensitive configuration in environment variables:

setPluginConfig(Sentry, {
  dsn: process.env.SENTRY_DSN || 'https://...'
});

Or with individual parameters:

setPluginConfig(Sentry, {
  key: process.env.SENTRY_KEY,
  org: process.env.SENTRY_ORG,
  project: process.env.SENTRY_PROJECT
});

Set environment variables before building:

export SENTRY_DSN="https://[email protected]/7890123"
npx ng build
npx scully

How It Works

The plugin injects the following script into the <head> section of each rendered HTML page:

<script src="https://browser.sentry-cdn.com/5.20.1/bundle.min.js" 
        integrity="sha384-O8HdAJg1h8RARFowXd2J/r5fIWuinSBtjhwQoPesfVILeXzGpJxvyY/77OaPPXUo" 
        crossorigin="anonymous"></script>
<script>
  window.Sentry && window.Sentry.init({ 
    dsn: 'https://[email protected]/7890123',
    integrations: [
      new window.Sentry.Integrations.TryCatch({ XMLHttpRequest: false })
    ]
  });
</script>

Verification

After building your site:

Open a generated HTML file from dist/static
Verify the Sentry script is present in the <head> section
Deploy your site
Trigger a test error in your application
Check the Sentry dashboard for the error

Testing

To test error tracking:

Build and serve your static site:

npx ng build
npx scully
npx scully serve

Open your browser’s console and trigger an error:
```
throw new Error('Test error for Sentry');
```
Check your Sentry dashboard to verify the error was captured

Advanced Configuration

Custom Sentry Options

For more control over Sentry initialization, you may need to create a custom plugin:

import { registerPlugin } from '@scullyio/scully';

const customSentryPlugin = async (html: string): Promise<string> => {
  const sentryScript = `
    <script src="https://browser.sentry-cdn.com/7.0.0/bundle.min.js"></script>
    <script>
      window.Sentry && window.Sentry.init({
        dsn: 'https://...',
        environment: 'production',
        release: '[email protected]',
        tracesSampleRate: 1.0,
        integrations: [
          new window.Sentry.BrowserTracing(),
        ],
      });
    </script>
  `;
  return html.replace(/<\/head/i, `${sentryScript}</head`);
};

registerPlugin('postProcessByHtml', 'customSentry', customSentryPlugin);

Sentry with Angular Integration

For tighter Angular integration, consider using Sentry in your Angular application directly:

npm install @sentry/angular @sentry/tracing

Then configure in your Angular app. This provides better integration with Angular errors and routing.

Troubleshooting

Scripts Not Injected

If Sentry scripts are missing:

Verify the plugin is in defaultPostRenderers or route-specific postRenderers
Check that configuration is set before the Scully config export
Ensure no errors during plugin configuration

Configuration Errors

Common configuration errors:

Error: sentry plugin missing configuration

Solution: Call setPluginConfig(Sentry, {...}) before using the plugin

Error: sentry plugin "key" missing configuration

Solution: Provide key, org, and project, or use dsn

Errors Not Appearing in Sentry

Verify your DSN is correct
Check browser console for Sentry initialization errors
Ensure your site is deployed (local files may have CORS issues)
Check Sentry project settings and quotas

XMLHttpRequest Errors

The plugin disables XMLHttpRequest tracking by default:

integrations: [new window.Sentry.Integrations.TryCatch({ XMLHttpRequest: false })]

This prevents issues with static sites. To enable, create a custom plugin.

Repository

Package: @scullyio/scully-plugin-sentry
Repository: GitHub
Sentry SDK Version: 5.20.1 (default)

Overview

Plugin Types

Built-in Plugins

Creating Plugins

Community Plugins

Sentry Plugin

Sentry Plugin

Overview

Installation

Configuration

Configuration Options

Option 1: Individual Parameters

Option 2: DSN String

Additional Options

src (optional)

integrity (optional)

crossorigin (optional)

Getting Your Sentry Configuration

Usage

Basic Setup

Route-Specific Configuration

Environment Variables

How It Works

Verification

Testing

Advanced Configuration

Custom Sentry Options

Sentry with Angular Integration

Troubleshooting

Scripts Not Injected

Configuration Errors

Errors Not Appearing in Sentry

XMLHttpRequest Errors

Repository

See Also

Build docs developers (and LLMs) love

Overview

Plugin Types

Built-in Plugins

Creating Plugins

Community Plugins

​Sentry Plugin

​Overview

​Installation

​Configuration

​Configuration Options

​Option 1: Individual Parameters

​Option 2: DSN String

​Additional Options

​src (optional)

​integrity (optional)

​crossorigin (optional)

​Getting Your Sentry Configuration

​Usage

​Basic Setup

​Route-Specific Configuration

​Environment Variables

​How It Works

​Verification

​Testing

​Advanced Configuration

​Custom Sentry Options

​Sentry with Angular Integration

​Troubleshooting

​Scripts Not Injected

​Configuration Errors

​Errors Not Appearing in Sentry

​XMLHttpRequest Errors

​Repository

​See Also

Build docs developers (and LLMs) love

Sentry Plugin

Overview

Installation

Configuration

Configuration Options

Option 1: Individual Parameters

Option 2: DSN String

Additional Options

src (optional)

integrity (optional)

crossorigin (optional)

Getting Your Sentry Configuration

Usage

Basic Setup

Route-Specific Configuration

Environment Variables

How It Works

Verification

Testing

Advanced Configuration

Custom Sentry Options

Sentry with Angular Integration

Troubleshooting

Scripts Not Injected

Configuration Errors

Errors Not Appearing in Sentry

XMLHttpRequest Errors

Repository

See Also