From 0655a508a48a81bafca92f23d3902f0c1ea7b1e5 Mon Sep 17 00:00:00 2001 From: Luis Alvarez Date: Wed, 15 Jul 2020 22:41:38 -0500 Subject: [PATCH 1/2] Updated with-sentry readme --- examples/with-sentry/.env.local.example | 6 ++ examples/with-sentry/README.md | 75 +++++++++++++++++++------ 2 files changed, 63 insertions(+), 18 deletions(-) create mode 100644 examples/with-sentry/.env.local.example diff --git a/examples/with-sentry/.env.local.example b/examples/with-sentry/.env.local.example new file mode 100644 index 0000000000000..1c27f919d4631 --- /dev/null +++ b/examples/with-sentry/.env.local.example @@ -0,0 +1,6 @@ +NEXT_PUBLIC_SENTRY_DSN= + +# Only required to upload sourcemaps +# SENTRY_ORG= +# SENTRY_PROJECT= +# SENTRY_AUTH_TOKEN= \ No newline at end of file diff --git a/examples/with-sentry/README.md b/examples/with-sentry/README.md index 214248776dfbc..7d70711f564e2 100644 --- a/examples/with-sentry/README.md +++ b/examples/with-sentry/README.md @@ -1,13 +1,17 @@ -[![Deploy To Now](https://deploy.now.sh/static/button.svg)](https://deploy.now.sh/?repo=https://github.com/vercel/next.js/tree/master/examples/with-sentry) - # Sentry -This is a example showing how to use [Sentry](https://sentry.io) to catch & report errors on both client + server side. +This is an example showing how to use [Sentry](https://sentry.io) to catch & report errors on both client + server side. - `_app.js` renders on both the server and client. It initializes Sentry to catch any unhandled exceptions - `_error.js` is rendered by Next.js while handling certain types of exceptions for you. It is overridden so those exceptions can be passed along to Sentry - `next.config.js` enables source maps in production for Sentry and swaps out `@sentry/node` for `@sentry/browser` when building the client bundle +## Deploy your own + +Once you have access to your [Sentry DSN](#step-1-enable-error-tracking), deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example): + +[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/import/git?c=1&s=https://github.com/vercel/next.js/tree/canary/examples/with-sentry&env=NEXT_PUBLIC_SENTRY_DSN&envDescription=DSN%20Key%20required%20by%20Sentry&envLink=https://github.com/vercel/next.js/tree/canary/examples/with-sentry%23step-1-enable-error-tracking) + ## How To Use ### Using `create-next-app` @@ -41,32 +45,67 @@ yarn dev Deploy it to the cloud with [Vercel](https://vercel.com/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)). +## Configuration + +### Step 1. Enable error tracking + +Copy the `.env.local.example` file in this directory to `.env.local` (which will be ignored by Git): + +```bash +cp .env.local.example .env.local +``` + +Next, Copy your Sentry DSN. You can get it from the settings of your project in **Client Keys (DSN)**. Then, copy the string labeled **DSN** and set it as the value for `NEXT_PUBLIC_SENTRY_DSN` inside `.env.local` + +> **Note:** Error tracking is disabled in development mode using the `NODE_ENV` environment variable. To change this behaviour, remove the `enabled` property from the `Sentry.init()` call inside your `_app.js` file. + +### Step 2. Run Next.js in development mode + +```bash +npm install +npm run dev + +# or + +yarn install +yarn dev +``` + +Your app should be up and running on [http://localhost:3000](http://localhost:3000)! If it doesn't work, post on [GitHub discussions](https://github.com/zeit/next.js/discussions). + +### Step 3. Automatic sourcemap upload (optional) + +1. Set up the `NEXT_PUBLIC_SENTRY_DSN` environment variable as described above. +2. Save your Sentry Organization slug as the `SENTRY_ORG` environment variable and your project slug as the `SENTRY_PROJECT` environment variable in `.env.local`. +3. Create an auth token in Sentry. The recommended way to do this is by creating a new internal integration for your organization. To do so, go into **Settings > Developer Settings > New internal integration**. After the integration is created, copy the Token. +4. Save the token inside the `SENTRY_AUTH_TOKEN` environment variable in `.env.local`. + +> **Note:** Sourcemap upload is disabled in development mode using the `NODE_ENV` environment variable. To change this behaviour, remove the `NODE_ENV === 'production'` check from your `next.config.js` file. + +## Other configuration options + +More configurations are available for the [Sentry webpack plugin](https://github.com/getsentry/sentry-webpack-plugin) using [Sentry Configuration variables](https://docs.sentry.io/cli/configuration/) for defining the releases/verbosity/etc. + ## Notes -- By default, neither sourcemaps nor error tracking is enabled in development mode (see Configuration). +- By default, neither sourcemaps nor error tracking are enabled in development mode (see Configuration). - When enabled in development mode, error handling [works differently than in production](https://nextjs.org/docs/advanced-features/custom-error-page#customizing-the-error-page) as `_error.js` is never actually called. - The build output will contain warning about unhandled Promise rejections. This is caused by the test pages, and is expected. - The version of `@zeit/next-source-maps` (`0.0.4-canary.1`) is important and must be specified since it is not yet the default. Otherwise [source maps will not be generated for the server](https://github.com/zeit/next-plugins/issues/377). - Both `@zeit/next-source-maps` and `@sentry/webpack-plugin` are added to dependencies (rather than `devDependencies`) because if used with SSR, these plugins are used during production for generating the source-maps and sending them to sentry. -## Configuration +## Deploy on Vercel -### Error tracking +You can deploy this app to the cloud with [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)). -1. Copy your Sentry DSN. You can get it from the settings of your project in **Client Keys (DSN)**. Then, copy the string labeled **DSN (Public)**. -2. Put the DSN inside the `SENTRY_DSN` environment variable inside a new environment file called `.env.local` +#### Deploy Your Local Project -> **Note:** Error tracking is disabled in development mode using the `NODE_ENV` environment variable. To change this behaviour, remove the `enabled` property from the `Sentry.init()` call inside your `_app.js` file. - -### Automatic sourcemap upload (optional) +To deploy your local project to Vercel, push it to GitHub/GitLab/Bitbucket and [import to Vercel](https://vercel.com/import/git?utm_source=github&utm_medium=readme&utm_campaign=next-example). -1. Set up the `SENTRY_DSN` environment variable as described above. -2. Save your Sentry Organization slug inside the `SENTRY_ORG` and your project slug inside the `SENTRY_PROJECT` environment variables. -3. Create an auth token in Sentry. The recommended way to do this is by creating a new internal integration for your organization. To do so, go into Settings > Developer Settings > New internal integration. After the integration is created, copy the Token. -4. Save the token inside the `SENTRY_AUTH_TOKEN` environment variable. +**Important**: When you import your project on Vercel, make sure to click on **Environment Variables** and set them to match your `.env.local` file. -> **Note:** Sourcemap upload is disabled in development mode using the `NODE_ENV` environment variable. To change this behaviour, remove the `NODE_ENV === 'production'` check from your `next.config.js` file. +#### Deploy from Our Template -### Other configuration options +Alternatively, you can deploy using our template by clicking on the Deploy button below. -More configurations are available for the [Sentry webpack plugin](https://github.com/getsentry/sentry-webpack-plugin) using [Sentry Configuration variables](https://docs.sentry.io/cli/configuration/) for defining the releases/verbosity/etc. +[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/import/git?c=1&s=https://github.com/vercel/next.js/tree/canary/examples/with-sentry&env=NEXT_PUBLIC_SENTRY_DSN&envDescription=DSN%20Key%20required%20by%20Sentry&envLink=https://github.com/vercel/next.js/tree/canary/examples/with-sentry%23step-1-enable-error-tracking) From ce3dcc1da3d7cd429366c159377a5bc879c07104 Mon Sep 17 00:00:00 2001 From: Joe Haddad Date: Thu, 16 Jul 2020 16:56:24 -0400 Subject: [PATCH 2/2] Update .env.local.example --- examples/with-sentry/.env.local.example | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/with-sentry/.env.local.example b/examples/with-sentry/.env.local.example index 1c27f919d4631..c1a592df4aab4 100644 --- a/examples/with-sentry/.env.local.example +++ b/examples/with-sentry/.env.local.example @@ -3,4 +3,4 @@ NEXT_PUBLIC_SENTRY_DSN= # Only required to upload sourcemaps # SENTRY_ORG= # SENTRY_PROJECT= -# SENTRY_AUTH_TOKEN= \ No newline at end of file +# SENTRY_AUTH_TOKEN=