Skip to content

Commit 584aed8

Browse files
cursoragentbuenaflor
cursoragent
and
buenaflor
committed
Add Flutter Chrome Extensions configuration guide for Sentry
Co-authored-by: giancarlo.buenaflor <[email protected]>
1 parent 4724273 commit 584aed8

File tree

1 file changed

+150
-0
lines changed

1 file changed

+150
-0
lines changed

‎docs/platforms/dart/guides/flutter/configuration/chrome-extensions.mdx‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
title: Chrome Extensions
3+
description: "Learn how to set up the Sentry Flutter SDK for Chrome Extensions with Flutter Web."
4+
sidebar_order: 10
5+
---
6+
7+
When building Flutter Web applications that will be packaged as Chrome Extensions, there are specific configuration requirements due to Chrome's Content Security Policy (CSP) restrictions. This guide walks you through the necessary setup steps.
8+
9+
## Overview
10+
11+
Chrome Extensions enforce strict Content Security Policy (CSP) rules that prevent dynamically loaded scripts. Since the Sentry Flutter SDK typically loads the Sentry JavaScript SDK dynamically for web platforms, this approach won't work in Chrome Extension environments.
12+
13+
## Required Setup
14+
15+
### 1. Download the Sentry JavaScript Bundle
16+
17+
Instead of loading the Sentry JavaScript SDK dynamically, you need to include it as a static asset:
18+
19+
1. Download the minified Sentry JavaScript bundle. For example, for version 9.40.0:
20+
```
21+
https://browser.sentry-cdn.com/9.40.0/bundle.tracing.min.js
22+
```
23+
24+
2. Save this file to your Flutter web project's `web/` directory.
25+
26+
### 2. Include the Script in Your HTML
27+
28+
Add the Sentry JavaScript bundle to your `web/index.html` file:
29+
30+
```html {filename:web/index.html}
31+
<!DOCTYPE html>
32+
<html>
33+
<head>
34+
<!-- Other head elements -->
35+
<script src="bundle.tracing.min.js" type="application/javascript"></script>
36+
</head>
37+
<body>
38+
<!-- Your app content -->
39+
</body>
40+
</html>
41+
```
42+
43+
### 3. Configure Your Flutter Build
44+
45+
When building your Flutter web app for Chrome Extensions, use the following build command to ensure compatibility:
46+
47+
```bash
48+
flutter build web --no-web-resources-cdn --pwa-strategy=none --source-maps
49+
```
50+
51+
**Build flags explained:**
52+
- `--no-web-resources-cdn`: Prevents Flutter from loading resources from external CDNs, which may be blocked by CSP
53+
- `--pwa-strategy=none`: Disables Progressive Web App features that may conflict with extension policies
54+
- `--source-maps`: Generates source maps for better debugging and error reporting
55+
56+
### 4. Upload Source Maps
57+
58+
After building your application, upload the generated source maps to Sentry for better debugging:
59+
60+
```bash
61+
sentry_dart_plugin
62+
```
63+
64+
Make sure you have the [Sentry Dart Plugin](/platforms/dart/guides/flutter/configuration/options/#sentry-dart-plugin) properly configured in your project.
65+
66+
## Complete Example
67+
68+
Here's a minimal example of the required files:
69+
70+
<details>
71+
<summary><code>web/index.html</code></summary>
72+
73+
```html {filename:web/index.html}
74+
<!DOCTYPE html>
75+
<html>
76+
<head>
77+
<base href="$FLUTTER_BASE_HREF">
78+
<meta charset="UTF-8">
79+
<meta content="IE=Edge" http-equiv="X-UA-Compatible">
80+
<meta name="description" content="My Chrome Extension">
81+
<meta name="apple-mobile-web-app-capable" content="yes">
82+
<meta name="apple-mobile-web-app-status-bar-style" content="black">
83+
<meta name="apple-mobile-web-app-title" content="My Extension">
84+
<link rel="apple-touch-icon" href="icons/Icon-192.png">
85+
<link rel="icon" type="image/png" href="favicon.png"/>
86+
<title>My Chrome Extension</title>
87+
<link rel="manifest" href="manifest.json">
88+
89+
<!-- Sentry JavaScript SDK -->
90+
<script src="bundle.tracing.min.js" type="application/javascript"></script>
91+
92+
<script>
93+
// Required for Chrome Extensions
94+
var serviceWorkerVersion = null;
95+
</script>
96+
<script src="flutter_service_worker.js?v=$FLUTTER_SERVICE_WORKER_VERSION" defer></script>
97+
</head>
98+
<body id="app-container">
99+
<script src="main.dart.js" type="application/javascript"></script>
100+
</body>
101+
</html>
102+
```
103+
104+
</details>
105+
106+
<details>
107+
<summary><code>pubspec.yaml</code> dependencies</summary>
108+
109+
```yaml {filename:pubspec.yaml}
110+
dependencies:
111+
flutter:
112+
sdk: flutter
113+
sentry_flutter: ^{{@inject packages.version('sentry.dart.flutter') }}
114+
115+
dev_dependencies:
116+
sentry_dart_plugin: ^{{@inject packages.version('sentry.dart.plugin') }}
117+
```
118+
119+
</details>
120+
121+
## Build and Deploy
122+
123+
1. Build your Flutter web app:
124+
```bash
125+
flutter build web --no-web-resources-cdn --pwa-strategy=none --source-maps
126+
```
127+
128+
2. Upload source maps:
129+
```bash
130+
dart run sentry_dart_plugin
131+
```
132+
133+
3. Package your Chrome Extension using the built files in the `build/web/` directory.
134+
135+
## Troubleshooting
136+
137+
**Script loading errors**: If you encounter script loading errors, ensure that:
138+
- The Sentry JavaScript bundle is properly downloaded and placed in the `web/` directory
139+
- The script tag in `index.html` has the correct path
140+
- Your Chrome Extension's `manifest.json` allows the necessary permissions
141+
142+
**CSP violations**: If you're still seeing CSP violations:
143+
- Verify that you're not loading any external resources
144+
- Check that the `--no-web-resources-cdn` flag is being used during build
145+
- Ensure your extension's `manifest.json` has appropriate CSP settings
146+
147+
**Source maps not uploading**: If source maps fail to upload:
148+
- Verify your Sentry project configuration in `pubspec.yaml`
149+
- Check that you have proper authentication configured for the Sentry CLI
150+
- Ensure the `--source-maps` flag is included in your build command

0 commit comments

Comments
 (0)