Feature loader

README.md

@@ -91,6 +91,42 @@ define('WP_SENTRY_BROWSER_FRONTEND_ENABLED', true); // Add the JavaScript tracke
 
 **Note:** This constant was previously called `WP_SENTRY_PUBLIC_DSN` and is still supported.
 
+### `WP_SENTRY_BROWSER_LOADER_URL` (Browser)
+
+Instead of loading the bundled Sentry SDK, you can use [Sentry's Loader Script](https://docs.sentry.io/platforms/javascript/install/loader/) which provides lazy loading capabilities. The loader is a small (~1KB) script that buffers errors and only loads the full SDK when an error occurs (when true lazy loading is possible) or on page load (when tracing or replay is enabled).
+
+**Using with Sentry.io:**
+
+Get your loader URL from your Sentry project settings under "Client Keys (DSN)" → "Configure" → "Loader Script URL":
+
+```php
+define( 'WP_SENTRY_BROWSER_LOADER_URL', 'https://js.sentry-cdn.com/YOUR_PUBLIC_KEY.min.js' );
+```
+
+**Using with self-hosted Sentry:**
+
+Self-hosted Sentry instances (v21.9+) can serve loader scripts. Use your instance's loader URL:
+
+```php
+define( 'WP_SENTRY_BROWSER_LOADER_URL', 'https://your-sentry.example.com/js-sdk-loader/YOUR_PUBLIC_KEY.min.js' );
+```
+
+**How it works:**
+
+- When `WP_SENTRY_BROWSER_LOADER_URL` is set, the plugin uses the loader instead of the bundled SDK
+- The loader is configured using `window.sentryOnLoad` callback with your WordPress settings (DSN, environment, release, tracing options, etc.)
+- If tracing (`WP_SENTRY_BROWSER_TRACES_SAMPLE_RATE`) or session replay (`WP_SENTRY_BROWSER_REPLAYS_SESSION_SAMPLE_RATE`) is enabled, `data-lazy="no"` is automatically added to load the SDK immediately
+- All other configuration options (`WP_SENTRY_VERSION`, `WP_SENTRY_ENV`, filters, etc.) work the same as with the bundled SDK
+
+**Benefits:**
+
+- **Smaller initial payload**: The loader is ~1KB vs ~30KB+ for the full SDK
+- **Lazy loading**: SDK only loads when an error occurs (if tracing/replay is disabled)
+- **CDN caching**: The SDK loaded by the loader is cached across all sites using Sentry
+- **Automatic updates**: Sentry manages the SDK version served by the loader (configurable in your project settings)
+
+**Note:** The loader URL must be a valid URL. If not set or invalid, the plugin falls back to loading the bundled SDK.
+
 ### Privacy
 
 #### `WP_SENTRY_SEND_DEFAULT_PII`

readme.txt

@@ -52,6 +52,18 @@ To track Browser (JavaScript) errors add this snippet to your `wp-config.php` an
 
 **Note:** Do not set this constant to disable the Browser (JavaScript) tracker.
 
+**Using Sentry's Loader Script (Recommended for Sentry.io or self-hosted with loader support):**
+
+Instead of loading the bundled SDK, you can use Sentry's Loader Script which provides lazy loading capabilities. The loader is a small (~1KB) script that buffers errors and only loads the full SDK when needed:
+
+    define( 'WP_SENTRY_BROWSER_LOADER_URL', 'https://js.sentry-cdn.com/YOUR_PUBLIC_KEY.min.js' );
+
+For self-hosted Sentry instances, use your loader URL:
+
+    define( 'WP_SENTRY_BROWSER_LOADER_URL', 'https://your-sentry.example.com/js-sdk-loader/YOUR_PUBLIC_KEY.min.js' );
+
+When using the loader, `data-lazy="no"` is automatically added if tracing or session replay is enabled (since these features require immediate SDK loading).
+
 _You can find more information and the full documentation: [here](https://github.com/stayallive/wp-sentry/tree/v8.10.0#configuration). The above are the basics._
 
 == Changelog ==

src/class-wp-sentry-admin-page.php

@@ -171,6 +171,7 @@ public function render_admin_page(): void {
 		$js_tracker = WP_Sentry_Js_Tracker::get_instance();
 
 		$enabled_for_js      = $js_tracker->enabled();
+		$js_loader_enabled   = $js_tracker->loader_enabled();
 		$js_tracing_enabled  = $enabled_for_js && $js_tracker->tracing_enabled();
 		$js_replays_enabled  = $enabled_for_js && $js_tracker->replays_enabled();
 		$js_feedback_enabled = $enabled_for_js && $js_tracker->feedback_enabled();
@@ -388,6 +389,23 @@ public function render_admin_page(): void {
 							</p>
 						</td>
 					</tr>
+					<tr>
+						<th><?php esc_html_e( 'Loader', 'wp-sentry' ); ?></th>
+						<td>
+							<fieldset>
+								<label>
+									<input name="wp-sentry-js-loader-enabled" type="checkbox" id="wp-sentry-js-loader-enabled" value="0" <?php echo $js_loader_enabled ? 'checked="checked"' : '' ?> readonly disabled>
+									<?php esc_html_e( 'Enabled', 'wp-sentry' ); ?>
+									(<a href="https://github.com/stayallive/wp-sentry/tree/v<?php echo WP_Sentry_Version::SDK_VERSION; ?>#wp_sentry_browser_loader_url-browser" target="_blank" rel="noopener">documentation</a>)
+								</label>
+							</fieldset>
+							<?php if ( ! $js_loader_enabled ): ?>
+								<p class="description">
+									<?php echo translate( 'To enable make sure <code>WP_SENTRY_BROWSER_LOADER_URL</code> is set.', 'wp-sentry' ); ?>
+								</p>
+							<?php endif; ?>
+						</td>
+					</tr>					
 					<tr>
 						<th><?php esc_html_e( 'Tracing', 'wp-sentry' ); ?></th>
 						<td>

src/class-wp-sentry-js-tracker.php

@@ -172,6 +172,29 @@ public function on_enqueue_scripts(): void {
 
 		$featuresString = implode( '.', $features );
 
+		// Check if loader script mode is enabled
+		if ( $this->loader_enabled() ) {
+			$loader_url   = WP_SENTRY_BROWSER_LOADER_URL;
+			$init_options = array_merge( $options, $this->get_options(), [ 'dsn' => $this->get_dsn() ] );
+			// Enqueue the loader script
+			wp_enqueue_script( 'wp-sentry-browser', $loader_url, [], null );
+			// Add sentryOnLoad callback before the loader script
+			wp_add_inline_script(
+				'wp-sentry-browser',
+				'window.sentryOnLoad = function() { Sentry.init(' . wp_json_encode( $init_options ) . '); };',
+				'before'
+			);
+			// Add crossorigin and data-lazy attributes to the script tag
+			add_filter( 'script_loader_tag', function ( $tag, $handle ) {
+				if ( $handle === 'wp-sentry-browser' ) {
+					$lazy_attr = ( $this->tracing_enabled() || $this->replays_enabled() ) ? 'data-lazy="no"' : '';
+					return str_replace( ' src=', ' crossorigin="anonymous" ' . $lazy_attr . ' src=', $tag );
+				}
+				return $tag;
+			}, 10, 2 );
+			return;
+		}
+
 		wp_enqueue_script(
 			'wp-sentry-browser-bundle',
 			plugin_dir_url( WP_SENTRY_PLUGIN_FILE ) . "public/wp-sentry-{$featuresString}.min.js",
@@ -225,6 +248,10 @@ public function on_enqueue_admin_scripts(): void {
 	public function enabled(): bool {
 		return ! empty( $this->get_dsn() );
 	}
+
+	public function loader_enabled(): bool {
+		return defined( 'WP_SENTRY_BROWSER_LOADER_URL' ) && filter_var( WP_SENTRY_BROWSER_LOADER_URL , FILTER_VALIDATE_URL );
+	}
 
 	public function tracing_enabled(): bool {
 		$sample_rate = defined( 'WP_SENTRY_BROWSER_TRACES_SAMPLE_RATE' )