From da3d3a7e41336381ae8a62aa78f8f79576c6942c Mon Sep 17 00:00:00 2001 From: JPeer264 Date: Fri, 11 Sep 2026 18:05:47 +0200 Subject: [PATCH] docs(solidstart): Document the SolidStart 2 setup `npm install @solidjs/start` gives SolidStart 2 today, and the guide described SolidStart 1 only. On SolidStart 2 there is no `app.config.ts`, `@solidjs/start/config` exports no `defineConfig`, the build emits no `.output/server/instrument.server.mjs`, and vinxi is not installed, so the documented config was ignored and the documented start command exited with `ERR_MODULE_NOT_FOUND`. Give each affected step a SolidStart 2 tab next to the SolidStart 1 one: - Server init moves to a Nitro startup plugin, `server/plugins/sentry.ts`. - The build config moves to `vite.config.ts` with `sentrySolidStart` from `@sentry/solidstart/vite`. - The server starts with a plain `node .output/server/index.mjs`. The Vite plugin instruments dependencies at build time, so no preload is needed. - Source map options move into `sentrySolidStart()`. Add a SolidStart prerequisites include naming the supported versions, so readers know which set of tabs applies to them. The guide fell back to the default include, which names no framework version at all. Scope the `--import`, limited server tracing and dynamic import installation methods to SolidStart 1, since all three configure `withSentry` in `app.config.ts`. Import `sentryBeforeResponseMiddleware` from `@sentry/solidstart`. The package exports `.`, `./solidrouter` and `./vite`, so the documented `@sentry/solidstart/middleware` path failed with `ERR_PACKAGE_PATH_NOT_EXPORTED`. Refs SDK-1515 Co-Authored-By: Claude Opus 5 --- .../guides/solidstart/features/middleware.mdx | 8 +- .../javascript/guides/solidstart/index.mdx | 89 ++++++++++++++++--- .../guides/solidstart/install/cli-import.mdx | 8 ++ .../solidstart/install/dynamic-import.mdx | 46 ++++++---- .../guides/solidstart/install/index.mdx | 4 +- .../install/limited-server-tracing.mdx | 6 ++ .../how-to-use/javascript.solidstart.mdx | 22 ++--- .../javascript.solidstart.mdx | 15 ++++ 8 files changed, 154 insertions(+), 44 deletions(-) create mode 100644 platform-includes/getting-started-prerequisites/javascript.solidstart.mdx diff --git a/docs/platforms/javascript/guides/solidstart/features/middleware.mdx b/docs/platforms/javascript/guides/solidstart/features/middleware.mdx index feb69bae2b524..39de896c99360 100644 --- a/docs/platforms/javascript/guides/solidstart/features/middleware.mdx +++ b/docs/platforms/javascript/guides/solidstart/features/middleware.mdx @@ -8,8 +8,8 @@ The Sentry middleware enhances the data collected by Sentry on the server side b Add the Sentry middleware to your `middleware.ts` file. If you don't have a `middleware.ts` file yet, create one: ```typescript {filename:middleware.ts} -import { sentryBeforeResponseMiddleware } from '@sentry/solidstart/middleware'; -import { createMiddleware } from '@solidjs/start/middleware'; +import { sentryBeforeResponseMiddleware } from "@sentry/solidstart"; +import { createMiddleware } from "@solidjs/start/middleware"; export default createMiddleware({ onBeforeResponse: [ @@ -22,10 +22,10 @@ export default createMiddleware({ And specify `middleware.ts` in `app.config.ts`: ```typescript {filename:app.config.ts} -import { defineConfig } from '@solidjs/start/config'; +import { defineConfig } from "@solidjs/start/config"; export default defineConfig({ // ... - middleware: './src/middleware.ts', + middleware: "./src/middleware.ts", }); ``` diff --git a/docs/platforms/javascript/guides/solidstart/index.mdx b/docs/platforms/javascript/guides/solidstart/index.mdx index aad5f768ad29c..d9c4a20da6f77 100644 --- a/docs/platforms/javascript/guides/solidstart/index.mdx +++ b/docs/platforms/javascript/guides/solidstart/index.mdx @@ -149,12 +149,32 @@ mount(() => , document.getElementById("app")); -Create a file named `instrument.server.ts` in your `src` folder. In this file, initialize and import Sentry for your server: +Initialize Sentry on the server. On SolidStart 2, do this in a Nitro startup plugin, which runs once when the server starts. On SolidStart 1, create an `instrument.server.ts` file in your `src` folder. -```javascript {filename:src/instrument.server.ts} +```typescript {tabTitle:SolidStart 2} {filename:server/plugins/sentry.ts} {mdExpandTabs} +import * as Sentry from "@sentry/solidstart"; +import { definePlugin } from "nitro"; + +export default definePlugin(() => { + Sentry.init({ + dsn: "___PUBLIC_DSN___", + // ___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 + }); +}); +``` + +```javascript {tabTitle:SolidStart 1} {filename:src/instrument.server.ts} import * as Sentry from "@sentry/solidstart"; Sentry.init({ @@ -205,13 +225,29 @@ export default createMiddleware({ -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: +Add the Sentry plugin to your build config and register the middleware you just created. On SolidStart 2, add `sentrySolidStart` to `vite.config.ts`. On SolidStart 1, wrap your `app.config.ts` with `withSentry` so that the instrumentation file gets included in your build output. -```javascript {filename:app.config.ts} {5-15} +```typescript {tabTitle:SolidStart 2} {filename:vite.config.ts} {mdExpandTabs} +import { sentrySolidStart } from "@sentry/solidstart/vite"; +import { solidStart } from "@solidjs/start/config"; +import { nitro } from "nitro/vite"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [ + solidStart({ + middleware: "./src/middleware.ts", + }), + sentrySolidStart(), + nitro(), + ], +}); +``` + +```javascript {tabTitle:SolidStart 1} {filename:app.config.ts} {5-15} import { withSentry } from "@sentry/solidstart"; import { defineConfig } from "@solidjs/start/config"; @@ -274,24 +310,35 @@ export default function App() { -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`. +On SolidStart 2, the Vite plugin instruments your dependencies at build time, so the server needs no preload flag. Build with `vite build` and start the output directly. + +On SolidStart 1, instrumentation has to happen as early as possible, so add an `--import` flag pointing at the instrumentation file that the build output creates: `.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: +On SolidStart 1, 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.` -If you're not able to use the `--import` flag, check the alternative installation methods. +If you're not able to use the `--import` flag on SolidStart 1, check the alternative installation methods. For example, update your scripts in `package.json`: -```json {filename:package.json} +```json {tabTitle:SolidStart 2} {filename:package.json} {mdExpandTabs} +{ + "scripts": { + "build": "vite build", + "start": "node .output/server/index.mjs" + } +} +``` + +```json {tabTitle:SolidStart 1} {filename:package.json} { "scripts": { "start:vinxi": "NODE_OPTIONS='--import ./.output/server/instrument.server.mjs ' vinxi start", @@ -327,12 +374,32 @@ To automatically report exceptions from inside a component tree to Sentry, wrap -To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slug in your SolidStart configuration: +To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slug to the Sentry plugin in your build config: -```TypeScript {filename:app.config.ts} +```typescript {tabTitle:SolidStart 2} {filename:vite.config.ts} {mdExpandTabs} +import { sentrySolidStart } from "@sentry/solidstart/vite"; +import { solidStart } from "@solidjs/start/config"; +import { nitro } from "nitro/vite"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [ + solidStart(), + sentrySolidStart({ + org: "___ORG_SLUG___", + project: "___PROJECT_SLUG___", + // store your auth token in an environment variable + authToken: process.env.SENTRY_AUTH_TOKEN, + }), + nitro(), + ], +}); +``` + +```TypeScript {tabTitle:SolidStart 1} {filename:app.config.ts} import { withSentry } from '@sentry/solidstart'; import { defineConfig } from '@solidjs/start/config'; diff --git a/docs/platforms/javascript/guides/solidstart/install/cli-import.mdx b/docs/platforms/javascript/guides/solidstart/install/cli-import.mdx index ea23fddb76902..1a179420847cb 100644 --- a/docs/platforms/javascript/guides/solidstart/install/cli-import.mdx +++ b/docs/platforms/javascript/guides/solidstart/install/cli-import.mdx @@ -4,6 +4,12 @@ sidebar_order: 1 description: "Learn how to use the node --import CLI flag." --- + + +This installation method applies to SolidStart 1. On SolidStart 2, the Sentry Vite plugin instruments your dependencies at build time, so no preload is needed. See the SolidStart guide. + + + ## Understanding the `--import` CLI Flag The [`--import` CLI flag](https://nodejs.org/api/cli.html#--importmodule) in Node is the default way in ESM to preload a specified module at startup. @@ -54,11 +60,13 @@ Consult your hosting provider's documentation for specific implementation detail Most deployment platforms support this through two primary methods: #### Option 1: Direct CLI Flag + ```bash node --import ./.output/server/instrument.server.mjs your-server-entry.mjs ``` #### Option 2: Environment Variable + ```bash NODE_OPTIONS='--import ./.output/server/instrument.server.mjs' ``` diff --git a/docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx b/docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx index a4bd655734da4..9b5d5a79302d6 100644 --- a/docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx +++ b/docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx @@ -4,12 +4,19 @@ sidebar_order: 3 description: "Learn about how the SolidStart SDK leverages dynamic input() in the build output." --- + + +This installation method applies to SolidStart 1. On SolidStart 2, the Sentry Vite plugin instruments your dependencies at build time, so no preload is needed. See the SolidStart guide. + + + ## Understanding the `import()` expression This setting is experimental as it is not guaranteed to work with every setup and the underlying functionality could change. - We recommend reading the guide for installing the SDK with the CLI flag `--import` or limited server tracing +We recommend reading the guide for installing the SDK with the CLI flag `--import` or limited server tracing + The `import()` expression, or dynamic import, enables flexible, conditional module loading in ESM. @@ -31,15 +38,17 @@ You can also check out the guide for installing the SDK with the + +This installation method applies to SolidStart 1. On SolidStart 2, the Sentry Vite plugin instruments your dependencies at build time, so no preload is needed. See the SolidStart guide. + + + ## Understanding Limited Server Tracing Sentry needs to be initialized before the rest of the application runs. diff --git a/platform-includes/distributed-tracing/how-to-use/javascript.solidstart.mdx b/platform-includes/distributed-tracing/how-to-use/javascript.solidstart.mdx index 02a15881625cc..81a950c32070e 100644 --- a/platform-includes/distributed-tracing/how-to-use/javascript.solidstart.mdx +++ b/platform-includes/distributed-tracing/how-to-use/javascript.solidstart.mdx @@ -3,8 +3,8 @@ To set up distributed tracing, use Sentry's middleware to inject tracing informa Create or modify the `middleware.ts` file and import and add `sentryBeforeResponseMiddleware` ```typescript {filename: middleware.ts} -import { sentryBeforeResponseMiddleware } from '@sentry/solidstart/middleware'; -import { createMiddleware } from '@solidjs/start/middleware'; +import { sentryBeforeResponseMiddleware } from "@sentry/solidstart"; +import { createMiddleware } from "@solidjs/start/middleware"; export default createMiddleware({ onBeforeResponse: [ @@ -12,16 +12,16 @@ export default createMiddleware({ // Add your other middleware handlers after `sentryBeforeResponseMiddleware` ], }); -```` +``` If you didn't use a middleware before, don't forget to specify it in `app.config.ts` ```typescript {filename: app.config.ts} -import { defineConfig } from '@solidjs/start/config'; +import { defineConfig } from "@solidjs/start/config"; export default defineConfig({ // ... - middleware: './src/middleware.ts', + middleware: "./src/middleware.ts", }); ``` @@ -66,8 +66,8 @@ Sentry.init({ This tells Sentry to pass trace headers across the following paths: -* Your main API server (where product data comes from) -* Your authentication server (where logins happen) +- Your main API server (where product data comes from) +- Your authentication server (where logins happen) This way, if a customer experiences an error during checkout, or you want to check the performance of a specific endpoint, you can see the complete path their request took across these different services. @@ -81,16 +81,16 @@ Sentry.init({ tracePropagationTargets: [ "https://api.myapp.com", "https://media.myapp.com", - /^\/local-api\// + /^\/local-api\//, ], }); ``` This configuration lets your app track user actions across: -* Your main API server (handles most app functions) -* Your media server (handles images, videos, etc.) -* Any local API endpoints in your app +- Your main API server (handles most app functions) +- Your media server (handles images, videos, etc.) +- Any local API endpoints in your app If your app crashes while a user is uploading a photo, you can trace exactly where the problem occurred - in the app itself, the main API, or the media service. diff --git a/platform-includes/getting-started-prerequisites/javascript.solidstart.mdx b/platform-includes/getting-started-prerequisites/javascript.solidstart.mdx new file mode 100644 index 0000000000000..2aad75db297c4 --- /dev/null +++ b/platform-includes/getting-started-prerequisites/javascript.solidstart.mdx @@ -0,0 +1,15 @@ +## Prerequisites + +You need: + +- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) +- Your application up and running +- SolidStart version `1.0.0`+ or `2.0.0`+ + + + +SolidStart 2 dropped vinxi and `app.config.ts`, so the two versions are set up differently. Check the `@solidjs/start` version in your `package.json`; a new project installs SolidStart 2. + +Where this guide shows **SolidStart 2** and **SolidStart 1** tabs, pick the one that matches your version. The installation methods apply to SolidStart 1 only. + +