Skip to content

docs(js): Use split layout in browser JS quick start guide #17101

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
inventarSarah wants to merge 1 commit into
base: master
Choose a base branch
from
+155 −19
Open

docs(js): Use split layout in browser JS quick start guide #17101

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 56 additions & 11 deletions platform-includes/getting-started-complete/javascript.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,4 @@
<PlatformContent includePath="getting-started-prerequisites" />

## Step 1: Install

Choose the features you want to configure, and this guide will show you how:

<OnboardingOptionButtons
Expand All @@ -13,28 +10,72 @@ Choose the features you want to configure, and this guide will show you how:
"logs",
]}
/>

<Include name="quick-start-features-expandable" />

### Install the Sentry SDK
<StepConnector selector="h2" showNumbers={true}>

## Install

<PlatformContent includePath="getting-started-install" />

## Step 2: Configure
## Configure

### Initialize the Sentry SDK

<PlatformContent includePath="getting-started-config" />

## Step 3: Add Readable Stack Traces With Source Maps (Optional)
### Add Readable Stack Traces With Source Maps (Optional)

<SplitLayout>

<SplitSection>

<SplitSectionText>
The stack traces in your Sentry errors probably won't look like your actual
code without unminifying them. To fix this, upload your{" "}
<PlatformLink to="/sourcemaps/">source maps</PlatformLink> to Sentry. The
easiest way to do this is by using the Sentry Wizard.
</SplitSectionText>

<SplitSectionCode>

```bash
npx @sentry/wizard@latest -i sourcemaps
```

</SplitSectionCode>

<PlatformContent includePath="getting-started-sourcemaps-short-version" />
</SplitSection>

## Step 4: Avoid Ad Blockers With Tunneling (Optional)
</SplitLayout>

<PlatformContent includePath="getting-started-tunneling" />
### Avoid Ad Blockers With Tunneling (Optional)

## Step 5: Verify Your Setup
<SplitLayout>

<SplitSection>

<SplitSectionText>
You can prevent ad blockers from blocking Sentry events using tunneling. Use the `tunnel` option in `Sentry.init` to add an API endpoint in your application that forwards Sentry events to Sentry servers.

This will send all events to the `tunnel` endpoint. However, the events need to be parsed and redirected to Sentry, so you'll need to do additional configuration on the server. You can find a detailed explanation on how to do this on our <PlatformLink to="/troubleshooting/#using-the-tunnel-option"> Troubleshooting page</PlatformLink>.

</SplitSectionText>

<SplitSectionCode>
```javascript {3}
Sentry.init({
dsn: "___PUBLIC_DSN___",
tunnel: "/tunnel",
});
```
</SplitSectionCode>

</SplitSection>

</SplitLayout>

## Verify Your Setup

<PlatformContent includePath="getting-started-verify" />

