feat: Allow users to customize fetch behavior (#1599)

src/__tests__/request.test.ts

@@ -186,6 +186,23 @@ describe('request', () => {
             })
         })
 
+        it('supports nextOptions parameter', async () => {
+            request(
+                createRequest({
+                    fetchOptions: { cache: 'force-cache', next: { revalidate: 0, tags: ['test'] } },
+                })
+            )
+            await flushPromises()
+
+            expect(mockedFetch).toHaveBeenCalledWith(
+                expect.anything(),
+                expect.objectContaining({
+                    cache: 'force-cache',
+                    next: { revalidate: 0, tags: ['test'] },
+                })
+            )
+        })
+
         describe('keepalive with fetch and large bodies can cause some browsers to reject network calls', () => {
             it.each([
                 ['always keepalive with small json POST', 'POST', 'small', undefined, true, ''],

src/posthog-core.ts

@@ -663,6 +663,10 @@ export class PostHog {
         }
         options.compression = options.compression === 'best-available' ? this.compression : options.compression
 
+        // Specially useful if you're doing SSR with NextJS
+        // Users must be careful when tweaking `cache` because they might get out-of-date feature flags
+        options.fetchOptions = options.fetchOptions || this.config.fetch_options
+
         request({
             ...options,
             callback: (response) => {

src/request.ts

@@ -165,6 +165,7 @@ const _fetch = (options: RequestOptions) => {
         keepalive: options.method === 'POST' && (estimatedSize || 0) < KEEP_ALIVE_THRESHOLD,
         body,
         signal: aborter?.signal,
+        ...options.fetchOptions,
     })
         .then((response) => {
             return response.text().then((responseText) => {

src/types.ts

@@ -333,6 +333,15 @@ export interface PostHogConfig {
         events_burst_limit?: number
     }
 
+    /** Used when sending data via `fetch`, use with care, this is intentionally meant to be used with NextJS `fetch`
+     *  Incorrect usage may cause out-of-date data for feature flags, actions tracking, etc.
+     *  See https://nextjs.org/docs/app/api-reference/functions/fetch#fetchurl-options
+     */
+    fetch_options?: {
+        cache?: RequestInit['cache']
+        next_options?: NextOptions
+    }
+
     /**
      * PREVIEW - MAY CHANGE WITHOUT WARNING - DO NOT USE IN PRODUCTION
      * whether to wrap fetch and add tracing headers to the request
@@ -440,6 +449,9 @@ export interface RequestResponse {
 
 export type RequestCallback = (response: RequestResponse) => void
 
+// See https://nextjs.org/docs/app/api-reference/functions/fetch#fetchurl-options
+type NextOptions = { revalidate: false | 0 | number; tags: string[] }
+
 export interface RequestOptions {
     url: string
     // Data can be a single object or an array of objects when batched
@@ -452,6 +464,10 @@ export interface RequestOptions {
     timeout?: number
     noRetries?: boolean
     compression?: Compression | 'best-available'
+    fetchOptions?: {
+        cache?: RequestInit['cache']
+        next?: NextOptions
+    }
 }
 
 // Queued request types - the same as a request but with additional queueing information