diff --git a/docs/platforms/javascript/guides/solidstart/features/error-boundary.mdx b/docs/platforms/javascript/guides/solidstart/features/error-boundary.mdx index 16f1dce83989a..0d79d8ecde5a2 100644 --- a/docs/platforms/javascript/guides/solidstart/features/error-boundary.mdx +++ b/docs/platforms/javascript/guides/solidstart/features/error-boundary.mdx @@ -8,18 +8,4 @@ from inside a component tree and render a fallback component. Wrap the native Solid `ErrorBoundary` component with `Sentry.withSentryErrorBoundary`. -```jsx -import * as Sentry from "@sentry/solidstart"; -import { ErrorBoundary } from "solid-js"; - -// Wrap Solid"s ErrorBoundary to automatically capture exceptions -const SentryErrorBoundary = Sentry.withSentryErrorBoundary(ErrorBoundary); - -export default function SomeComponent() { - return ( -
Error: {err.message}
}> -
Some Component
- - ); -} -``` + diff --git a/docs/platforms/javascript/guides/solidstart/index.mdx b/docs/platforms/javascript/guides/solidstart/index.mdx index b37eaf99f4b0c..6ec5ff0f228c1 100644 --- a/docs/platforms/javascript/guides/solidstart/index.mdx +++ b/docs/platforms/javascript/guides/solidstart/index.mdx @@ -1,15 +1,45 @@ --- title: SolidStart -description: SolidStart is a framework for full-stack web apps and websites. Learn how to set it up with Sentry. +description: Learn how to set up Sentry in your SolidStart application and capture your first errors. sdk: sentry.javascript.solidstart categories: - browser - server --- -## Install + + This SDK is currently in **beta**. Beta features are still in progress and may + have bugs. Please reach out on + [GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose) if + you have any feedback or concerns. + + + + This SDK guide is specifically for SolidStart. For instrumenting your Solid + app, see our [Solid SDK](/platforms/javascript/guides/solid). + + + + +## Step 1: Install -Sentry captures data by using an SDK within your application's runtime. +Choose the features you want to configure, and this guide will show you how: + + + + + +### Install the Sentry SDK + +Run the command for your preferred package manager to add the Sentry SDK to your application: ```bash {tabTitle:npm} npm install @sentry/solidstart --save @@ -23,81 +53,116 @@ yarn add @sentry/solidstart pnpm add @sentry/solidstart ``` -## Configure +## Step 2: Configure -Configuration should happen as early as possible in your application's lifecycle. +You need to initialize and configure the Sentry SDK in two places: the client side and the server side. -Initialize the Sentry SDK in your `src/entry-client.tsx` file. + + The examples in this guide will use TypeScript with a `src` folder structure. + Make sure to adjust the file paths and extensions (`.js`, `.jsx`, `.ts`, + `.tsx`) to match your project setup. + + +### Configure Client-side Sentry + +Import and initialize the Sentry SDK in your `/src/entry-client.tsx` file. -If you're using Solid Router, add the `solidRouterBrowserTracingIntegration` to collect meaningful performance data about the health of your page loads and associated requests. + + If you're using Solid Router, make sure to import and add the + `solidRouterBrowserTracingIntegration` to enable tracing in your app: + ```jsx {filename:src/entry-client.tsx} import * as Sentry from "@sentry/solidstart"; +// ___PRODUCT_OPTION_START___ performance +// import solidRouterBrowserTracingIntegration if you're using Solid Router import { solidRouterBrowserTracingIntegration } from "@sentry/solidstart/solidrouter"; +// ___PRODUCT_OPTION_END___ performance import { mount, StartClient } from "@solidjs/start/client"; Sentry.init({ dsn: "___PUBLIC_DSN___", - // Adds request headers and IP for users, for more info visit: // https://docs.sentry.io/platforms/javascript/guides/solidstart/configuration/options/#sendDefaultPii sendDefaultPii: true, - - integrations: [solidRouterBrowserTracingIntegration()], - tracesSampleRate: 1.0, // Capture 100% of the transactions + integrations: [ + // ___PRODUCT_OPTION_START___ performance + // add solidRouterBrowserTracingIntegration if you're using Solid Router + solidRouterBrowserTracingIntegration(), + // ___PRODUCT_OPTION_END___ performance + // ___PRODUCT_OPTION_START___ session-replay + // Replay may only be enabled for the client-side + Sentry.replayIntegration(), + // ___PRODUCT_OPTION_END___ session-replay + // ___PRODUCT_OPTION_START___ user-feedback + Sentry.feedbackIntegration({ + // Additional SDK configuration goes in here, for example: + colorScheme: "system", + }), + // ___PRODUCT_OPTION_END___ user-feedback + ], + // ___PRODUCT_OPTION_START___ performance + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for tracing. + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance + // ___PRODUCT_OPTION_START___ session-replay + + // Capture Replay for 10% of all sessions, + // plus for 100% of sessions with an error + // Learn more at + // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ session-replay + // ___PRODUCT_OPTION_START___ logs + + // Enable logs to be sent to Sentry + enableLogs: true, + // ___PRODUCT_OPTION_END___ logs }); mount(() => , document.getElementById("app")); ``` - - -Depending on the configuration of your SolidStart project, the file structure may differ from the code listed on this page. -For example, for JavaScript projects files end in `.js` and `.jsx` while we use TypeScript snippets here ending in `.ts` and `.tsx`. - - - -### Server-side Setup +### Configure Server-side Sentry -Create an instrument file `instrument.server.ts` in your `src` folder. In this file, initialize the Sentry SDK for your server. +Create a file named `instrument.server.ts` in your `src` folder. In this file, initialize and import Sentry for your server: ```javascript {filename:src/instrument.server.ts} import * as Sentry from "@sentry/solidstart"; Sentry.init({ dsn: "___PUBLIC_DSN___", - // Adds request headers and IP for users, for more info visit: // https://docs.sentry.io/platforms/javascript/guides/solidstart/configuration/options/#sendDefaultPii sendDefaultPii: true, - - tracesSampleRate: 1.0, // Capture 100% of the transactions + // ___PRODUCT_OPTION_START___ performance + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for tracing. + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance + // ___PRODUCT_OPTION_START___ logs + + // Enable logs to be sent to Sentry + enableLogs: true, + // ___PRODUCT_OPTION_END___ logs }); ``` -Wrap your SolidStart config with `withSentry`, so this file gets added to your build output. With the default server preset, you can find the file here: `.output/server/instrument.server.mjs`. +### Server Instrumentation -```javascript {filename:app.config.ts} {5-12} -import { withSentry } from "@sentry/solidstart"; -import { defineConfig } from "@solidjs/start/config"; +The Sentry SDK provides [middleware lifecycle](https://docs.solidjs.com/solid-start/advanced/middleware) handlers that enhance the data collected by Sentry on the server side, enabling distributed tracing between the client and server. -export default defineConfig( - withSentry( - { - /* Your SolidStart config */ - }, - { - /* Your Sentry build-time config (such as source map upload options) */ - } - ) -); -``` - -### Instrumentation - -The Sentry SDK provides [middleware lifecycle](https://docs.solidjs.com/solid-start/advanced/middleware) handlers to enhance data collected by Sentry on the server side by enabling distributed tracing between the client and server. - -Complete the setup by adding `sentryBeforeResponseMiddleware` to your `src/middleware.ts` file. If you don't have a `src/middleware.ts` file yet, create one: +Create or update your `src/middleware.ts` file and add the `sentryBeforeResponseMiddleware` handler: ```typescript {filename:src/middleware.ts} {6} import { sentryBeforeResponseMiddleware } from "@sentry/solidstart"; @@ -111,22 +176,31 @@ export default createMiddleware({ }); ``` -And specify `src/middleware.ts` in `app.config.ts`: +Wrap your SolidStart config in `app.config.ts` with `withSentry` so that the instrumentation file gets included in your build output. +Then, specify the middleware that you've just created: -```typescript {filename:app.config.ts} {7} +```javascript {filename:app.config.ts} {5-15} import { withSentry } from "@sentry/solidstart"; import { defineConfig } from "@solidjs/start/config"; export default defineConfig( - withSentry({ - // other SolidStart config options... - middleware: "./src/middleware.ts", - }) + withSentry( + { + // other SolidStart config options... + middleware: "./src/middleware.ts", + }, + { + // Your Sentry build-time config (such as source map upload options) + // optional: if your `instrument.server.ts` file is not located inside `src` + instrumentation: "./mypath/instrument.server.ts", + } + ) ); ``` -If you previously added the `solidRouterBrowserTracingIntegration` integration to `Sentry.init` in `src/entry-client.tsx`, wrap your Solid Router with `withSentryRouterRouting`. -This creates a higher order component, which will enable Sentry to collect navigation spans. + +### Configure Solid Router +If you're using Solid Router and the Sentry `solidRouterBrowserTracingIntegration` integration, wrap your Solid Router with `withSentryRouterRouting` to enable Sentry to collect navigation spans: ```tsx {filename:app.tsx} {5,9,11} import { Router } from "@solidjs/router"; @@ -144,9 +218,19 @@ export default function App() { } ``` -### Run your application + -Add an `--import` flag directly or to the `NODE_OPTIONS` environment variable wherever you run your application to import `.output/server/instrument.server.mjs `. +### Run Your Application + +Instrumentation needs to happen as early as possible to make sure Sentry works as intended. To do this, add an `--import` flag to the `NODE_OPTIONS` environment variable when you run your application and set it to import the instrumentation file created by the build output: `.output/server/instrument.server.mjs`. + + + +Run your build command to generate the `instrument.server.mjs` file before running your app. Depending on your build preset, the location of the file can differ. To find out where the file is located, monitor the build log output for: + +`[Sentry SolidStart withSentry] Successfully created /my/project/path/.output/server/instrument.server.mjs.` + + For example, update your scripts in `package.json`. @@ -159,20 +243,17 @@ For example, update your scripts in `package.json`. } ``` - - If you experience any issues during the server-side setup, read through the - different installation methods - or check out{" "} - Troubleshooting. - +If you're not able to use the `--import` flag, check the alternative installation methods. -## Add Readable Stack Traces to Errors +## Step 3: Capture Solid Errors -To upload source maps, you need to pass an auth token to `withSentry` explicitly with the `authToken` -option. We highly recommend to store this token in an environment variable for security. You can also use the `SENTRY_AUTH_TOKEN` environment variable or have an `.env.sentry-build-plugin` file in the -working directory when building your project. +To automatically report exceptions from inside a component tree to Sentry, wrap Solid's `ErrorBoundary` with Sentry's helper function: -Update your `app.config.ts`: + + +## Step 4: Add Readable Stack Traces With Source Maps (Optional) + +To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slug in your SolidStart configuration: ```TypeScript {filename:app.config.ts} import { withSentry } from '@sentry/solidstart'; @@ -193,7 +274,7 @@ export default defineConfig( ); ``` -Store your token in an environment variable: +To keep your auth token secure, always store it in an environment variable instead of directly in your files: @@ -201,7 +282,7 @@ Store your token in an environment variable: SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ ``` -or create a `.env.sentry-build-plugin` file: +Alternatively, you can create a `.env.sentry-build-plugin` file: ```bash {filename:.env.sentry-build-plugin} SENTRY_ORG="___ORG_SLUG___" @@ -209,29 +290,95 @@ SENTRY_PROJECT="___PROJECT_SLUG___" SENTRY_AUTH_TOKEN="___ORG_AUTH_TOKEN___" ``` -We recommend adding the auth token to your CI/CD environment as an environment variable. +## Step 5: Avoid Ad Blockers With Tunneling (Optional) + + + +## Step 6: Verify Your Setup + +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -## Verify +### Issues -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +To verify that Sentry captures errors and creates issues in your Sentry project, add a test button to an existing page or create a new one: ```javascript ``` -This snippet adds a button that throws an error in a Solid component. + + Open the page in a browser and click the button to trigger a frontend error. + - + -Learn more about manually capturing an error or message in our Usage documentation. + +### Tracing - +To test tracing, create a test API route like `src/routes/sentry-test.tsx`: + +```javascript {filename:sentry-test.tsx} +export async function GET() { + throw new Error("Sentry Example API Route Error"); +} +``` + +Next, update your test button to call this route and throw an error if the response isn't `ok`: + +```javascript + +``` + +Open the page in the browser and click the button to trigger a frontend error, an error in the API route, and a trace to measure the time it takes for the API request to complete. + + + +### View Captured Data in Sentry + +Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). + + + +## Next Steps + +At this point, you should have integrated Sentry into your SolidStart 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: + +- Learn how to manually capture errors +- Continue to customize your configuration +- Learn how to make use of SolidStart-specific features +- Get familiar with [Sentry's product features](/) like tracing, insights, and alerts + + + +- If you encountered issues with setting up Sentry, review alternative installation methods +- Find various topics in Troubleshooting +- [Get support](https://sentry.zendesk.com/hc/en-us/) -To view and resolve the recorded error, log into [sentry.io](https://sentry.io) and select your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. + diff --git a/platform-includes/getting-started-capture-errors/javascript.solidstart.mdx b/platform-includes/getting-started-capture-errors/javascript.solidstart.mdx new file mode 100644 index 0000000000000..df859a2505a37 --- /dev/null +++ b/platform-includes/getting-started-capture-errors/javascript.solidstart.mdx @@ -0,0 +1,15 @@ +```jsx +import * as Sentry from "@sentry/solidstart"; +import { ErrorBoundary } from "solid-js"; + +// Wrap Solid"s ErrorBoundary to automatically capture exceptions +const SentryErrorBoundary = Sentry.withSentryErrorBoundary(ErrorBoundary); + +export default function SomeComponent() { + return ( +
Error: {err.message}
}> +
Some Component
+ + ); +} +```