feat: API event handler to proxy event through Nitro server (#36)

* feat: add API event handler, proxy configuration and documentation
- Implement event handling in src/runtime/server/api/event.post.ts
- Update playground/nuxt.config.ts to enable proxy
- Enhance src/module.ts with proxy options and server handler logic
- Add proxy and proxyBaseURL options to README and module.ts

* chore: minor updates

---------

Co-authored-by: Johann Schopplich <[email protected]>

Author: asonnleitner

README.md

@@ -78,6 +78,8 @@ With this setup, you can omit the `plausible` key in your Nuxt configuration.
 | `autoPageviews`        | `boolean`  | `true`                       | Track the current page and all further pages automatically. Disable this if you want to manually manage pageview tracking.                                                                                                                      |
 | `autoOutboundTracking` | `boolean`  | `false`                      | Track all outbound link clicks automatically. If enabled, a [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) automagically detects link nodes throughout the application and binds `click` events to them. |
 | `logIgnoredEvents`     | `boolean`  | `false`                      | Log events to the console if they are ignored.                                                                                                                                                                                                  |
+| `proxy`                | `boolean`  | `false`                      | Whether to proxy the event endpoint through the current origin.                                                                                                                                                                                 |
+| `proxyBaseURL`         | `string`   | `'/api/event'`               | The base URL to proxy the event endpoint through.                                                                                                                                                                                               |
 
 ## Composables
 

playground/nuxt.config.ts

@@ -6,5 +6,6 @@ export default defineNuxtConfig({
   plausible: {
     autoPageviews: false,
     autoOutboundTracking: false,
+    proxy: true,
   },
 })

src/module.ts

@@ -2,6 +2,7 @@ import { defu } from 'defu'
 import {
   addImports,
   addPlugin,
+  addServerHandler,
   createResolver,
   defineNuxtModule,
   useLogger,
@@ -90,6 +91,20 @@ export interface ModuleOptions {
    * @default false
    */
   logIgnoredEvents?: boolean
+
+  /**
+   * Whether to proxy the event endpoint through the current origin.
+   *
+   * @default false
+   */
+  proxy?: boolean
+
+  /**
+   * The base URL to proxy the event endpoint through.
+   *
+   * @default '/api/event'
+   */
+  proxyBaseURL?: string
 }
 
 export default defineNuxtModule<ModuleOptions>({
@@ -112,6 +127,8 @@ export default defineNuxtModule<ModuleOptions>({
     autoPageviews: true,
     autoOutboundTracking: false,
     logIgnoredEvents: false,
+    proxy: false,
+    proxyBaseURL: '/api/event',
   },
   setup(options, nuxt) {
     const logger = useLogger('plausible')
@@ -142,6 +159,23 @@ export default defineNuxtModule<ModuleOptions>({
     // Transpile runtime
     nuxt.options.build.transpile.push(resolve('runtime'))
 
+    if (nuxt.options.runtimeConfig.public.plausible.proxy) {
+      const proxyBaseURL = nuxt.options.runtimeConfig.public.plausible.proxyBaseURL
+
+      const hasUserProvidedProxyBaseURL
+        = nuxt.options.serverHandlers.find(handler => handler.route?.startsWith(proxyBaseURL))
+        || nuxt.options.devServerHandlers.find(handler => handler.route?.startsWith(proxyBaseURL))
+      if (hasUserProvidedProxyBaseURL) {
+        throw new Error(`The route \`${proxyBaseURL}\` is already in use. Please use the \`proxyBaseURL\` option to change the base URL of the proxy endpoint.`)
+      }
+
+      addServerHandler({
+        route: proxyBaseURL,
+        handler: resolve('runtime/server/api/event.post'),
+        method: 'post',
+      })
+    }
+
     addImports(
       ['useTrackEvent', 'useTrackPageview'].map(name => ({
         name,

src/runtime/plugin.client.ts

@@ -17,6 +17,7 @@ export default defineNuxtPlugin({
       ...options,
       logIgnored: options.logIgnoredEvents,
       domain: options.domain || window.location.hostname,
+      apiHost: options.proxy ? window.location.origin : options.apiHost,
     })
 
     return {

src/runtime/server/api/event.post.ts

@@ -0,0 +1,52 @@
+import { joinURL } from 'ufo'
+import { createError, defineEventHandler, getRequestHeader, getRequestIP, readBody } from 'h3'
+import type { ModuleOptions } from '../../../module'
+import { useRuntimeConfig } from '#imports'
+
+export default defineEventHandler(async (event) => {
+  const config = useRuntimeConfig(event)
+  const options = config.public.plausible as Required<ModuleOptions>
+
+  try {
+    if (!options?.apiHost) {
+      throw createError({
+        statusCode: 500,
+        message: 'Plausible API host not configured',
+      })
+    }
+
+    const target = joinURL(options.apiHost, 'api/event')
+    const body = await readBody(event)
+
+    const headers = new Headers({
+      'Content-Type': 'application/json',
+      ...Object.fromEntries([
+        ['User-Agent', getRequestHeader(event, 'user-agent')],
+        ['X-Forwarded-For', getRequestIP(event, { xForwardedFor: true })],
+      ].filter(([_, value]) => value != null)),
+    })
+
+    const result = await globalThis.$fetch(target, {
+      method: 'POST',
+      headers: headers,
+      body,
+      retry: 2,
+      timeout: 5000,
+      onRequestError: ({ request, error }) => {
+        console.error(`Failed to send request to ${request}: ${error.message}`)
+      },
+    })
+
+    return result
+  }
+  catch (error) {
+    if (error instanceof Error && error.name === 'FetchError') {
+      throw createError({
+        statusCode: 502,
+        message: 'Failed to reach Plausible analytics service',
+      })
+    }
+
+    throw error
+  }
+})