Skip to content

Commit e152325

Browse files
lucas-zimermanlucas-zimerman
committed
capacitor source maps update
1 parent 72e6b30 commit e152325

File tree

4 files changed

+344
-2
lines changed

4 files changed

+344
-2
lines changed

‎docs/platforms/javascript/common/sourcemaps/uploading/ionic-capacitor.mdx

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
---
2+
title: Ionic Capacitor Build
3+
description: "Upload your source maps using ionic capacitor and Sentry CLI."
4+
sidebar_order: 2
5+
Supported:
6+
- javascript.capacitor
7+
---
8+
9+
In this guide, you'll learn how to successfully upload source maps for TypeScript using our `sentry-cli` tool.
10+
11+
<Include name="debug-id-requirement.mdx" />
12+
13+
<Alert>
14+
15+
This guide is only applicable if you're using the command `ionic capacitor build` to compile your project. If you use another command, you'll most likely want to follow that guide instead.
16+
17+
</Alert>
18+
19+
## Automatic Setup
20+
21+
You can use Sentry Wizard to give you an initial setup, but manual changes will still be required in order to setup sourcemaps
22+
for this build setup.
23+
24+
<Include name="sourcemaps-wizard-instructions.mdx" />
25+
26+
## Manual Setup
27+
28+
### 1. Generate Source Maps
29+
30+
First, configure the TypeScript compiler to output source maps:
31+
32+
```json {filename:tsconfig.json}
33+
{
34+
"compilerOptions": {
35+
"sourceMap": true,
36+
"inlineSources": true,
37+
38+
// Set `sourceRoot` to "/" to strip the build path prefix from
39+
// generated source code references. This will improve issue grouping in Sentry.
40+
"sourceRoot": "/"
41+
}
42+
}
43+
```
44+
45+
<Alert>
46+
Generating sourcemaps may expose them to the public, potentially causing your source code to be leaked. You can prevent this by configuring your server to deny access to `.js.map` files, or by deleting the sourcemaps before deploying your application.
47+
</Alert>
48+
49+
### 2. Configure Sentry CLI
50+
51+
<Alert>
52+
53+
You can find installation instructions for Sentry CLI here: https://docs.sentry.io/cli/installation/
54+
55+
For more info on `sentry-cli` configuration visit the [Sentry CLI configuration docs](/cli/configuration/).
56+
57+
</Alert>
58+
59+
Make sure `sentry-cli` is configured for your project. For that you can use environment variables:
60+
61+
<OrgAuthTokenNote />
62+
63+
```bash {filename:.env.local}
64+
SENTRY_ORG=___ORG_SLUG___
65+
SENTRY_PROJECT=___PROJECT_SLUG___
66+
SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
67+
```
68+
69+
### 3. Inject Debug IDs Into Artifacts
70+
71+
Debug IDs are used to match the stack frame of an event with its corresponding minified source and source map file. Visit [What are Debug IDs](/platforms/javascript/sourcemaps/troubleshooting_js/debug-ids/) if you want to learn more about Debug IDs.
72+
73+
To inject Debug IDs, use the following command after you build your project:
74+
75+
```bash
76+
// Paths can vary so check where your assets/public and App/public folder are.
77+
sentry-cli sourcemaps inject /path/to/directory/android/app/src/main/assets/public
78+
sentry-cli sourcemaps inject /path/to/directory/ios/App/public
79+
```
80+
81+
#### Verify Debug IDs Were Injected in Artifacts
82+
83+
Minified source files should contain at the end a comment named `debugId` like:
84+
85+
```javascript {filename:example_minified_file.js}
86+
...
87+
//# debugId=<debug_id>
88+
//# sourceMappingURL=<sourcemap_url>
89+
```
90+
91+
Source maps should contain a field named `debug_id` like:
92+
93+
```json {filename:example_source_map.js.map}
94+
{
95+
...
96+
"debug_id":"<debug_id>",
97+
...
98+
}
99+
```
100+
101+
### 4. Upload Artifact Bundle
102+
103+
After you've injected Debug IDs into your artifacts, upload them using the following command.
104+
105+
```bash
106+
// Paths can vary so check where your assets/public and App/public folder are.
107+
sentry-cli sourcemaps upload /path/to/directory/android/app/src/main/assets/public
108+
sentry-cli sourcemaps upload /path/to/directory/ios/App/public
109+
110+
```
111+
112+
#### Verify That Artifact Bundles Were Uploaded
113+
114+
Open up Sentry and navigate to **Project Settings > Source Maps**. If you choose “Artifact Bundles” in the tabbed navigation, you'll see all the artifact bundles that have been successfully uploaded to Sentry.
115+
116+
### 5. Deploy your Application
117+
118+
If you're following this guide from your local machine, then you've successfully:
119+
120+
1. Generated minified source and source map files (artifacts) by running your application's build process
121+
2. Injected Debug IDs into the artifacts you've just generated
122+
3. Uploaded those artifacts to Sentry with our upload command
123+
124+
The last step is deploying a new version of your application using the generated artifacts you created in step one. **We strongly recommend that you integrate `sentry-cli` into your CI/CD Pipeline**, to ensure each subsequent deploy will automatically inject debug IDs into each artifact and upload them directly to Sentry.
125+
126+
### Optional Steps
127+
128+
<Alert title="Warning">
129+
130+
Only follow these optional steps if you have concluded that you absolutely need them.
131+
Using `release` and `dist` values will make your artifact upload more specific, but will also make the entire process less forgiving, which may lead to your code not being unminified by Sentry.
132+
133+
</Alert>
134+
135+
#### Associating `release` with Artifact Bundle
136+
137+
Provide a `release` property in your SDK options.
138+
139+
```javascript
140+
Sentry.init({
141+
// This value must be identical to the release name specified during upload
142+
// with the `sentry-cli`.
143+
release: "<release_name>",
144+
});
145+
```
146+
147+
Afterwards, run the `sourcemaps upload` command with the additional `--release` option. Please ensure that the value specified for `<release_name>` is the same value specified in your SDK options.
148+
149+
```bash
150+
// Paths can vary so check where your assets/public and App/public folder are.
151+
sentry-cli sourcemaps upload --release=<release_name> /path/to/directory/android/app/src/main/assets/public
152+
sentry-cli sourcemaps upload --release=<release_name> /path/to/directory/ios/App/public
153+
```
154+
155+
<Alert>
156+
157+
Running `upload` with `--release` **doesn't automatically create a release in Sentry**.
158+
Either wait until the first event with the new release set in `Sentry.init` is sent to Sentry, or create a release with the same name in a separate step [with the CLI](/cli/releases).
159+
160+
</Alert>
161+
162+
#### Associating `dist` with Artifact Bundle
163+
164+
In addition to `release`, you can also add a `dist` to your uploaded artifacts, to set the distribution identifier for uploaded files. To do so, run the `sourcemaps upload` command with the additional `--dist` option.
165+
166+
Provide `release` and `dist` properties in your SDK options.
167+
168+
```javascript
169+
Sentry.init({
170+
// These values must be identical to the release and dist names specified during upload
171+
// with the `sentry-cli`.
172+
release: "<release_name>",
173+
dist: "<dist_name>",
174+
});
175+
```
176+
177+
The distribution identifier is used to distinguish between multiple files of the same name within a single release. `dist` can be used to disambiguate build or deployment variants.
178+
179+
```bash
180+
181+
// Paths can vary so check where your assets/public and App/public folder are.
182+
sentry-cli sourcemaps upload --release=<release_name> --dist=<dist_name> /path/to/directory/android/app/src/main/assets/public
183+
sentry-cli sourcemaps upload --release=<release_name> --dist=<dist_name> /path/to/directory/ios/App/public
184+
```
185+
186+
## Dealing with TSLib
187+
188+
During compilation, TypeScript will inject some of its runtime dependencies into the output files it produces if needed. It can include things like polyfills for function generators or APIs that may not be available in all the environments. However, the fact that there aren't any original sources makes it impossible to map frames from compiled code to the original sources.
189+
190+
As a workaround, you'll need to tell the TypeScript compiler to use `tslib`, its own 3rd party package, (which is internally the part of a compiler) instead of injecting runtime dependencies. You'll only need to change what's inside the TypeScript config file, not your source code. Here's how:
191+
192+
1. Make sure that `tslib` is listed as the dependency in your `package.json` file.
193+
2. Once that's done, add two entries in `compilerOptions` section of your `tsconfig.json`:
194+
- `"noEmitHelpers": true` and
195+
-`"importHelpers": true`.
196+
197+
That's it! Now you should be able to correctly map the source maps for all your stack trace frames, including internal TypeScript compiler code snippets.

