Add example on how to expose the instance globally (#413)

examples/next-csr-app/package.json

@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "@croct/plug-react": "latest",
-    "next": "^12.3.3",
+    "next": "^14.0.4",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },

examples/next-ssr-app/components/GlobalCroct.test.tsx

@@ -0,0 +1,19 @@
+import {render} from '@testing-library/react';
+import croct, {Plug} from '@croct/plug';
+import {GlobalCroct} from '@/components/GlobalCroct';
+
+declare global {
+    interface Window {
+        croct?: Plug;
+    }
+}
+
+describe('<Providers />', () => {
+    it('should expose the Croct instance on the global scope', () => {
+        expect(window.croct).toBeUndefined();
+
+        render(<GlobalCroct />);
+
+        expect(window.croct).toBe(croct);
+    });
+});

examples/next-ssr-app/components/GlobalCroct.ts

@@ -0,0 +1,31 @@
+'use client';
+
+import {FunctionComponent, useEffect} from 'react';
+import croct from '@croct/plug';
+
+/*
+ * NOTE
+ *
+ * This component makes the `croct` instance available on the `window`
+ * object so tools like Google Tag Manager can use it.
+ *
+ * Although functional, we do not recommend this approach as it can
+ * lead to problems like race conditions where Google Tag Manager may
+ * run before the `useEffect` hook.
+ *
+ * For more reliable and efficient event tracking, use the `useCroct`
+ * hook directly in your application.
+ */
+
+export const GlobalCroct: FunctionComponent = () => {
+    useEffect(
+        () => {
+            if (!('croct' in window)) {
+                Object.assign(window, {croct: croct});
+            }
+        },
+        [],
+    );
+
+    return null;
+};

examples/next-ssr-app/components/Providers.test.tsx

@@ -52,7 +52,7 @@ describe('<Providers />', () => {
             {
                 appId: APP_ID,
                 clientId: clientId,
-                children: 'foo',
+                children: expect.arrayContaining(['foo']),
             },
             expect.anything(),
         );

examples/next-ssr-app/components/Providers.tsx

@@ -2,13 +2,15 @@ import {PropsWithChildren, ReactElement} from 'react';
 import {CroctProvider} from '@croct/plug-react/CroctProvider';
 import {headers} from 'next/headers';
 import {Header} from '@/lib/constants';
+import {GlobalCroct} from '@/components/GlobalCroct';
 
 export default function Providers({children}: PropsWithChildren): ReactElement {
     return (
         <CroctProvider
             appId={process.env.NEXT_PUBLIC_CROCT_APP_ID!}
             clientId={headers().get(Header.CLIENT_ID) ?? undefined}
         >
+            <GlobalCroct />
             {children}
         </CroctProvider>
     );