npm package: @labor-digital/sentry-browser
Description: A convenience wrapper around the sentry.io browser api - Probably mostly for company internal affairs ;)
Author: LABOR.digital
Latest version: 1.5.1

# Sentry.io - Asset Building Addon
This package is a wrapper for the sentry.io SDK. It integrates into the [asset-building](https://github.com/labor-digital/asset-building) toolbox to automagically
inject the required DSN into your codebase.

This is mostly an internal tool we use in combination with our bitbucket build-pipelines.
However, you can also use the library without any build-pipeline (See "Without pipeline" for further details).

## Installation
Install this package using npm:
```
npm install @labor-digital/sentry-browser
```

Register the extension for the asset-builder
```
{
    "labor": {
        "apps": [...],
        "extensions": [
            "@labor-digital/sentry-browser/asset-building"
        ]
    }
}
```

## Usage
In your frontend code you can now simply import the Sentry class from the package.
The injection of all required information will be handled by our build-pipeline. (See "Without pipeline" for usage without build pipeline)
```
import Sentry from "@labor-digital/sentry-browser"
try {
    ... Your Code ...
} catch(e){
    Sentry.captureException(e);
}
```

## Without pipeline
If you can't, or don't want to use our bitbucket pipeline you have to manually inject the configuration into the script.
You can do that by manually setting the configuration in your code using ```Sentry.setSentryConfig()```,
or by injecting the ```process.env.LABOR_SENTRY_CONFIG``` environment variable using webpack's "Define Plugin" in your build process.

```javascript
const sentryConfig = {
    dsn: "$YOUR_DSN", // This is the dsn you get from the sentry website or using the CLI
    release: "$YOUR_RELEASE", // This is optional to use sentry's release feature
};
module.exports = merge($WEBPACK_CONFIG, {
    plugins: [
        new (require("webpack")).DefinePlugin({
            "process.env.LABOR_SENTRY_CONFIG": JSON.stringify(sentryConfig)
        })
    ]
});
```

## Additional data on errors
If you are using custom error objects, that hold additional data
you want to provide to sentry, this package has you covered. By default,
you would have to add a beforeSend() hook to inject your data before
sentry sends the data to the api.

With this package you can simply add a method called getSentryExtra()
to your error object. The method can either return a promise, or a simple
object that will automatically be added to the error when the request is send.

## Methods

### captureException()
Captures an exception event and sends it to Sentry.

### captureMessage()
Captures a message event and sends it to Sentry.

### manualActivation()
We use NODE_ENV === "production" to automatically detect
if sentry logging should be enabled. If you want to force the activity state you can always use this method to
set the activity manually.
Keep in mind, that even if you set this to TRUE, but your configuration is incomplete nothing will be logged!

### setSentryConfig()
By default, the class will try to load the basic configuration using the config.json file
that was generated by the sentry-release build step, but you may use this method either to
provide additional configuration for sentry or to provide the whole configuration without using the build step.

### isActivated()
Checks if the sentry logging is activated, by validating if the class was correctly initialized

## Building the sources

- Clone the repository
- Navigate to the root directory (where the "package.json" lives)
- Install the dependencies with ```npm install```
- Run the continuous watcher for development ```npm run watch```
- OR build the sources for production ```npm run build```

## Postcardware
You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.

Our address is: LABOR.digital - Fischtorplatz 21 - 55116 Mainz, Germany

We publish all received postcards on our [company website](https://labor.digital).