Skip to content

doc(astro): Update Readme #9333

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 23, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 21 additions & 81 deletions packages/astro/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,9 @@
[![npm dm](https://img.shields.io/npm/dm/@sentry/astro.svg)](https://www.npmjs.com/package/@sentry/astro)
[![npm dt](https://img.shields.io/npm/dt/@sentry/astro.svg)](https://www.npmjs.com/package/@sentry/astro)

<!--
TODO: Add links once we have official docs
## Links

- [Official SDK Docs](https://docs.sentry.io/platforms/javascript/guides/astro/)
-->

## Experimental Note

Expand All @@ -28,98 +25,41 @@ This package is a wrapper around `@sentry/node` for the server and `@sentry/brow

## Installation and Setup

### 1. Registering the Sentry Astro integration:
Install the Sentry Astro SDK with the `astro` CLI:

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__',
}),
],
})
```bash
npx astro add @sentry/astro
```

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:
Complete the setup by adding your DSN and source maps upload configuration:

### 2. [Optional] Uploading Source Maps

To upload source maps to Sentry, simply add the `project` and `authToken` options to `sentryAstro`:

```js
// astro.config.mjs
import { sentryAstro } from "@sentry/astro/integration";
```javascript
import { defineConfig } from "astro/config";
import sentry from "@sentry/astro";

export default defineConfig({
// Rest of your Astro project config
integrations: [
sentryAstro({
dsn: '__DSN__',
project: 'your-project-slug',
authToken: import.meta.env('SENTRY_AUTH_TOKEN'),
sentry({
dsn: "__DSN__",
sourceMapsUploadOptions: {
project: "your-sentry-project-slug",
authToken: process.env.SENTRY_AUTH_TOKEN,
},
}),
],
})
});
```

You can also define these values as environment variables in e.g. a `.env` file
or in you CI configuration:
Follow [this guide](https://docs.sentry.io/product/accounts/auth-tokens/#organization-auth-tokens) to create an auth token and add it to your environment variables:

```sh
SENTRY_PROJECT="your-project"
```bash
SENTRY_AUTH_TOKEN="your-token"
```

Follow [this guide](https://docs.sentry.io/product/accounts/auth-tokens/#organization-auth-tokens) to create an auth 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 use 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
## Configuration

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`:
Check out our docs for configuring your SDK setup:

```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',
}),
],
})
```
* [Getting Started](https://docs.sentry.io/platforms/javascript/guides/astro/)
* [Manual Setup and Configuration](https://docs.sentry.io/platforms/javascript/guides/astro/manual-setup/)
* [Source Maps Upload](https://docs.sentry.io/platforms/javascript/guides/astro/sourcemaps/)