docs(solidstart): Add docs for installation methods (#12335)

* docs(solidstart): Add docs for installation methods

* review suggestions

Author: s1gr1d

docs/platforms/javascript/common/install/loader.mdx

@@ -19,6 +19,7 @@ notSupported:
   - javascript.wasm
   - javascript.remix
   - javascript.react-router
+  - javascript.solidstart
   - javascript.svelte
   - javascript.sveltekit
   - javascript.node

docs/platforms/javascript/guides/nuxt/install/cli-import.mdx

@@ -55,7 +55,7 @@ Most deployment platforms support this through two primary methods:
 
 #### Option 1: Direct CLI Flag
 ```bash
-node --import .output/server/sentry.server.config.mjs your-server-entry.mjs
+node --import ./.output/server/sentry.server.config.mjs your-server-entry.mjs
 ```
 
 #### Option 2: Environment Variable

docs/platforms/javascript/guides/solidstart/install/cli-import.mdx

@@ -0,0 +1,64 @@
+---
+title: --import CLI flag (default)
+sidebar_order: 1
+description: "Learn how to use the node --import CLI flag."
+---
+
+## 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.
+Setting this CLI flag is crucial for ensuring proper server-side initialization, as Sentry needs to be initialized before the application runs.
+This will register Sentry's [loader hook](https://nodejs.org/api/module.html#customization-hooks) and therefore enable proper instrumentation of ESM modules.
+
+## Scenarios where `--import` does not work
+
+- You're unable to add Node CLI flags or environment variables scoped to the function runtime, meaning these variables aren't applied in other scopes, such as build time.
+- You don't know the path to the SolidStart server folder in the build output
+- At this time, it isn't possible to properly configure `--import` in **Netlify**.
+- At this time, it isn't possible to properly configure `--import` in **Vercel**.
+
+If any of those points apply to you, you cannot use the `--import` flag to initialize Sentry on the server-side.
+Check out the guide for using <PlatformLink to="/install/limited-server-tracing">limited server tracing</PlatformLink> instead.
+
+## Initializing Sentry with `--import`
+
+By default, the SDK will add the Sentry server instrumentation file to the build output (typically, `.output/server/instrument.server.mjs`).
+
+### 1. Adding `--import` to `node` command
+
+After building your SolidStart app with `vinxi build`, add the `--import` flag followed by the Sentry server instrumentation file path to the `node` command.
+With the default Vinxi Node preset, this typically looks like this:
+
+```bash
+node --import ./.output/server/instrument.server.mjs .output/server/index.mjs
+```
+
+Check the log at the very end of the console output after building the application.
+This will print the node command with the server entry path for your application (`node .output/server/index.mjs` with the Node preset).
+Make sure to update the paths accordingly, especially when using a different Vinxi preset.
+
+To make things easier, add a script in the `package.json`:
+
+```json {filename:package.json}
+{
+  "scripts": {
+    "start": "node --import ./.output/server/instrument.server.mjs .output/server/index.mjs"
+  }
+}
+```
+
+### 2. Adding `--import` flag in production
+
+To be able to set up Sentry in production, the `--import` flag needs to be added wherever you run your application's production build output.
+Consult your hosting provider's documentation for specific implementation details.
+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'
+```

docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx

@@ -0,0 +1,80 @@
+---
+title: Dynamic Import (experimental)
+sidebar_order: 3
+description: "Learn about how the SolidStart SDK leverages dynamic input() in the build output."
+---
+
+## Understanding the `import()` expression
+
+<Alert level='warning'>
+  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 <PlatformLink to="/install/cli-import">CLI flag `--import`</PlatformLink> or <PlatformLink to="/install/limited-server-tracing">limited server tracing</PlatformLink>
+</Alert>
+
+The `import()` expression, or dynamic import, enables flexible, conditional module loading in ESM.
+Node.js will generate a separate module graph for any code wrapped in a dynamic `import()`. This separate graph is evaluated **after** all modules, which are statically `import`ed.
+
+By using the Sentry SolidStart SDK, the server-side application will be wrapped in a dynamic `import()`, while the Sentry instrumentation file will be imported with a static `import`.
+This makes it possible to initialize the Sentry SolidStart SDK at startup, while the Nitro server runtime loads later because it is `import()`ed.
+This early initialization of Sentry is required to correctly set up the SDK's instrumentation of various libraries.
+
+## Scenarios where `import()` doesn't work
+
+Depending on your setup and which version of Vinxi is used (and respectively Nitro, as this runs under the hood), the server-side is sometimes not correctly initialized.
+The build output **must not** include a regular `import` of the Nitro runtime (e.g. `import './chunks/nitro/nitro.mjs'`).
+
+You can also check out the guide for installing the SDK with the <PlatformLink to="/install/cli-import">CLI flag `--import`</PlatformLink> or <PlatformLink to="/install/limited-server-tracing">limited-server-tracing</PlatformLink>.
+
+## Initializing Sentry with Dynamic `import()`
+
+Enable the dynamic `import()` by setting `autoInjectServerSentry`:
+
+```typescript {filename:app.config.ts} {8}
+import { defineConfig } from '@solidjs/start/config';
+import { withSentry } from '@sentry/solidstart';
+
+export default defineConfig(withSentry(
+    {},
+    {
+      autoInjectServerSentry: 'experimental_dynamic-import'
+    })
+ );
+```
+
+After setting this, the Sentry SolidStart SDK will add build-time configuration so that your app will be wrapped with `import()`,
+ensuring that Sentry can be initialized before any other modules.
+
+The SolidStart server entry file will look something like this:
+
+```javascript {filename:.output/server/index.mjs}
+// Note: The file may have some imports and code, related to debug IDs
+Sentry.init({
+  dsn: "..."
+});
+
+import('./chunks/nitro/nitro.mjs').then(function (n) { return n.r; });
+```
+
+## Re-exporting serverless handler functions
+
+Sentry automatically detects serverless handler functions in the build output and re-exports them from the server entry file.
+
+By default, Sentry re-exports functions named `handler`, `server`, and `default` exports. This will work in most cases and no other action is required.
+If your serverless function has a custom name, you can override it with `experimental_entrypointWrappedFunctions`:
+
+```javascript {filename: app.config.ts} {11}
+
+import { defineConfig } from '@solidjs/start/config';
+import { withSentry } from '@sentry/solidstart';
+
+export default defineConfig(withSentry(
+    {},
+    {
+      autoInjectServerSentry: 'experimental_dynamic-import',
+      // Customize detected function names
+      // Default value: ['default', 'handler', 'server']
+      experimental_entrypointWrappedFunctions: ['customFunctionName']
+    })
+ );
+```

docs/platforms/javascript/guides/solidstart/install/index.mdx

@@ -0,0 +1,12 @@
+---
+title: Installation Methods
+sidebar_order: 1.5
+description: "Review our alternate installation methods."
+---
+
+SolidStart uses ES Modules for server-side builds, which requires Sentry to register Node [customization hooks](https://nodejs.org/api/module.html#customization-hooks).
+Those customization hooks need to be registered before the rest of the application.
+
+To be able to run Sentry before the rest of the application and fully monitor the server-side, Sentry can be initialized using one of those two approaches:
+
+<PageGrid />

docs/platforms/javascript/guides/solidstart/install/limited-server-tracing.mdx

@@ -0,0 +1,41 @@
+---
+title: Limited Server Tracing
+sidebar_order: 2
+description: "Learn how to set up the SolidStart SDK with limited server tracing by adding a top-level import to the build output."
+---
+
+## Understanding Limited Server Tracing
+
+Sentry needs to be initialized before the rest of the application runs.
+If the default way of adding an <PlatformLink to="/install/cli-import">`--import` CLI flag</PlatformLink> doesn't work for you,
+enable the SDK to add a top-level `import`.
+
+The automatically added top-level `import` will then import the Sentry server-side config at the top of the SolidStart server entry file.
+In this case, Sentry isn’t initialized before the app starts, but is set up as early as possible.
+
+<Alert level='warning' title='Restrictions of this installation method'>
+  This installation method has fundamental restrictions:
+  - Only basic `http` and `fetch` instrumentation will work.
+  - No DB or framework-specific instrumentation will be available.
+
+  We recommend using this only if the `--import` flag is not an option for you.
+</Alert>
+
+## Initializing Sentry With a Top-level `import`
+
+Enable the top-level `import` by setting `autoInjectServerSentry`:
+
+```typescript {filename:app.config.ts} {8}
+import { defineConfig } from '@solidjs/start/config';
+import { withSentry } from '@sentry/solidstart';
+
+export default defineConfig(withSentry(
+    {},
+    {
+    autoInjectServerSentry: 'top-level-import'
+    })
+ );
+```
+
+By default, the SDK will add the Sentry server instrumentation file to the build output (typically, `.output/server/instrument.server.mjs`).
+The SDK will then automatically import this file at the top of the SolidStart server entry file in the build output.

platform-includes/getting-started-config/javascript.solidstart.mdx

@@ -26,18 +26,9 @@ mount(() => <StartClient />, document.getElementById('app'));
 
 ### Server-side Setup
 
-Create an instrument file `instrument.server.mjs`, initialize the Sentry SDK and deploy it alongside your application.
-For example by placing it in the `public` folder.
+Create an instrument file `instrument.server.ts` in your `src` folder. In this file, initialize the Sentry SDK for your server.
 
-<Alert>
-
-  Placing `instrument.server.mjs` inside the `public` folder makes it accessible to the outside world.
-  Consider blocking requests to this file or finding a more appropriate location which your backend can access.
-
-</Alert>
-
-
-```javascript {filename:public/instrument.server.mjs}
+```javascript {filename:src/instrument.server.ts}
 import * as Sentry from '@sentry/solidstart';
 
 Sentry.init({
@@ -46,13 +37,31 @@ Sentry.init({
 });
 ```
 
+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`.
+
+```javascript {filename:app.config.ts} {5-12}
+import { withSentry } from '@sentry/solidstart';
+import { defineConfig } from '@solidjs/start/config';
+
+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:
 
-```typescript {filename:src/middleware.ts}
+```typescript {filename:src/middleware.ts} {6}
 import { sentryBeforeResponseMiddleware } from '@sentry/solidstart';
 import { createMiddleware } from '@solidjs/start/middleware';
 
@@ -66,19 +75,22 @@ export default createMiddleware({
 
 And specify `src/middleware.ts` in `app.config.ts`:
 
-```typescript {filename:app.config.ts}
+```typescript {filename:app.config.ts} {7}
+import { withSentry } from '@sentry/solidstart';
 import { defineConfig } from '@solidjs/start/config';
 
-export default defineConfig({
-  // ...
-  middleware: './src/middleware.ts',
-});
+export default defineConfig(
+  withSentry({
+    // other SolidStart config options...
+    middleware: './src/middleware.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.
 
-```tsx {filename:app.tsx}
+```tsx {filename:app.tsx} {5,9,11}
 import { Router } from "@solidjs/router";
 import { FileRoutes } from "@solidjs/start/router";
 import { withSentryRouterRouting } from '@sentry/solidstart/solidrouter'
@@ -96,13 +108,22 @@ export default function App() {
 
 ### Run your application
 
-Add an `--import` flag to the `NODE_OPTIONS` environment variable wherever you run your application to import `public/instrument.server.mjs`.
+Add an `--import` flag directly or to the `NODE_OPTIONS` environment variable wherever you run your application to import `.output/server/instrument.server.mjs `.
 
 For example, update your scripts in `package.json`.
 
 ```json {filename:package.json}
 {
   "scripts": {
-    "start": "NODE_OPTIONS='--import ./public/instrument.server.mjs' vinxi start",
+    "start:vinxi": "NODE_OPTIONS='--import ./.output/server/instrument.server.mjs ' vinxi start",
+    "start:node": "node --import ./.output/server/instrument.server.mjs .output/server/index.mjs"
   }
 }
+```
+
+<Alert level="warning">
+  If you experience any issues during the server-side setup, read through the different <PlatformLink to="/install">installation methods</PlatformLink>
+  or check out <PlatformLink to="/troubleshooting">Troubleshooting</PlatformLink>.
+</Alert>
+
+