From 14a749a33bff7756cc6f13267e43d70e573cdba9 Mon Sep 17 00:00:00 2001
From: Andrei Borza <andrei.borza@sentry.io>
Date: Wed, 25 Sep 2024 14:32:56 +0900
Subject: [PATCH] Update README

---
 packages/solidstart/README.md | 133 +++++++++++++++++++++++++---------
 1 file changed, 97 insertions(+), 36 deletions(-)

diff --git a/packages/solidstart/README.md b/packages/solidstart/README.md
index ceda55838e8d..3bf1663e6c74 100644
--- a/packages/solidstart/README.md
+++ b/packages/solidstart/README.md
@@ -101,16 +101,109 @@ export default defineConfig({
 The Sentry middleware enhances the data collected by Sentry on the server side by enabling distributed tracing between
 the client and server.
 
-### 5. Run your application
+### 5. Configure your application
+
+For Sentry to work properly, SolidStart's `app.config.ts` has to be modified.
+
+#### 5.1 Wrapping the config with `withSentry`
+
+Add `withSentry` from `@sentry/solidstart` and wrap SolidStart's config inside `app.config.ts`.
+
+```typescript
+import { defineConfig } from '@solidjs/start/config'
+import { withSentry } from "@sentry/solidstart";
+
+export default defineConfig(withSentry({
+  // ...
+  middleware: './src/middleware.ts',
+}))
+
+```
+
+#### 5.2 Generate source maps and build `instrument.server.ts`
+
+Sentry relies on running `instrument.server.ts` as early as possible. Add the `sentrySolidStartVite` plugin
+from `@sentry/solidstart` to your `app.config.ts`. This takes care of building `instrument.server.ts` and placing it alongside the server entry file.
+
+To upload source maps, configure an auth token. Auth tokens can be passed to the plugin explicitly with the `authToken` option, with a
+`SENTRY_AUTH_TOKEN` environment variable, or with an `.env.sentry-build-plugin` file in the working directory when
+building your project. We recommend you add the auth token to your CI/CD environment as an environment variable.
+
+Learn more about configuring the plugin in our
+[Sentry Vite Plugin documentation](https://www.npmjs.com/package/@sentry/vite-plugin).
+
+```typescript
+// app.config.ts
+import { defineConfig } from '@solidjs/start/config';
+import { sentrySolidStartVite, withSentry } from '@sentry/solidstart';
+
+export default defineConfig(withSentry({
+  // ...
+  middleware: './src/middleware.ts',
+  vite: {
+    plugins: [
+      sentrySolidStartVite({
+        org: process.env.SENTRY_ORG,
+        project: process.env.SENTRY_PROJECT,
+        authToken: process.env.SENTRY_AUTH_TOKEN,
+        debug: true,
+      }),
+    ],
+  },
+  // ...
+}));
+```
+
+### 6. Run your application
 
 Then run your app
 
 ```bash
-NODE_OPTIONS='--import=./instrument.server.mjs' yarn start
-# or
-NODE_OPTIONS='--require=./instrument.server.js' yarn start
+NODE_OPTIONS='--import=./.output/server/instrument.server.mjs' yarn start
+```
+
+⚠️ **Note build presets** ⚠️  
+Depending on [build preset](https://nitro.unjs.io/deploy), the location of `instrument.server.mjs` differs.
+To find out where `instrument.server.mjs` is located, monitor the build log output for
+
+```bash
+[Sentry SolidStart withSentry] Successfully created /my/project/path/.output/server/instrument.server.mjs.
+```
+
+
+⚠️ **Note for platforms without the ability to modify `NODE_OPTIONS` or use `--import`** ⚠️  
+Depending on where the application is deployed to, it might not be possible to modify or use `NODE_OPTIONS` to
+import `instrument.server.mjs`.
+
+For such platforms, we offer the `experimental_basicServerTracing` flag to add a top 
+level import of `instrument.server.mjs` to the server entry file.
+
+```typescript
+// app.config.ts
+import { defineConfig } from '@solidjs/start/config';
+import { sentrySolidStartVite, withSentry } from '@sentry/solidstart';
+
+export default defineConfig(withSentry({
+  // ...
+  middleware: './src/middleware.ts',
+  vite: {
+    plugins: [
+      sentrySolidStartVite({
+        org: process.env.SENTRY_ORG,
+        project: process.env.SENTRY_PROJECT,
+        authToken: process.env.SENTRY_AUTH_TOKEN,
+        debug: true,
+      }),
+    ],
+  },
+  // ...
+}, { experimental_basicServerTracing: true }));
 ```
 
+This has a **fundamental restriction**: It only supports limited performance instrumentation. 
+**Only basic http instrumentation** will work, and no DB or framework-specific instrumentation will be available.
+
+
 # Solid Router
 
 The Solid Router instrumentation uses the Solid Router library to create navigation spans to ensure you collect
@@ -156,35 +249,3 @@ render(
   document.getElementById('root'),
 );
 ```
-
-## Uploading Source Maps
-
-To upload source maps, add the `sentrySolidStartVite` plugin from `@sentry/solidstart` to your `app.config.ts` and
-configure an auth token. Auth tokens can be passed to the plugin explicitly with the `authToken` option, with a
-`SENTRY_AUTH_TOKEN` environment variable, or with an `.env.sentry-build-plugin` file in the working directory when
-building your project. We recommend you add the auth token to your CI/CD environment as an environment variable.
-
-Learn more about configuring the plugin in our
-[Sentry Vite Plugin documentation](https://www.npmjs.com/package/@sentry/vite-plugin).
-
-```typescript
-// app.config.ts
-import { defineConfig } from '@solidjs/start/config';
-import { sentrySolidStartVite } from '@sentry/solidstart';
-
-export default defineConfig({
-  // ...
-
-  vite: {
-    plugins: [
-      sentrySolidStartVite({
-        org: process.env.SENTRY_ORG,
-        project: process.env.SENTRY_PROJECT,
-        authToken: process.env.SENTRY_AUTH_TOKEN,
-        debug: true,
-      }),
-    ],
-  },
-  // ...
-});
-```