feat(astro): Add sentryAstro integration

Author: Lms24

packages/astro/.eslintrc.js

@@ -11,5 +11,12 @@ module.exports = {
         project: ['tsconfig.test.json'],
       },
     },
+    {
+      files: ['src/integration/**', 'src/server/**'],
+      rules: {
+        '@sentry-internal/sdk/no-optional-chaining': 'off',
+        '@sentry-internal/sdk/no-nullish-coalescing': 'off',
+      },
+    },
   ],
 };

packages/astro/.npmignore

@@ -0,0 +1,10 @@
+# The paths in this file are specified so that they align with the file structure in `./build` after this file is copied
+# into it by the prepack script `scripts/prepack.ts`.
+
+*
+
+!/cjs/**/*
+!/esm/**/*
+!/types/**/*
+!/types-ts3.8/**/*
+!/integration/**/*

packages/astro/README.md

@@ -28,4 +28,98 @@ This package is a wrapper around `@sentry/node` for the server and `@sentry/brow
 
 ## Installation and Setup
 
-TODO
+### 1. Registering the Sentry Astro integration:
+
+Add the `sentryAstro` integration to your `astro.config.mjs` file:
+
+```javascript
+import { sentryAstro } from "@sentry/astro/integration";
+
+export default defineConfig({
+  // Rest of your Astro project config
+  integrations: [
+    sentryAstro({
+      dsn: '__DSN__',
+    }),
+  ],
+})
+```
+
+This is the easiest way to configure Sentry in an Astro project.
+You can pass a few additional options to `sentryAstro` but the SDK comes preconfigured in an opinionated way.
+If you want to fully customize your SDK setup, you can do so, too:
+
+### 2. [Optional] Uploading Source Maps
+
+To upload source maps to Sentry, simply add the `project`, `org` and `authToken` options to `sentryAstro`:
+
+```js
+// astro.config.mjs
+import { sentryAstro } from "@sentry/astro/integration";
+
+export default defineConfig({
+  // Rest of your Astro project config
+  integrations: [
+    sentryAstro({
+      dsn: '__DSN__',
+      org: 'your-org-slug',
+      project: 'your-project-slug',
+      authToken: import.meta.env('SENTRY_AUTH_TOKEN'),
+    }),
+  ],
+})
+```
+
+You can also define these values as environment variables in e.g. a `.env` file
+or in you CI configuration:
+
+```sh
+SENTRY_ORG="your-org-slug"
+SENTRY_PROJECT="your-project"
+SENTRY_AUTH_TOKEN="your-token"
+```
+
+### 3. [Optional] Advanced Configuration
+
+To fully customize and configure Sentry in an Astro project, follow step 1 and in addition,
+add a `sentry.client.config.(js|ts)` and `sentry.server.config(js|ts)` file to the root directory of your project.
+Inside these files, you can call `Sentry.init()` and get the full range of Sentry options.
+
+Configuring the client SDK:
+
+```js
+// sentry.client.config.ts or sentry.server.config.ts
+import * as Sentry from "@sentry/astro";
+
+Sentry.init({
+  dsn: "__DSN__",
+  beforeSend(event) {
+    console.log("Sending event on the client");
+    return event;
+  },
+  tracesSampler: () => {/* ... */}
+});
+```
+
+**Important**: Once you created a sentry config file, the SDK options passed to `sentryAstro` will be ignored for the respective runtime. You can also only define create of the two files.
+
+#### 3.1 Custom file location
+
+If you want to move the `sentry.*.config` files to another location,
+you can specify the file path, relative to the project root, in `sentryAstro`:
+
+```js
+// astro.config.mjs
+import { sentryAstro } from "@sentry/astro/integration";
+
+export default defineConfig({
+  // Rest of your Astro project config
+  integrations: [
+    sentryAstro({
+      dsn: '__DSN__',
+      clientInitPath: '.config/sentry.client.init.js',
+      serverInitPath: '.config/sentry.server.init.js',
+    }),
+  ],
+})
+```

packages/astro/package.json

@@ -9,30 +9,44 @@
   "engines": {
     "node": ">=18.14.1"
   },
-  "main": "build/cjs/index.server.js",
+  "type": "module",
+  "main": "build/cjs/index.client.js",
   "module": "build/esm/index.server.js",
   "browser": "build/esm/index.client.js",
   "types": "build/types/index.types.d.ts",
+  "exports": {
+    ".": {
+      "node": "./build/esm/index.server.js",
+      "browser": "./build/esm/index.client.js",
+      "import": "./build/esm/index.client.js",
+      "require": "./build/cjs/index.server.js",
+      "types": "./build/types/index.types.d.ts"
+    },
+    "./integration": {
+      "default": "./build/integration/index.ts"
+    }
+  },
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
-    "astro": "1.x"
+    "astro": "3.x"
   },
   "dependencies": {
     "@sentry/browser": "7.73.0",
     "@sentry/node": "7.73.0",
     "@sentry/core": "7.73.0",
     "@sentry/utils": "7.73.0",
-    "@sentry/types": "7.73.0"
+    "@sentry/types": "7.73.0",
+    "@sentry/vite-plugin": "^2.8.0"
   },
   "devDependencies": {
     "astro": "^3.2.3",
     "rollup": "^3.20.2",
     "vite": "4.0.5"
   },
   "scripts": {
-    "build": "run-p build:transpile build:types",
+    "build": "run-p build:transpile build:types build:sync:integration",
     "build:dev": "yarn build",
     "build:transpile": "rollup -c rollup.npm.config.js --bundleConfigAsCjs",
     "build:types": "tsc -p tsconfig.types.json",
@@ -41,6 +55,7 @@
     "build:transpile:watch": "rollup -c rollup.npm.config.js --bundleConfigAsCjs --watch",
     "build:types:watch": "tsc -p tsconfig.types.json --watch",
     "build:tarball": "ts-node ../../scripts/prepack.ts && npm pack ./build",
+    "build:sync:integration": "ts-node -P tsconfig.dev.json ./scripts/syncIntegration.ts",
     "circularDepCheck": "madge --circular src/index.client.ts && madge --circular src/index.server.ts && madge --circular src/index.types.ts",
     "clean": "rimraf build coverage sentry-astro-*.tgz",
     "fix": "run-s fix:eslint fix:prettier",

packages/astro/scripts/syncIntegration.ts

@@ -0,0 +1,20 @@
+/* eslint-disable no-console */
+
+import * as fse from 'fs-extra';
+import * as path from 'path';
+
+const buildDir = path.resolve('build');
+const srcIntegrationDir = path.resolve(path.join('src', 'integration'));
+const destIntegrationDir = path.resolve(path.join(buildDir, 'integration'));
+
+try {
+  fse.copySync(srcIntegrationDir, destIntegrationDir, {
+    filter: (src, _) => {
+      return !src.endsWith('.md');
+    },
+  });
+  console.log('\nCopied Astro integration to ./build/integration\n');
+} catch (e) {
+  console.error('\nError while copying integration to build dir:');
+  console.error(e);
+}

packages/astro/src/integration/README.md

@@ -0,0 +1,4 @@
+Contents of this directory are _not_ bundled with rollup.
+They're directly copied into `build/integration`.
+Astro supports TypeScript in integration packages.
+The integration files will simply be bundled by Vite when building the Astro project.

packages/astro/src/integration/index.ts

@@ -0,0 +1,69 @@
+/* eslint-disable no-console */
+import { sentryVitePlugin } from '@sentry/vite-plugin';
+import type { AstroIntegration } from 'astro';
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadEnv } from 'vite';
+
+import { buildClientSnippet, buildSdkInitFileImportSnippet, buildServerSnippet } from './snippets';
+import type { SentryOptions } from './types';
+
+const PKG_NAME = '@sentry/astro';
+
+export const sentryAstro = (options: SentryOptions = {}): AstroIntegration => {
+  return {
+    name: PKG_NAME,
+    hooks: {
+      'astro:config:setup': async ({ updateConfig, injectScript }) => {
+        // The third param here enables loading of all env vars, regardless of prefix
+        // see: https://main.vitejs.dev/config/#using-environment-variables-in-config
+        const env = loadEnv('production', process.cwd(), '');
+
+        if (options.authToken ?? env.SENTRY_AUTH_TOKEN) {
+          updateConfig({
+            vite: {
+              build: {
+                sourcemap: true,
+              },
+              plugins: [
+                sentryVitePlugin({
+                  org: options.org ?? env.SENTRY_ORG,
+                  project: options.project ?? env.SENTRY_PROJECT,
+                  authToken: options.authToken ?? env.SENTRY_AUTH_TOKEN,
+                  telemetry: options.telemetry,
+                }),
+              ],
+            },
+          });
+        }
+
+        const pathToClientInit = options.clientInitPath ?? findSdkInitFile('client');
+        const pathToServerInit = options.serverInitPath ?? findSdkInitFile('server');
+
+        if (pathToClientInit) {
+          options.debug && console.log(`[sentry-astro] Using ${pathToClientInit} for client init.`);
+          injectScript('page', buildSdkInitFileImportSnippet(pathToClientInit));
+        } else {
+          options.debug && console.log('[sentry-astro] Using default client init.');
+          injectScript('page', buildClientSnippet(options || {}));
+        }
+
+        if (pathToServerInit) {
+          options.debug && console.log(`[sentry-astro] Using ${pathToServerInit} for server init.`);
+          // For whatever reason, we need to move one level up to import the server file correctly
+          injectScript('page-ssr', buildSdkInitFileImportSnippet(path.join('..', pathToServerInit)));
+        } else {
+          options.debug && console.log('[sentry-astro] Using default server init.');
+          injectScript('page-ssr', buildServerSnippet(options || {}));
+        }
+      },
+    },
+  };
+};
+
+function findSdkInitFile(type: 'server' | 'client'): string | undefined {
+  const fileExtensions = ['ts', 'js', 'tsx', 'jsx', 'mjs', 'cjs', 'mts'];
+  return fileExtensions
+    .map(ext => path.join(process.cwd(), `sentry.${type}.config.${ext}`))
+    .find(filename => fs.existsSync(filename));
+}

packages/astro/src/integration/snippets.ts

@@ -0,0 +1,47 @@
+import type { SentryOptions } from './types';
+
+/**
+ * Creates a snippet that imports a Sentry.init file.
+ */
+export function buildSdkInitFileImportSnippet(filePath: string): string {
+  return `import "${filePath}";`;
+}
+
+/**
+ * Creates a snippet that initializes Sentry on the client by choosing
+ * default options.
+ */
+export function buildClientSnippet(options: SentryOptions): string {
+  return `import * as Sentry from "@sentry/astro";
+
+Sentry.init({
+  dsn: ${options.dsn ? JSON.stringify(options.dsn) : 'import.meta.env.PUBLIC_SENTRY_DSN'},
+  debug: ${options.debug ? true : false},
+  environment: ${options.environment ? JSON.stringify(options.environment) : 'import.meta.env.PUBLIC_VERCEL_ENV'},
+  release: ${options.release ? JSON.stringify(options.release) : 'import.meta.env.PUBLIC_VERCEL_GIT_COMMIT_SHA'},
+  integrations: [new Sentry.BrowserTracing(), new Sentry.Replay()],
+  tracesSampleRate: ${options.tracesSampleRate ?? 1.0},
+  replaysSessionSampleRate: ${options.replaysSessionSampleRate ?? 0.1},
+  replaysOnErrorSampleRate: ${options.replaysOnErrorSampleRate ?? 1.0},${
+    options.sampleRate ? `\n  sampleRate: ${options.sampleRate},` : ''
+  }
+});`;
+}
+
+/**
+ * Creates a snippet that initializes Sentry on the server by choosing
+ * default options.
+ */
+export function buildServerSnippet(options: SentryOptions): string {
+  return `import * as Sentry from "@sentry/astro";
+
+Sentry.init({
+  dsn: ${options.dsn ? JSON.stringify(options.dsn) : 'import.meta.env.PUBLIC_SENTRY_DSN'},
+  debug: ${options.debug ? true : false},
+  environment: ${options.environment ? JSON.stringify(options.environment) : 'import.meta.env.PUBLIC_VERCEL_ENV'},
+  release: ${options.release ? JSON.stringify(options.release) : 'import.meta.env.PUBLIC_VERCEL_GIT_COMMIT_SHA'},
+  tracesSampleRate: ${options.tracesSampleRate ?? 1.0},${
+    options.sampleRate ? `\n  sampleRate: ${options.sampleRate},` : ''
+  }
+});`;
+}

packages/astro/src/integration/types.ts

@@ -0,0 +1,32 @@
+import type { BrowserOptions } from '@sentry/browser';
+import type { Options } from '@sentry/types';
+import type { SentryVitePluginOptions } from '@sentry/vite-plugin';
+
+type SdkInitPaths = {
+  /**
+   * Path to a `sentry.client.config.(js|ts)` file that contains a `Sentry.init` call.
+   * If this option is not specified, the default location (`src/sentry.client.config.(js|ts)`) will be used.
+   * If there is no file at the default location, a default `Sentry.init` call will made.
+   */
+  clientInitPath?: string;
+  /**
+   * Path to a `sentry.client.config.(js|ts)` file that contains a `Sentry.init` call.
+   * If this option is not specified, the default location (`src/sentry.client.config.(js|ts)`) will be used.
+   * If there is no file at the default location, a default `Sentry.init` call will made.
+   */
+  serverInitPath?: string;
+};
+
+/**
+ * A subset of Sentry SDK options that can be set via the `sentryAstro` integration.
+ * Some options (e.g. integrations) are set by default and cannot be changed here.
+ *
+ * If you want a more fine-grained control over the SDK, with all options,
+ * you can call Sentry.init in `sentry.client.config.(js|ts)` or `sentry.server.config.(js|ts)` files.
+ *
+ * If you specify a dedicated init file, the SDK options passed to `sentryAstro` will be ignored.
+ */
+export type SentryOptions = SdkInitPaths &
+  Pick<Options, 'dsn' | 'release' | 'environment' | 'sampleRate' | 'tracesSampleRate' | 'debug'> &
+  Pick<BrowserOptions, 'replaysSessionSampleRate' | 'replaysOnErrorSampleRate'> &
+  Pick<SentryVitePluginOptions, 'authToken' | 'org' | 'project' | 'telemetry'>;