instrument file path configurable

Author: nicohrubec

packages/tanstackstart-react/src/vite/copyInstrumentationFile.ts

@@ -4,14 +4,17 @@ import * as path from 'path';
 import type { Plugin, ResolvedConfig } from 'vite';
 
 /**
- * Creates a Vite plugin that copies the user's `instrument.server.mjs` file
+ * Creates a Vite plugin that copies the user's instrumentation file
  * to the server build output directory after the build completes.
  *
+ * By default, copies `instrument.server.mjs` from the project root.
+ * A custom file path can be provided via `instrumentationFilePath`.
+ *
  * Supports:
  * - Nitro deployments (reads output dir from the Nitro Vite environment config)
  * - Cloudflare/Netlify deployments (outputs to `dist/server`)
  */
-export function makeCopyInstrumentationFilePlugin(): Plugin {
+export function makeCopyInstrumentationFilePlugin(instrumentationFilePath?: string): Plugin {
   let serverOutputDir: string | undefined;
 
   return {
@@ -57,34 +60,36 @@ export function makeCopyInstrumentationFilePlugin(): Plugin {
         return;
       }
 
-      const instrumentationSource = path.resolve(process.cwd(), 'instrument.server.mjs');
+      const instrumentationFileName = instrumentationFilePath || 'instrument.server.mjs';
+      const instrumentationSource = path.resolve(process.cwd(), instrumentationFileName);
 
       try {
         await fs.promises.access(instrumentationSource, fs.constants.F_OK);
       } catch {
         consoleSandbox(() => {
           // eslint-disable-next-line no-console
           console.warn(
-            '[Sentry TanStack Start] No instrument.server.mjs file found in project root. ' +
+            `[Sentry TanStack Start] No ${instrumentationFileName} file found in project root. ` +
               'The Sentry instrumentation file will not be copied to the build output.',
           );
         });
         return;
       }
 
-      const destination = path.resolve(serverOutputDir, 'instrument.server.mjs');
+      const destinationFileName = path.basename(instrumentationFileName);
+      const destination = path.resolve(serverOutputDir, destinationFileName);
 
       try {
         await fs.promises.mkdir(serverOutputDir, { recursive: true });
         await fs.promises.copyFile(instrumentationSource, destination);
         consoleSandbox(() => {
           // eslint-disable-next-line no-console
-          console.log(`[Sentry TanStack Start] Copied instrument.server.mjs to ${destination}`);
+          console.log(`[Sentry TanStack Start] Copied ${destinationFileName} to ${destination}`);
         });
       } catch (error) {
         consoleSandbox(() => {
           // eslint-disable-next-line no-console
-          console.warn('[Sentry TanStack Start] Failed to copy instrument.server.mjs to build output.', error);
+          console.warn(`[Sentry TanStack Start] Failed to copy ${destinationFileName} to build output.`, error);
         });
       }
     },

packages/tanstackstart-react/src/vite/sentryTanstackStart.ts

@@ -20,6 +20,15 @@ export interface SentryTanstackStartOptions extends BuildTimeOptionsBase {
    * @default true
    */
   autoInstrumentMiddleware?: boolean;
+
+  /**
+   * Path to the instrumentation file to be copied to the server build output directory.
+   *
+   * Relative paths are resolved from the current working directory.
+   *
+   * @default 'instrument.server.mjs'
+   */
+  instrumentationFilePath?: string;
 }
 
 /**
@@ -55,7 +64,7 @@ export function sentryTanstackStart(options: SentryTanstackStartOptions = {}): P
   const plugins: Plugin[] = [...makeAddSentryVitePlugin(options)];
 
   // copy instrumentation file to build output
-  plugins.push(makeCopyInstrumentationFilePlugin());
+  plugins.push(makeCopyInstrumentationFilePlugin(options.instrumentationFilePath));
 
   // middleware auto-instrumentation
   if (options.autoInstrumentMiddleware !== false) {

packages/tanstackstart-react/test/vite/copyInstrumentationFile.test.ts

@@ -262,6 +262,77 @@ describe('makeCopyInstrumentationFilePlugin()', () => {
         '[Sentry TanStack Start] Failed to copy instrument.server.mjs to build output.',
         expect.any(Error),
       );
+    });
+
+    it('uses custom instrumentation file path when provided', async () => {
+      const customPlugin = makeCopyInstrumentationFilePlugin('custom/path/my-instrument.mjs');
+
+      const resolvedConfig = {
+        root: '/project',
+        plugins: [{ name: 'nitro' }],
+        environments: {
+          nitro: {
+            build: {
+              rollupOptions: {
+                output: {
+                  dir: '/project/.output/server',
+                },
+              },
+            },
+          },
+        },
+      } as unknown as ResolvedConfig;
+
+      (customPlugin.configResolved as AnyFunction)(resolvedConfig);
+
+      vi.mocked(fs.promises.access).mockResolvedValueOnce(undefined);
+      vi.mocked(fs.promises.mkdir).mockResolvedValueOnce(undefined);
+      vi.mocked(fs.promises.copyFile).mockResolvedValueOnce(undefined);
+
+      await (customPlugin.closeBundle as AnyFunction)();
+
+      expect(fs.promises.access).toHaveBeenCalledWith(
+        path.resolve(process.cwd(), 'custom/path/my-instrument.mjs'),
+        fs.constants.F_OK,
+      );
+      expect(fs.promises.copyFile).toHaveBeenCalledWith(
+        path.resolve(process.cwd(), 'custom/path/my-instrument.mjs'),
+        path.resolve('/project/.output/server', 'my-instrument.mjs'),
+      );
+    });
+
+    it('warns with custom file name when custom instrumentation file is not found', async () => {
+      const customPlugin = makeCopyInstrumentationFilePlugin('custom/my-instrument.mjs');
+
+      const resolvedConfig = {
+        root: '/project',
+        plugins: [{ name: 'nitro' }],
+        environments: {
+          nitro: {
+            build: {
+              rollupOptions: {
+                output: {
+                  dir: '/project/.output/server',
+                },
+              },
+            },
+          },
+        },
+      } as unknown as ResolvedConfig;
+
+      (customPlugin.configResolved as AnyFunction)(resolvedConfig);
+
+      vi.mocked(fs.promises.access).mockRejectedValueOnce(new Error('ENOENT'));
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      await (customPlugin.closeBundle as AnyFunction)();
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[Sentry TanStack Start] No custom/my-instrument.mjs file found in project root. ' +
+          'The Sentry instrumentation file will not be copied to the build output.',
+      );
+      expect(fs.promises.copyFile).not.toHaveBeenCalled();
 
       warnSpy.mockRestore();
     });