Expand All @@ -44,6 +85,8 @@ Now, head over to your project on [Sentry.io](https://sentry.io) to view the col

<Include name="quick-start-locate-data-expandable" />

## Next Steps

At this point, you should have integrated Sentry into your JavaScript application and should already be sending data to your Sentry project.

Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are:
Expand All @@ -60,3 +103,5 @@ Now's a good time to customize your setup and look into more advanced topics. Ou
- [Get support](https://sentry.zendesk.com/hc/en-us/)

</Expandable>

</StepConnector>
16 changes: 16 additions & 0 deletions platform-includes/getting-started-config/javascript.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
<SplitLayout>

<SplitSection>

Comment on lines +1 to +4
Copy link

@sentry sentry bot Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: A shared include file, getting-started-config/javascript.mdx, was wrapped in a <SplitLayout>, which will break the layout for non-browser guides like Node.js that use it.
Severity: MEDIUM

Suggested Fix

Instead of modifying the shared include file directly, wrap the <SplitLayout> component within the file with a <PlatformSection platform="javascript.browser">. This will ensure the split layout only renders for browser-based guides and does not affect Node.js or other server-side framework documentation.

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: platform-includes/getting-started-config/javascript.mdx#L1-L4

Potential issue: The shared include file
`platform-includes/getting-started-config/javascript.mdx` has been entirely wrapped in a
`<SplitLayout>` component. This file is used by various JavaScript guides, including
those for Node.js and other server-side frameworks. These non-browser guides do not use
the necessary parent layout components that `<SplitLayout>` requires. As a result, when
these guides include the modified file, the layout will render incorrectly, leading to a
broken visual presentation for users viewing the Node.js or server-side framework quick
start documentation.

Did we get this right? 👍 / 👎 to inform future reviews.

Copy link
Collaborator Author

@inventarSarah inventarSarah Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't find any other guide that uses this file so it should be fine.

We could inline the content just to be safe

<SplitSectionText>

Initialize Sentry as early as possible in your application's lifecycle. The setup differs slightly depending on how you installed the Sentry SDK. Be sure to follow the instructions in the related tab (npm, Loader, CDN):

</SplitSectionText>

<SplitSectionCode>

```javascript {tabTitle:npm}
import * as Sentry from "___SDK_PACKAGE___";

Expand Down Expand Up @@ -180,3 +190,9 @@ Sentry.init({
});
</script>
```

</SplitSectionCode>

</SplitSection>

</SplitLayout>
14 changes: 14 additions & 0 deletions platform-includes/getting-started-install/javascript.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,17 @@
We recommend installing Sentry via a package manager. If that isn't an option for you, you can use the [Loader Script](/platforms/javascript/install/loader/) or a CDN bundle.

<SplitLayout>

<SplitSection>

<SplitSectionText>
#### Option 1: Package Manager (Recommended)

Run the command for your preferred package manager to add the Sentry SDK to your application:

</SplitSectionText>
<SplitSectionCode>

```bash {tabTitle:npm}
npm install @sentry/browser --save
```
Expand All @@ -16,6 +24,12 @@ yarn add @sentry/browser
pnpm add @sentry/browser
```

</SplitSectionCode>

</SplitSection>

</SplitLayout>

#### Option 2: Loader Script
Copy link
Collaborator Author

@inventarSarah inventarSarah Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we move the other 2 options into the split layout?

It looks better to me this way


In Sentry, go to
Expand Down
77 changes: 69 additions & 8 deletions platform-includes/getting-started-verify/javascript.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,22 @@ Let's test your setup and confirm that data reaches your Sentry project.

### Issues

To verify that Sentry captures errors and creates issues in your Sentry project, add a button that throws an error when clicked:
<SplitLayout>

<SplitSection>

<SplitSectionText>
To verify that Sentry captures errors and creates issues in your Sentry project, add a button that throws an error when clicked.

<OnboardingOption optionId="performance" hideForThisOption>
Open the page in a browser and click the button to throw an error.
</OnboardingOption>

<PlatformContent includePath="getting-started-browser-sandbox-warning" />

</SplitSectionText>

<SplitSectionCode>

```html
<script>
Expand All @@ -14,15 +29,26 @@ To verify that Sentry captures errors and creates issues in your Sentry project,
<button onclick="triggerError()">Break the World</button>
```

<OnboardingOption optionId="performance" hideForThisOption>
Open the page in a browser and click the button to throw an error.
</OnboardingOption>
</SplitSectionCode>

<PlatformContent includePath="getting-started-browser-sandbox-warning" />
</SplitSection>

</SplitLayout>

<OnboardingOption optionId="performance">
### Tracing
To test your tracing configuration, update the previous code to simulate a longer operation and start a trace:
<SplitLayout>

<SplitSection>

<SplitSectionText>
To test your tracing configuration, update the previous code to simulate a longer operation and start a trace.

Open the page in a browser and click the button to throw an error and create a trace.

</SplitSectionText>

<SplitSectionCode>

```html
<script>
Expand All @@ -41,12 +67,47 @@ To test your tracing configuration, update the previous code to simulate a longe
<button onclick="triggerError()">Break the World</button>
```

Open the page in a browser and click the button to throw an error and create a trace.
</SplitSectionCode>

</SplitSection>

</SplitLayout>

</OnboardingOption>

<OnboardingOption optionId="logs">

<Include name="logs/javascript-quick-start-verify-logs" />
### Logs <FeatureBadge type="new" size="small" />

<SplitLayout>

<SplitSection>

<SplitSectionText>
To verify that Sentry catches your logs, add some log statements to your application:

</SplitSectionText>

<SplitSectionCode>

```javascript
Sentry.logger.info("User example action completed");

Sentry.logger.warn("Slow operation detected", {
operation: "data_fetch",
duration: 3500,
});

Sentry.logger.error("Validation failed", {
field: "email",
reason: "Invalid email",
});
```

</SplitSectionCode>

</SplitSection>

</SplitLayout>

</OnboardingOption>
Loading