Merge branch 'canary' into feature/incremental-typechecking

Author: ijjk

examples/with-sentry/README.md

@@ -1,11 +1,11 @@
 # Sentry
 
-This is an example showing how to use [Sentry](https://sentry.io) to catch & report errors on both client + server side, using the [official Sentry SDK for Next.js](https://docs.sentry.io/platforms/javascript/guides/nextjs/).
+This is an example showing how to use [Sentry](https://sentry.io) to catch and report errors on both the front and back ends, using the [official Sentry SDK for Next.js](https://docs.sentry.io/platforms/javascript/guides/nextjs/).
 
-- `_app.js` renders on both the server and client
-- `_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
+- `sentry.server.config.js` and `sentry.client.config.js` are used to configure and initialize Sentry
+- `next.config.js` automatically injects Sentry into your app using `withSentryConfig`
+- `_error.js` (which is rendered by Next.js when handling certain types of exceptions) is overridden so those exceptions can be passed along to Sentry
 - Each API route is handled with `withSentry`
-- `next.config.js` automatically configures the app to use Sentry through `withSentry`
 
 ## Preview
 
@@ -15,43 +15,60 @@ Preview the example live on [StackBlitz](http://stackblitz.com/):
 
 ## Deploy your own
 
-Once you have access to your [Sentry DSN](https://docs.sentry.io/product/sentry-basics/dsn-explainer/#where-to-find-your-dsn), deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
+It only takes a few steps to create and deploy your own version of this example app. Before you begin, make sure you have [linked your Vercel account to GitHub](https://vercel.com/docs/personal-accounts/login-connections), and [set up a project in Sentry](https://docs.sentry.io/product/sentry-basics/guides/integrate-frontend/create-new-project/).
 
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/with-sentry&project-name=with-sentry&repository-name=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)
+### Option 1: Deploy directly to Vercel
 
-Check out [Sentry’s Vercel Integration](#sentry-integration).
+You can deploy a copy of this project directly to [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example).
 
-## How To Use
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/with-sentry&project-name=nextjs-sentry-example&repository-name=nextjs-sentry-example&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)
 
-Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example:
+This will clone this example to your GitHub org, create a linked project in Vercel, and prompt you to install the Vercel Sentry Integration. (You can read more about the integration [on Vercel](https://vercel.com/integrations/sentry) and in [the Sentry docs](https://docs.sentry.io/product/integrations/deployment/vercel/).)
+
+### Option 2: Create locally before deploying
+
+Alternatively, you can create a copy of ths example app locally so you can configure and customize it before you deploy it.
+
+#### Create and configure your app
+
+To begin, execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npx](https://www.npmjs.com/package/npx) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), to create the app and install dependencies:
 
 ```bash
-npx create-next-app --example with-sentry with-sentry-app
+npx create-next-app --example with-sentry nextjs-sentry-example
 # or
-yarn create next-app --example with-sentry with-sentry-app
+yarn create next-app --example with-sentry nextjs-sentry-example
 ```
 
-## Configuration
+Next, run [`sentry-wizard`](https://docs.sentry.io/platforms/javascript/guides/nextjs/#configure), which will create and populate the settings files needed by `@sentry/nextjs` to initialize the SDK and upload source maps to Sentry:
 
-You can [configure your app automatically](https://docs.sentry.io/platforms/javascript/guides/nextjs/#configure) or do the [manual setup](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/).
-Both ways lead to having your custom config files (`next.config.js`, `sentry.client.config.js`, `sentry.server.config.js`, and `sentry.properties`); so you can delete them from the example, they are here to illustrate how an example app looks like.
+```bash
+npx @sentry/wizard -i nextjs
+```
 
-## Deploy on Vercel
+Once the files are created, you can further configure your app by adding [SDK settings](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/) to `sentry.server.config.js` and `sentry.client.config.js` and [`SentryWebpackPlugin` settings](https://github.com/getsentry/sentry-webpack-plugin#options) to `next.config.js`.
 
-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)).
+(If you'd rather do the SDK set-up manually, [you can do that, too](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/).)
 
-#### Deploy Your Local Project
+You should now be able to build and run your app locally, upload source maps, and send errors to Sentry. For more details, check out the [Sentry Next.js SDK docs](https://docs.sentry.io/platforms/javascript/guides/nextjs/).
 
-To deploy your local project to Vercel, push it to GitHub/GitLab/Bitbucket and [import to Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example).
+#### Deploy your app to Vercel
 
-**Important**: When you import your project on Vercel, make sure to click on **Environment Variables** and set them to match your `.env.local` file.
+Vercel reads you code from GitHub, so you first need to [create an empty GitHub repo](https://docs.github.com/en/get-started/quickstart/create-a-repo) for your project and then add it to your local repo [as a remote](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories):
 
-#### Deploy from Our Template
+```bash
+git remote add origin https://github.com/<org>/<repo>.git
+```
+
+Next, [create a project in Vercel](https://vercel.com/docs/projects/overview#creating-a-project) and [link it to your GitHub repo](https://vercel.com/docs/git#deploying-a-git-repository).
 
-Alternatively, you can deploy using our template by clicking on the Deploy button below.
+In order for Vercel to upload source maps to Sentry when building your app, it needs an auth token. To use the personal token set up by the wizard, add an [environment variable](https://vercel.com/docs/projects/environment-variables) to your Vercel project with the key `SENTRY_AUTH_TOKEN` and the value you'll find in `.sentryclirc` at the root level of your project. To use an org-wide token instead, set up the Vercel Sentry Integration. (You can read more about the integration [on Vercel](https://vercel.com/integrations/sentry) and in [the Sentry docs](https://docs.sentry.io/product/integrations/deployment/vercel/).)
 
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/with-sentry&project-name=with-sentry&repository-name=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)
+Finally, commit your app and push it to GitHub:
 
-## Sentry Integration
+```bash
+git add .
+git commit -m "initial commit"
+git push
+```
 
-Sentry’s Vercel Integration connects your Sentry and Vercel projects to automatically upload source maps and notify Sentry of release deployment. Learn more about this integration in [Sentry’s full documentation](https://docs.sentry.io/product/integrations/vercel/).
+This will trigger a deployment in Vercel. Head over to your [Vercel dashboard](https://vercel.com/dashboard) and click on your project and then "Visit" to see the results!

examples/with-sentry/next.config.js

@@ -9,7 +9,7 @@ const moduleExports = {
   // Your existing module.exports
 }
 
-const SentryWebpackPluginOptions = {
+const sentryWebpackPluginOptions = {
   // Additional config options for the Sentry Webpack plugin. Keep in mind that
   // the following options are set automatically, and overriding them is not
   // recommended:
@@ -21,4 +21,4 @@ const SentryWebpackPluginOptions = {
 
 // Make sure adding Sentry options is the last code to run before exporting, to
 // ensure that your source maps include changes from all other Webpack plugins
-module.exports = withSentryConfig(moduleExports, SentryWebpackPluginOptions)
+module.exports = withSentryConfig(moduleExports, sentryWebpackPluginOptions)

examples/with-sentry/pages/index.js

@@ -18,8 +18,8 @@ const Index = () => (
     </p>
     <ol>
       <li>
-        API route exceptions (note that 1-3 are not expected to work if deployed
-        to Vercel yet)
+        API route exceptions (note that 1 and 2 are not expected to work if
+        deployed to Vercel yet)
       </li>
       <ol>
         <li>

examples/with-sentry/pages/ssr/test2.js

@@ -1,7 +1,7 @@
 const Test2 = () => <h1>SSR Test 2</h1>
 
 export async function getServerSideProps() {
-  throw new Error('SSR Test 2')
+  return Promise.reject(Error('SSR Test 2'))
 }
 
 export default Test2