‎docs/platforms/javascript/common/sourcemaps/uploading/ionic.mdx

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: Ionic
3+
description: "Upload your source maps using Ionic and Sentry CLI."
4+
sidebar_order: 2
5+
notSupported:
6+
- javascript.svelte
7+
- javascript.sveltekit
8+
---
9+
10+
In this guide, you'll learn how to successfully upload source maps for TypeScript using our `sentry-cli` tool.
11+
12+
<Include name="debug-id-requirement.mdx" />
13+
14+
<Alert>
15+
16+
This guide is only applicable if you're using `tsc` to compile your project. If you use another tool (such as webpack) in combination with TypeScript, you'll most likely want to follow that guide instead.
17+
18+
</Alert>
19+
20+
## Automatic Setup
21+
22+
The easiest way to configure source map uploading with `tsc` and `sentry-cli` is by using the Sentry Wizard:
23+
24+
<Include name="sourcemaps-wizard-instructions.mdx" />
25+
26+
If you'd rather configure source maps manually, follow the steps below.
27+
28+
## Manual Setup
29+
30+
### 1. Generate Source Maps
31+
32+
First, configure the TypeScript compiler to output source maps:
33+
34+
```json {filename:tsconfig.json}
35+
{
36+
"compilerOptions": {
37+
"sourceMap": true,
38+
"inlineSources": true,
39+
40+
// Set `sourceRoot` to "/" to strip the build path prefix from
41+
// generated source code references. This will improve issue grouping in Sentry.
42+
"sourceRoot": "/"
43+
}
44+
}
45+
```
46+
47+
<Alert>
48+
Generating sourcemaps may expose them to the public, potentially causing your source code to be leaked. You can prevent this by configuring your server to deny access to `.js.map` files, or by deleting the sourcemaps before deploying your application.
49+
</Alert>
50+
51+
<Include name="sentry-cli-sourcemaps.mdx" />
52+
53+
## Dealing with TSLib
54+
55+
During compilation, TypeScript will inject some of its runtime dependencies into the output files it produces if needed. It can include things like polyfills for function generators or APIs that may not be available in all the environments. However, the fact that there aren't any original sources makes it impossible to map frames from compiled code to the original sources.
56+
57+
As a workaround, you'll need to tell the TypeScript compiler to use `tslib`, its own 3rd party package, (which is internally the part of a compiler) instead of injecting runtime dependencies. You'll only need to change what's inside the TypeScript config file, not your source code. Here's how:
58+
59+
1. Make sure that `tslib` is listed as the dependency in your `package.json` file.
60+
2. Once that's done, add two entries in `compilerOptions` section of your `tsconfig.json`:
61+
- `"noEmitHelpers": true` and
62+
-`"importHelpers": true`.
63+
64+
That's it! Now you should be able to correctly map the source maps for all your stack trace frames, including internal TypeScript compiler code snippets.

