feat: Add option to NextJS for creating sentry rules LLM file

e2e-tests/tests/nextjs-14.test.ts

@@ -78,6 +78,13 @@
       (await wizardInstance.sendStdinAndWaitForOutput(
         // Selecting `No` for CI/CD tool
         [KEYS.DOWN, KEYS.ENTER],
+        'Do you want to create a sentryrules file',
+      ));
+
+
+    sentryRulesPrompted &&
+      (await wizardInstance.sendStdinAndWaitForOutput(
+        [KEYS.ENTER],
         'Successfully installed the Sentry Next.js SDK!',
       ));
 
@@ -134,6 +141,10 @@
     ]);
   });
 
+  test('sentryrules file exists', () => {
+    checkFileExists(`${projectDir}/.rules/sentryrules.md`);
+  });
+
   test('next.config file contains Sentry wrapper', () => {
     checkFileContents(`${projectDir}/next.config.mjs`, [
       "import {withSentryConfig} from '@sentry/nextjs'",

e2e-tests/tests/nextjs-15.test.ts

@@ -78,6 +78,19 @@ describe('NextJS-15', () => {
       (await wizardInstance.sendStdinAndWaitForOutput(
         // Selecting `No` for CI/CD tool
         [KEYS.DOWN, KEYS.ENTER],
+        'Do you want to create a sentryrules file',
+      ));
+
+    const sentryRulesPrompted =
+      ciCdPrompted &&
+      (await wizardInstance.sendStdinAndWaitForOutput(
+        [KEYS.ENTER],
+        'Do you want to create a sentryrules file',
+      ));
+
+    sentryRulesPrompted &&
+      (await wizardInstance.sendStdinAndWaitForOutput(
+        [KEYS.ENTER],
         'Successfully installed the Sentry Next.js SDK!',
       ));
 

src/nextjs/nextjs-wizard.ts

@@ -51,6 +51,7 @@
   getSimpleUnderscoreErrorCopyPasteSnippet,
   getWithSentryConfigOptionsTemplate,
   getInstrumentationClientHookCopyPasteSnippet,
+  getAiRulesFileContent,
 } from './templates';
 import { getNextJsVersionBucket } from './utils';
 
@@ -344,6 +345,51 @@
   const packageManagerForOutro =
     packageManagerFromInstallStep ?? (await getPackageManager());
 
+  await traceStep('create-ai-rules-file', async () => {
+    const shouldCreateAiRulesFile = await askShouldCreateAiRulesFile();
+    if (shouldCreateAiRulesFile) {
+      try {
+        const rulesDir = path.join(process.cwd(), '.rules');
+        const rulesDirExists = fs.existsSync(rulesDir);
+
+        // Create .rules directory if it doesn't exist
+        if (!rulesDirExists) {
+          await fs.promises.mkdir(rulesDir, { recursive: true });
+        }
+
+        const aiRulesContent = getAiRulesFileContent();
+        await fs.promises.writeFile(
+          path.join(rulesDir, 'sentryrules.md'),
+          aiRulesContent,
+          { encoding: 'utf8', flag: 'w' },
+        );
+
+        clack.log.success(
+          `Created ${chalk.cyan('sentryrules.md')} in ${chalk.cyan(
+            '.rules',
+          )} directory.`,
+        );
+      } catch (error) {
+        clack.log.error(
+          `Failed to create ${chalk.cyan('sentryrules.md')} in ${chalk.cyan(
+            '.rules',
+          )} directory.`,
+        );
+
+        const aiRulesContent = getAiRulesFileContent();
+        await showCopyPasteInstructions({
+          filename: '.rules/sentryrules.md',
+          codeSnippet: aiRulesContent,
+          hint: "create the .rules directory and file if they don't already exist",
+        });
+
+        Sentry.captureException(error);
+      }
+    } else {
+      clack.log.info('Skipped creating sentryrules.md.');
+    }
+  });
+
   await runPrettierIfInstalled({ cwd: undefined });
 
   clack.outro(`
@@ -1071,6 +1117,40 @@
   });
 }
 
+/**
+ * Ask users if they want to create a .sentryrules file with AI rule examples for Sentry.
+ * This is useful for giving the LLM context on common actions in Sentry like custom spans,
+ * logging, and error / exception handling.
+ */
+
+async function askShouldCreateAiRulesFile(): Promise<boolean> {
+  return await traceStep('ask-create-ai-rules-file', async (span) => {
+    const shouldCreateAiRulesFile = await abortIfCancelled(
+      clack.select({
+        message:
+          'Do you want to create a ./rules/sentryrules.md file with AI rule examples for Sentry?',
+        options: [
+          {
+            label: 'Yes',
+            value: true,
+            hint: 'Creates .rules/sentryrules.md in your project',
+          },
+          {
+            label: 'No',
+            value: false,
+          },
+        ],
+        initialValue: true,
+      }),
+    );
+
+    span?.setAttribute('shouldCreateAiRulesFile', shouldCreateAiRulesFile);
+    Sentry.setTag('shouldCreateAiRulesFile', shouldCreateAiRulesFile);
+
+    return shouldCreateAiRulesFile;
+  });
+}
+
 /**
  * Returns true or false depending on whether we think the user is using Turbopack. May return null in case we aren't sure.
  */

src/nextjs/templates.ts

@@ -711,3 +711,139 @@
   )
 }
 `;
+
+export function getAiRulesFileContent(): string {
+  return `These examples should be used as guidance when configuring Sentry functionality within a project.
+
+# Exception Catching
+
+- Use \`Sentry.captureException(error)\` to capture an exception and log the error in Sentry.
+- Use this in try catch blocks or areas where exceptions are expected
+
+# Tracing Examples
+
+- Spans should be created for meaningful actions within an applications like button clicks, API calls, and function calls
+- Ensure you are creating custom spans with meaningful names and operations
+- Span names should be parameterized. For example, when get a user by an id, name the span \`fetch /users/:id\` instead of \`fetch /users/1234\`
+- Use the \`Sentry.startSpan\` function to create a span
+- Child spans can exist within a parent span
+
+## Custom Span instrumentation in component actions
+
+- The \`name\` and \`op\` properties should be meaninful for the activities in the call.
+- Attach attribute based on relevant information and metrics from the request
+
+\`\`\`javascript
+function TestComponent() {
+  const handleTestButtonClick = () => {
+    // Create a transaction/span to measure performance
+    Sentry.startSpan({ 
+      op: "ui.click", 
+      name: "Test Button Click" 
+    }, (span) => {
+       
+      const value = "some config"
+      const metric = "some metric"
+      
+      // Metrics can be added to the span
+      span.setAttribute("config", value)
+      span.setAttribute("metric", metric)
+      
+      doSomething();
+    });
+  };
+
+  return (
+    <button 
+      type="button" 
+      onClick={handleTestButtonClick}
+    >
+      Test Sentry
+    </button>
+  );
+}
+\`\`\`
+
+## Custom span instrumentation in API calls
+
+- The \`name\` and \`op\` properties should be meaninful for the activities in the call.
+- Attach attributes based on relevant information and metrics from the request
+
+\`\`\`javascript
+async function fetchUserData(userId) {
+  return Sentry.startSpan(
+    {
+      name: \'fetch /api/users/:userId',
+    },
+    async () => {
+      try {
+        const response = await fetch(\`/api/users/\${userId}\`);
+        const data = await response.json();
+        return data;
+      }
+    );
+  }
+\`\`\`
+
+# Logs 
+
+- Where logs are used, ensure Sentry is imported using \`import * as Sentry from "@sentry/nextjs"\`.
+- Enable logging in Sentry using \`Sentry.init({ _experiments: { enableLogs: true } })\`
+- Reference the logger using \`const { logger } = Sentry\`.
+- Sentry offers a consoleLoggingIntegration that can be used to log specific console error types automatically without instrumenting the individual logger calls
+
+## Configuration
+
+- In NextJS the client side Sentry initialization is in \`instrumentation-client.ts\`, the server initialization is in \`sentry.edge.config.ts\` and the edge initialization is in \`sentry.server.config.ts\`
+- Initialization does not need to be repeated in other files, it only needs to happen the files mentioned above. You should use \`import * as Sentry from "@sentry/nextjs"\` to reference Sentry functionality
+
+### Baseline
+
+\`\`\`javascript
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: "https://[email protected]/0",
+
+  _experiments: {
+    enableLogs: true,
+  },
+  
+});
+\`\`\`
+
+### Logger Integration
+
+\`\`\`javascript
+Sentry.init({
+  dsn: "https://[email protected]/0",
+  integrations: [
+    // send console.log, console.error, and console.warn calls as logs to Sentry
+    Sentry.consoleLoggingIntegration({ levels: ["log", "error", "warn"] }),
+  ],
+});
+\`\`\`
+
+## Logger Examples 
+
+\`\`\`javascript
+logger.trace("Starting database connection", { database: "users" });
+logger.debug("Cache miss for user", { userId: 123 });
+logger.info("Updated profile", { profileId: 345 });
+logger.warn("Rate limit reached for endpoint", {
+  endpoint: "/api/results/",
+  isEnterprise: false,
+});
+logger.error("Failed to process payment", {
+  orderId: "order_123",
+  amount: 99.99,
+});
+logger.fatal("Database connection pool exhausted", {
+  database: "users",
+  activeConnections: 100,
+});
+\`\`\`
+
+
+`;
+}