diff --git a/contents/docs/error-tracking/_snippets/nextjs-upload-source-maps.mdx b/contents/docs/error-tracking/_snippets/nextjs-upload-source-maps.mdx index 4f7b421c1d97..c66d1a869f8b 100644 --- a/contents/docs/error-tracking/_snippets/nextjs-upload-source-maps.mdx +++ b/contents/docs/error-tracking/_snippets/nextjs-upload-source-maps.mdx @@ -1,4 +1,4 @@ -We provide a helper package that will hook into the Next.js build process and upload sourcemaps for your client and server code. This process is enabled by default for production builds but you can disable it by setting `enabled` to `false` in the `sourcemaps` object. +We provide a helper package that will hook into the Next.js build process and upload source maps for your client and server code. This process is enabled by default for production builds but you can disable it by setting `enabled` to `false` in the `sourcemaps` object. #### 1. Install package diff --git a/contents/docs/error-tracking/installation/nuxt-3-6.mdx b/contents/docs/error-tracking/installation/nuxt-3-6.mdx new file mode 100644 index 000000000000..634f9de01676 --- /dev/null +++ b/contents/docs/error-tracking/installation/nuxt-3-6.mdx @@ -0,0 +1,97 @@ +--- +title: Nuxt error tracking installation (v3.6 and below) +showStepsToc: true +--- + +import { Steps, Step } from 'components/Docs/Steps' + +import CLIUpload from "../_snippets/cli/upload.mdx" +import CLIAuthenticate from "../_snippets/cli/authenticate.mdx" +import CLIDownload from "../_snippets/cli/download.mdx" +import InstallNuxt from "../../integrate/_snippets/install-nuxt.mdx" +import StepVerifyErrorTracking from "./_snippets/step-verify-error-tracking.mdx" +import StepUploadSourceMaps from "./_snippets/step-upload-source-maps.tsx" + +For older versions of Nuxt, you'll need to manually set up error tracking and source map uploads. + + + + + + + + + + +Before proceeding, confirm that you can [capture events](/docs/libraries/nuxt-js#capture-custom-events) using `posthog.capture('test_event')`. + + + + + +To send errors directly using the PostHog client, import it and use the `captureException` method like this: + +```vue component.vue + +``` + +On the server side, you can use the `posthog` object directly. + +```js file=server/api/example.js focusOnLines=4-21 +export default defineEventHandler(async (event) => { + const distinctId = getCookie(event, 'distinct_id') + + const { PostHog } = await import('posthog-node'); + const runtimeConfig = useRuntimeConfig() + + const posthog = new PostHog( + runtimeConfig.public.posthogPublicKey, + { + host: runtimeConfig.public.posthogHost, + } + ); + + try { + const results = await DB.query.users.findMany() + return results + } catch (error) { + posthog.captureException(error) + } +}) +``` + + + + + +Update your `posthog.client.js` to add an error hook. + +```js +export default defineNuxtPlugin((nuxtApp) => { + ... + nuxtApp.hook('vue:error', (error) => { + posthogClient.captureException(error) + }) + ... +}) +``` + + + + + + + + + + + + + diff --git a/contents/docs/error-tracking/installation/nuxt.mdx b/contents/docs/error-tracking/installation/nuxt.mdx index 48b230e6a323..cf349b8c6977 100644 --- a/contents/docs/error-tracking/installation/nuxt.mdx +++ b/contents/docs/error-tracking/installation/nuxt.mdx @@ -12,22 +12,83 @@ import InstallNuxt from "../../integrate/_snippets/install-nuxt.mdx" import StepVerifyErrorTracking from "./_snippets/step-verify-error-tracking.mdx" import StepUploadSourceMaps from "./_snippets/step-upload-source-maps.tsx" +For Nuxt v3.7 and above, we recommend using the official `@posthog/nuxt` module which provides automatic error tracking with built-in source map support. + - + - +Install the PostHog Nuxt module using your package manager: - + + +```bash file=npm +npm install @posthog/nuxt +``` + +```bash file=Yarn +yarn add @posthog/nuxt +``` + +```bash file=pnpm +pnpm add @posthog/nuxt +``` + +```bash file=Bun +bun add @posthog/nuxt +``` - + + +Add the module to your `nuxt.config.ts` file: + +```typescript file=nuxt.config.ts +export default defineNuxtConfig({ + modules: ['@posthog/nuxt'], + + // Enable source maps generation in both vue and nitro + sourcemap: { + client: 'hidden' + }, + nitro: { + rollupConfig: { + output: { + sourcemapExcludeSources: false, + }, + }, + }, + + posthogConfig: { + publicKey: '', // Find it in project settings https://app.posthog.com/settings/project + host: '', // Optional: defaults to https://us.i.posthog.com. Use https://eu.i.posthog.com for EU region + clientConfig: { + capture_exceptions: true, // Enables automatic exception capture on the client side (Vue) + }, + serverConfig: { + enableExceptionAutocapture: true, // Enables automatic exception capture on the server side (Nitro) + }, + sourcemaps: { + enabled: true, + envId: '', // Your environment ID from PostHog settings https://app.posthog.com/settings/environment#variables + personalApiKey: '', // Your personal API key from PostHog settings https://app.posthog.com/settings/user-api-keys + project: 'my-application', // Optional: defaults to git repository name + version: '1.0.0', // Optional: defaults to current git commit + }, + }, +}) +``` -Before proceeding, confirm that you can [capture events](/docs/libraries/nuxt-js#capture-custom-events) using `posthog.capture('test_event')`. +The module will automatically: +- Initialize PostHog on both Vue (client side) and Nitro (server side) +- Capture exceptions on both client and server +- Generate and upload source maps during build - + -To send errors directly using the PostHog client, import it and use the `captureException` method like this: +Our module if set up as shown above already captures both client and server side exceptions automatically. + +To send errors manually on the client side, import it and use the `captureException` method like this: ```vue component.vue ``` -On the server side, you can use the `posthog` object directly. +On the server side instantiate PostHog using: ```js file=server/api/example.js focusOnLines=4-21 export default defineEventHandler(async (event) => { @@ -67,29 +128,30 @@ export default defineEventHandler(async (event) => { - + -Update your `posthog.client.js` to add an error hook +Build your project for production by running the following command: -```js -export default defineNuxtPlugin((nuxtApp) => { - ... - nuxtApp.hook('vue:error', (error) => { - posthogClient.captureException(error) - }) - ... -}) +```bash +nuxt build ``` +The PostHog module will automatically generate and upload source maps to PostHog during the build process. + - + +Before proceeding, confirm that source maps are being properly uploaded. - +You can verify the injection is successful by checking your `.mjs.map` source map files for `//# chunkId=` comments. Make sure to serve these injected files in production, PostHog will check for the `//# chunkId` comments to display the correct stack traces. - + + Check symbol sets in PostHog + - \ No newline at end of file + + + diff --git a/contents/docs/error-tracking/upload-source-maps/nuxt.mdx b/contents/docs/error-tracking/upload-source-maps/nuxt.mdx index f824422aadb7..95e6a79f8be8 100644 --- a/contents/docs/error-tracking/upload-source-maps/nuxt.mdx +++ b/contents/docs/error-tracking/upload-source-maps/nuxt.mdx @@ -7,6 +7,16 @@ import CLIDownload from '../_snippets/cli/download.mdx' import CLIAuthenticate from '../_snippets/cli/authenticate.mdx' import StepVerifySourceMapUpload from './_snippets/step-verify-source-map-upload.mdx' +## Nuxt v3.7 and above + +For Nuxt v3.7 and above, the `@posthog/nuxt` module automatically handles source map generation and upload during the build process. + +No manual configuration is needed - follow the [Nuxt error tracking installation guide](/docs/error-tracking/installation/nuxt) to set up the module, and source maps are automatically generated and uploaded when you build your project. + +## Nuxt v3.6 and below + +For older versions of Nuxt, you'll need to manually configure source map generation and upload using the PostHog CLI. + @@ -14,7 +24,7 @@ import StepVerifySourceMapUpload from './_snippets/step-verify-source-map-upload - + You can hook into the `close` event to generate and upload source maps for your Nuxt application like this: @@ -53,13 +63,13 @@ Build your project for production by running the following command: nuxt build ``` -Post-build scripts should automatically generate and upload sourcemaps to PostHog. +Post-build scripts should automatically generate and upload source maps to PostHog. - + -Before proceeding, confirm that sourcemaps are being properly uploaded. +Before proceeding, confirm that source maps are being properly uploaded. You can verify the injection is successful by checking your `.mjs.map` source map files for `//# chunkId=` comments. Make sure to serve these injected files in production, PostHog will check for the `//# chunkId` comments to display the correct stack traces. diff --git a/contents/docs/libraries/nuxt-js-2.mdx b/contents/docs/libraries/nuxt-js-2.mdx new file mode 100644 index 000000000000..fb2953172528 --- /dev/null +++ b/contents/docs/libraries/nuxt-js-2.mdx @@ -0,0 +1,97 @@ +--- +title: Nuxt.js (v2.16 and below) +icon: >- + https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/frameworks/nuxt.svg +--- + +PostHog makes it easy to get data about usage of your [Nuxt.js](https://nuxt.com/) app. Integrating PostHog into your app enables analytics about user behavior, custom events capture, session replays, feature flags, and more. + +These docs are for Nuxt v2.16 and below. + +We are going to implement PostHog as a [Nuxt.js integration](https://nuxtjs.org/docs/2.x/directory-structure/plugins) which gives us the possibility to inject +the `posthog` object and make it available across our application. + +## Installation + +The first thing you want to do is to install the [posthog-js library](/docs/integrate/client/js) in your project - so add it using your package manager: + +import InstallWebPackageManagers from "../integrate/_snippets/install-web-package-managers.mdx" + + + +After that we want to create an app in `plugins/posthog/index.js` + +```javascript +import posthog from 'posthog-js' +import Vue from 'vue' + +export default function({ app: { router } }, inject) { + // Init PostHog + posthog.init('', { + api_host: '', + defaults: '', + capture_pageview: false, + loaded: () => posthog.identify('unique_id') // If you can already identify your user + }) + + // Inject PostHog into the application and make it available via this.$posthog (or app.$posthog) + inject('posthog', posthog) + + // Make sure that pageviews are captured with each route change + router.afterEach(to => { + Vue.nextTick(() => { + /* Note: this might also be a good place to call posthog.register(...) in order to update your properties + on each page view + */ + posthog.capture('$pageview', { + $current_url: to.fullPath + }) + }) + }) +} + +``` + +Finally, we need to activate it on the client side in our `nuxt.config.js` + +```js +plugins: [ + ... + { src: './plugins/posthog', mode: 'client' } + ], +``` + +## Usage + +By using the example code above you can now use PostHog across your app with `this.$posthog` or `app.$posthog` - depending on the context. +Compare with the [Nuxt.js docs](https://nuxtjs.org/docs/2.x/directory-structure/plugins#inject-in-root--context) on further details when to use `app.$posthog` or `this.$posthog`. + +Let's say for example the user makes a purchase you could track an event like that: + +```js-web + + + +``` + +## Next steps + +For any technical questions for how to integrate specific PostHog features into Nuxt (such as analytics, feature flags, A/B testing, surveys, etc.), have a look at our [JavaScript Web](/docs/libraries/js) and [Node](/docs/libraries/node) SDK docs. + +Alternatively, the following tutorials can help you get started: + +- [How to set up analytics in Nuxt](/tutorials/nuxt-analytics) +- [How to set up feature flags in Nuxt](/tutorials/nuxt-feature-flags) +- [How to set up A/B tests in Nuxt](/tutorials/nuxtjs-ab-tests) +- [How to set up surveys in Nuxt](/tutorials/nuxt-surveys) + diff --git a/contents/docs/libraries/nuxt-js-3-6.mdx b/contents/docs/libraries/nuxt-js-3-6.mdx new file mode 100644 index 000000000000..82075efd31fe --- /dev/null +++ b/contents/docs/libraries/nuxt-js-3-6.mdx @@ -0,0 +1,114 @@ +--- +title: Nuxt.js (v3.0 to v3.6) +icon: >- + https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/frameworks/nuxt.svg +--- + +import DetailSetUpReverseProxy from "../integrate/_snippets/details/set-up-reverse-proxy.mdx" +import DetailGroupProductsInOneProject from "../integrate/_snippets/details/group-products-in-one-project.mdx" + +PostHog makes it easy to get data about usage of your [Nuxt.js](https://nuxt.com/) app. Integrating PostHog into your app enables analytics about user behavior, custom events capture, session replays, feature flags, and more. + +These docs are for Nuxt v3.0 to v3.6. You can see a working example of the Nuxt v3.0 integration in our [Nuxt.js demo app](https://github.com/PostHog/posthog-js/tree/master/playground/nuxtjs) + +## Setting up PostHog on the client side + +import NuxtInstall from "../integrate/_snippets/install-nuxt.mdx" + + + +PostHog can then be accessed throughout your Nuxt.js using the provider accessor, for example: + +```vue filename=index.vue + +``` + +See the [JavaScript SDK docs](/docs/libraries/js/features) for all usable functions, such as: +- [Capture custom event capture, identify users, and more.](/docs/libraries/js/features#capturing-events) +- [Feature flags including variants and payloads.](/docs/libraries/js/features#feature-flags) + + + + + +## Setting up PostHog on the server side + +Install `posthog-node` using your package manager: + +import InstallNodePackageManagers from "../integrate/_snippets/install-node-package-managers.mdx" + + + +Add your PostHog API key and host to your `nuxt.config.js` file. If you've already done this when adding PostHog to the client side, you can skip this step. + +```js file=nuxt.config.js +export default defineNuxtConfig({ + runtimeConfig: { + public: { + posthogPublicKey: '', + posthogHost: '', + posthogDefaults: '', + } + } +}) +``` + +Initialize the PostHog Node client where you'd like to use it on the server side. For example, in a [server route](https://nuxt.com/docs/guide/directory-structure/server#server-routes): + +```js file=server/api/example.js focusOnLines=7-27 +export default defineEventHandler(async (event) => { + const rawCookie = getCookie(event, `ph_${runtimeConfig.public.posthogPublicKey}_posthog`) + const distinctID = rawCookie ? JSON.parse(rawCookie)?.distinct_id : undefined + const url = getRequestURL(event) + const query = getQuery(event) + + const { PostHog } = await import('posthog-node'); + const runtimeConfig = useRuntimeConfig() + + const posthog = new PostHog( + runtimeConfig.public.posthogPublicKey, + { + host: runtimeConfig.public.posthogHost, + } + ); + + posthog.capture({ + event: 'api_call', + distinctId: distinctId, + properties: { + $current_url: url, + query: query + } + }) + posthog.shutdown() + + return { + message: "example response" + } +}) +``` + +> **Note**: Make sure to _always_ call `posthog.shutdown()` after capturing events from the server-side. +> PostHog queues events into larger batches, and this call forces all batched events to be flushed immediately. + +See the [Node SDK docs](/docs/libraries/node) for all usable functions, such as: +- [Capture custom event capture, identify users, and more.](/docs/libraries/node#capturing-events) +- [Feature flags including variants and payloads.](/docs/libraries/node#feature-flags) + +## Next steps + +For any technical questions for how to integrate specific PostHog features into Nuxt (such as analytics, feature flags, A/B testing, surveys, etc.), have a look at our [JavaScript Web](/docs/libraries/js) and [Node](/docs/libraries/node) SDK docs. + +Alternatively, the following tutorials can help you get started: + +- [How to set up analytics in Nuxt](/tutorials/nuxt-analytics) +- [How to set up feature flags in Nuxt](/tutorials/nuxt-feature-flags) +- [How to set up A/B tests in Nuxt](/tutorials/nuxtjs-ab-tests) +- [How to set up surveys in Nuxt](/tutorials/nuxt-surveys) + diff --git a/contents/docs/libraries/nuxt-js.mdx b/contents/docs/libraries/nuxt-js.mdx index 1a9500839421..749c524454bb 100644 --- a/contents/docs/libraries/nuxt-js.mdx +++ b/contents/docs/libraries/nuxt-js.mdx @@ -9,66 +9,71 @@ import DetailGroupProductsInOneProject from "../integrate/_snippets/details/grou PostHog makes it easy to get data about usage of your [Nuxt.js](https://nuxt.com/) app. Integrating PostHog into your app enables analytics about user behavior, custom events capture, session replays, feature flags, and more. -These docs are aimed at Nuxt.js users who run Nuxt in `spa` or `universal` mode. You can see a working example of the Nuxt v3.0 integration in our [Nuxt.js demo app](https://github.com/PostHog/posthog-js/tree/master/playground/nuxtjs) +For Nuxt 3.7 and above, we recommend using the official `@posthog/nuxt` module. This module provides: +- Automatic PostHog client initialization for both Vue (client side) and Nitro (server side) +- Automatic exception capture for error tracking +- Source map configuration and upload for error tracking -## Nuxt v3.0 and above +## Installation -### Setting up PostHog on the client side +Install the PostHog Nuxt module using your package manager: -import NuxtInstall from "../integrate/_snippets/install-nuxt.mdx" + - +```bash file=npm +npm install @posthog/nuxt +``` -PostHog can then be accessed throughout your Nuxt.js using the provider accessor, for example: +```bash file=Yarn +yarn add @posthog/nuxt +``` -```vue filename=index.vue - +```bash file=pnpm +pnpm add @posthog/nuxt ``` -See the [JavaScript SDK docs](/docs/libraries/js/features) for all usable functions, such as: -- [Capture custom event capture, identify users, and more.](/docs/libraries/js/features#capturing-events) -- [Feature flags including variants and payloads.](/docs/libraries/js/features#feature-flags) +```bash file=Bun +bun add @posthog/nuxt +``` - + - +## Configuration -### Setting up PostHog on the server side +Add the module to your `nuxt.config.ts` file: -1. Install `posthog-node` using your package manager: +```typescript file=nuxt.config.ts +export default defineNuxtConfig({ + modules: ['@posthog/nuxt'], + posthogConfig: { + publicKey: '', // Find it in project settings https://app.posthog.com/settings/project + host: '', // Optional: defaults to https://us.i.posthog.com. Use https://eu.i.posthog.com for EU region + clientConfig: { + // Optional: PostHog client configuration options + }, + }, +}) +``` -import InstallNodePackageManagers from "../integrate/_snippets/install-node-package-managers.mdx" +## Usage on the client side - +You can access the PostHog client in your Vue components using: -2. Add your PostHog API key and host to your `nuxt.config.js` file. If you've already done this when adding PostHog to the client side, you can skip this step. +```vue filename=index.vue + ``` -3. Initialize the PostHog Node client where you'd like to use it on the server side. For example, in a [server route](https://nuxt.com/docs/guide/directory-structure/server#server-routes): +## Usage on the server side + +Instantiate PostHog using: -```js file=server/api/example.js focusOnLines=7-27 +```js file=server/api/example.js focusOnLines=4-21 export default defineEventHandler(async (event) => { - const rawCookie = getCookie(event, `ph_${runtimeConfig.public.posthogPublicKey}_posthog`) - const distinctID = rawCookie ? JSON.parse(rawCookie)?.distinct_id : undefined - const url = getRequestURL(event) - const query = getQuery(event) + const distinctId = getCookie(event, 'distinct_id') const { PostHog } = await import('posthog-node'); const runtimeConfig = useRuntimeConfig() @@ -80,104 +85,22 @@ export default defineEventHandler(async (event) => { } ); - posthog.capture({ - event: 'api_call', - distinctId: distinctId, - properties: { - $current_url: url, - query: query - } - }) - posthog.shutdown() - - return { - message: "example response" - } + posthog.capture('') }) ``` -> **Note**: Make sure to _always_ call `posthog.shutdown()` after capturing events from the server-side. -> PostHog queues events into larger batches, and this call forces all batched events to be flushed immediately. - -See the [Node SDK docs](/docs/libraries/node) for all usable functions, such as: -- [Capture custom event capture, identify users, and more.](/docs/libraries/node#capturing-events) -- [Feature flags including variants and payloads.](/docs/libraries/node#feature-flags) - -## Nuxt v2.16 and below - -We are going to implement PostHog as a [Nuxt.js integration](https://nuxtjs.org/docs/2.x/directory-structure/plugins) which gives us the possibility to inject -the `posthog` object and make it available across our application. - -The first thing you want to do is to install the [posthog-js library](/docs/integrate/client/js) in your project - so add it using your package manager: - -import InstallWebPackageManagers from "../integrate/_snippets/install-web-package-managers.mdx" - - - -After that we want to create a app in `plugins/posthog/index.js` - -```javascript -import posthog from 'posthog-js' -import Vue from 'vue' - -export default function({ app: { router } }, inject) { - // Init PostHog - posthog.init('', { - api_host: '', - defaults: '', - capture_pageview: false, - loaded: () => posthog.identify('unique_id') // If you can already identify your user - }) - - // Inject PostHog into the application and make it available via this.$posthog (or app.$posthog) - inject('posthog', posthog) - - // Make sure that pageviews are captured with each route change - router.afterEach(to => { - Vue.nextTick(() => { - /* Note: this might also be a good place to call posthog.register(...) in order to update your properties - on each page view - */ - posthog.capture('$pageview', { - $current_url: to.fullPath - }) - }) - }) -} - -``` - -Finally, we need to activate it on the client side in our `nuxt.config.js` - -```js -plugins: [ - ... - { src: './plugins/posthog', mode: 'client' } - ], -``` + -### Usage + -By using the example code above you can now use PostHog across your app with `this.$posthog` or `app.$posthog` - depending on the context. -Compare with the [Nuxt.js docs](https://nuxtjs.org/docs/2.x/directory-structure/plugins#inject-in-root--context) on further details when to use `app.$posthog` or `this.$posthog`. +## Error tracking -Let's say for example the user makes a purchase you could track an event like that: +For a detailed error tracking installation guide, including automatic exception capture and source map configuration, see the [Nuxt error tracking installation docs](/docs/error-tracking/installation/nuxt). -```js-web - +## Troubleshooting - -``` +**TypeScript errors in posthog config:** +Remove the `.nuxt` directory and rebuild your project to regenerate config types. ## Next steps diff --git a/src/navs/index.js b/src/navs/index.js index 78653753ffb2..466f7c79892c 100644 --- a/src/navs/index.js +++ b/src/navs/index.js @@ -2001,6 +2001,20 @@ export const docsMenu = { { name: 'Nuxt.js', url: '/docs/libraries/nuxt-js', + children: [ + { + name: '3.7 and above', + url: '/docs/libraries/nuxt-js', + }, + { + name: '3.0 to 3.6', + url: '/docs/libraries/nuxt-js-3-6', + }, + { + name: '2.16 and below', + url: '/docs/libraries/nuxt-js-2', + }, + ], }, { name: 'n8n', @@ -3691,6 +3705,16 @@ export const docsMenu = { { name: 'Nuxt', url: '/docs/error-tracking/installation/nuxt', + children: [ + { + name: '3.7 and above', + url: '/docs/error-tracking/installation/nuxt', + }, + { + name: '3.6 and below', + url: '/docs/error-tracking/installation/nuxt-3-6', + }, + ], }, { name: 'SvelteKit',