‎docs/platforms/javascript/guides/capacitor/index.mdx

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -467,12 +467,32 @@ You can also use the features available with the Sentry SDK for the framework yo
467467

468468
You will need to upload source maps to make sense of the events you receive in Sentry.
469469

470-
For example, if you are using Capacitor with Ionic-Angular, upload your `www` folder on **every build** you release. The values for `<release_name>` and `<dist>` must match the values passed into `Sentry.init` for events to be deminified correctly.
470+
If you are using Capacitor with Ionic-Angular, upload your outputPath folder (tipically `www` or `dist`) on **every build** you release. The values for `<release_name>` and `<dist>` must match the values passed into `Sentry.init` for events to be deminified correctly.
471471

472-
```bash {tabTitle: Ionic}
472+
```bash {tabTitle: Ionic Build & others}
473+
sentry-cli sourcemaps inject --org ___ORG_SLUG___ --project ___PROJECT_SLUG___ ./www
473474
sentry-cli sourcemaps upload --release <release_name> --dist <dist> ./www
474475
```
475476

477+
```bash {tabTitle: Ionic Capacitor Build}
478+
479+
# Android
480+
sentry-cli sourcemaps inject --org ___ORG_SLUG___ --project ___PROJECT_SLUG___ ./android/app/src/main/assets/public
481+
sentry-cli sourcemaps upload --org ___ORG_SLUG___ --project ___PROJECT_SLUG___ --release <release_name> --dist <dist> ./android/app/src/main/assets/public
482+
find ./android/app/src/main/assets/public -type f -name '*.map' -delete # Optional, removes sourcemaps from the mobile app.
483+
484+
# iOS
485+
sentry-cli sourcemaps inject --org ___ORG_SLUG___ --project ___PROJECT_SLUG___ ./ios/App/App/public
486+
sentry-cli sourcemaps upload --org ___ORG_SLUG___ --project ___PROJECT_SLUG___ --release <release_name> --dist <dist> ./ios/App/App/public,
487+
find ./ios/App/App/public -type f -name '*.map' -delete # Optional, removes sourcemaps from the mobile app.
488+
489+
```
490+
491+
<Alert level="warning" title="Important">
492+
If you are building your project using `ionic capacitor build`, you must upload the sourcemaps from the native app folder (e.g., android/app/build/assets) — not from the `outputPath` defined in your web project (like `www` or `dist`).
493+
</Alert>
494+
495+
476496
Learn more about uploading [source maps](/platforms/javascript/guides/capacitor/sourcemaps/).
477497

478498
### Provide Native Debug Information (iOS)

‎platform-includes/sourcemaps/overview/javascript.capacitor.mdx

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
## Uploading Source Maps
2+
3+
The easiest way to configure uploading source maps is by using the Sentry Wizard:
4+
5+
<Include name="sourcemaps-wizard-instructions.mdx" />
6+
7+
<PlatformSection supported={['javascript', 'javascript.react']}>
8+
9+
<Alert>
10+
11+
This guide assumes you are using a Browser JavaScript SDK. For instructions on how to set up source maps for React Native, follow the [source maps guide for React Native](/platforms/react-native/sourcemaps/).
12+
13+
</Alert>
14+
15+
</PlatformSection>
16+
17+
If you want to configure source maps to upload manually, follow the guide for your bundler or build tool below.
18+
19+
<PlatformSection supported={["javascript.react"]}>
20+
21+
### Create React App
22+
23+
If you used Create React App to set up your React application see our <PlatformLink to="/sourcemaps/uploading/create-react-app/">Create React App</PlatformLink> guide to upload source maps.
24+
25+
</PlatformSection>
26+
27+
## Sentry Bundler Support
28+
29+
- <PlatformLink to="/sourcemaps/uploading/webpack/">webpack</PlatformLink>
30+
- <PlatformLink to="/sourcemaps/uploading/rollup/">Rollup</PlatformLink>
31+
- <PlatformLink to="/sourcemaps/uploading/vite/">Vite</PlatformLink>
32+
- <PlatformLink to="/sourcemaps/uploading/esbuild/">esbuild</PlatformLink>
33+
34+
### Guides for Source Maps
35+
36+
- <PlatformLink to="/sourcemaps/uploading/ionic-capacitor/">Ionic Capacitor build</PlatformLink>
37+
- <PlatformLink to="/sourcemaps/uploading/ionic/">Ionic Build</PlatformLink>
38+
- <PlatformLink to="/sourcemaps/uploading/typescript/">TypeScript (tsc)</PlatformLink>
39+
40+
<Alert>
41+
If you're using one of webpack, Vite, Rollup, or Esbuild, use the
42+
corresponding Sentry plugin instead (see section "Sentry Bundler Support").
43+
</Alert>
44+
45+
- <PlatformLink to="/sourcemaps/uploading/uglifyjs/">UglifyJS</PlatformLink>
46+
- <PlatformLink to="/sourcemaps/uploading/systemjs/">SystemJS</PlatformLink>
47+
- [GitHub Actions](/product/releases/setup/release-automation/github-actions/)
48+
49+
## Other Tools
50+
51+
If you're not using one of these tools, we assume you already know how to generate source maps with your toolchain and we recommend you upload them using <PlatformLink to="/sourcemaps/uploading/cli/">Sentry CLI</PlatformLink>.
52+
53+
<PlatformSection notSupported={['javascript.node', 'javascript.aws-lambda', 'javascript.azure-functions', 'javascript.connect', 'javascript.express', 'javascript.fastify', 'javascript.gcp-functions', 'javascript.hapi', 'javascript.hono', 'javascript.koa', 'javascript.nestjs']}>
54+
55+
<Alert>
56+
57+
Though we strongly recommend uploading source maps as part of your build process, for browser applications it's also possible to <PlatformLink to="/sourcemaps/uploading/hosting-publicly/">host your source maps publicly</PlatformLink>.
58+
59+
</Alert>
60+
61+
</PlatformSection>

0 commit comments

Comments
 (0)