# JavaScript client for popular frameworks

If you want to install our client-side library as a package—rather than using [our JavaScript snippet](/integrations/data-in/connections/javascript/)—you’ll use our `@customerio/cdp-analytics-browser` package. This guide covers installation for popular JavaScript frameworks.

## Client-side vs. server-side[](#client-side-vs-server-side)

The instructions on this page are for client-side implementations. In general, we prefer the client-side library to support things like in-app messaging and automatic page tracking. But, if you need to use a server-side implementation, see [our Node.js library](/integrations/data-in/connections/servers/node/).

Feature

Browser Library

Node.js Library

**Package**

`@customerio/cdp-analytics-browser`

`@customerio/cdp-analytics-node`

**Page context**

Automatic: captured from DOM

Manual: you must provide URL, path, etc.

**Identity persistence**

Automatic: stored in cookies/localStorage

Manual: you must pass `userId` or `anonymousId` on every call

**In-app message support**

**Use for**

Client-side tracking, single page applications (SPAs), in-app messages

Server-side tracking, API routes, background jobs

## React[](#react)

For React-based applications, you’ll want to create a singleton instance of the analytics client that you can import throughout your app. This prevents you from initializing the library multiple times and ensures consistent tracking.

1.  Go to *Data & Integrations > Integrations*. In the **Connections** tab, pick the **JavaScript** integration to get your *Write Key*.
    
2.  Install the package:
    
    ```bash
    npm install @customerio/cdp-analytics-browser
    ```
    
3.  Create an analytics module (for example, `src/analytics.js`):
    
    ```javascript
    import { AnalyticsBrowser } from '@customerio/cdp-analytics-browser';
    
    export const cioanalytics = AnalyticsBrowser.load({
      // cdnURL: 'https://cdp-eu.customer.io', // Set if you're in our EU data center
      writeKey: '<YOUR_WRITE_KEY>'
    });
    ```
    
4.  Import and use the analytics instance in your components:
    
    ```jsx
    import { cioanalytics } from './analytics';
    
    function SignupButton() {
      const handleClick = () => {
        cioanalytics.track('Signup Started');
      };
    
      return <button onClick={handleClick}>Sign Up</button>;
    }
    ```
    

### Track page views in React[](#track-page-views-in-react)

If you use client-side routing (like React Router), you’ll need to track page views manually when routes change. For example, here’s how you might track page views in React Router:

```jsx
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';
import { cioanalytics } from './analytics';

function usePageTracking() {
  const location = useLocation();

  useEffect(() => {
    cioanalytics.page();
  }, [location]);
}

// Use in your App component
function App() {
  usePageTracking();

  return (
    // your app content
  );
}
```

## Next.js[](#nextjs)

Next.js supports both client-side and server-side rendering. For client-side tracking, you’ll use the browser library with the `'use client'` directive.

If you want to use the server-side library, see [our Node.js library instructions](/integrations/data-in/connections/servers/node/).

1.  Go to *Data & Integrations > Integrations*. In the **Connections** tab, pick the **JavaScript** integration to get your *Write Key*.
    
2.  Install the package:
    
    ```bash
    npm install @customerio/cdp-analytics-browser
    ```
    
3.  Create an analytics component in `./components/analytics.js` (or `.tsx` for TypeScript):
    
    ```javascript
    'use client';
    
    import { AnalyticsBrowser } from '@customerio/cdp-analytics-browser';
    
    export const cioanalytics = AnalyticsBrowser.load({
      // cdnURL: 'https://cdp-eu.customer.io', // Set if you're in our EU data center
      writeKey: '<YOUR_WRITE_KEY>'
    });
    
    export default function Analytics() { return null; }
    ```
    
4.  Load this component in your `./app/layout.tsx` file so it initializes on every page:
    
    ```tsx
    import Analytics from '../components/analytics'
    
    export default function RootLayout({
      children,
    }: {
      children: React.ReactNode
    }) {
      return (
        <html lang="en">
          <Analytics />
          <body>{children}</body>
        </html>
      )
    }
    ```
    
5.  Use the analytics instance in your pages:
    
    ```jsx
    import { cioanalytics } from '../components/analytics'
    
    export default function Home() {
      return (
        <main>
          <button onClick={() => cioanalytics.track('Button Clicked')}>
            Track Event
          </button>
        </main>
      )
    }
    ```
    

### Track page views in Next.js[](#track-page-views-in-nextjs)

Next.js uses client-side routing. To track page views on route changes, you can use `usePathname` and `useSearchParams`. You might create a component like this and add it to your layout alongside the Analytics component.

```tsx
'use client';

import { usePathname, useSearchParams } from 'next/navigation';
import { useEffect } from 'react';
import { cioanalytics } from './analytics';

export function PageTracker() {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useEffect(() => {
    cioanalytics.page();
  }, [pathname, searchParams]);

  return null;
}
```

## Vue.js[](#vuejs)

In Vue.js, you can expose the analytics instance as a global property so it’s available in all components.

1.  Go to *Data & Integrations > Integrations*. In the **Connections** tab, pick the **JavaScript** integration to get your *Write Key*.
    
2.  Install the package:
    
    ```bash
    npm install @customerio/cdp-analytics-browser
    ```
    
3.  Add the following code to your `main.js` file (or your application’s entry point):
    
    ```javascript
    import { createApp } from 'vue'
    import App from './App.vue'
    import { AnalyticsBrowser } from '@customerio/cdp-analytics-browser'
    
    const app = createApp(App)
    
    app.config.globalProperties.$cioanalytics = AnalyticsBrowser.load({
      // cdnURL: 'https://cdp-eu.customer.io', // Set if you're in our EU data center
      writeKey: '<YOUR_WRITE_KEY>'
    });
    
    app.mount('#app')
    ```
    
4.  Use `$cioanalytics` in your components:
    
    ```vue
    <template>
      <button @click="$cioanalytics.track('Button Clicked')">Track Event</button>
    </template>
    ```
    

### Track page views in Vue.js[](#track-page-views-in-vuejs)

If you use Vue Router for client-side navigation, track page views using navigation guards:

```javascript
import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(),
  routes: [/* your routes */]
})

router.afterEach((to) => {
  // Access the global property from the app instance
  app.config.globalProperties.$cioanalytics.page({
    name: to.name,
    path: to.path
  });
})
```

## Listening for in-app message events[](#listening-for-in-app-message-events)

If you want to send in-app messages and respond to user interactions, add the `integrations` object when initializing the library. You can find the Site ID in \> *Workspace Settings > API and Webhooks Credentials > [Tracking API Keys](https://fly.customer.io/workspaces/last/settings/api_credentials)*.

```javascript
import { AnalyticsBrowser } from '@customerio/cdp-analytics-browser'

const cioanalytics = AnalyticsBrowser.load(
  {
    writeKey: '<YOUR_WRITE_KEY>',
  },
  { 
    integrations: {
      'Customer.io In-App Plugin': {
        siteId: '<YOUR_SITE_ID>',
        events: (e) => {
          switch (e.type) {
            case "in-app:message-opened":
              // do something when a message is opened
              break;
            case "in-app:message-dismissed":
              // do something when a message is dismissed
              break;
            case "in-app:message-action":
              // do something when a message is interacted with
              break;
            case "in-app:message-error":
              // do something when a message errors
              break;
            case "in-app:message-changed":
              // do something when a user moves to the next step
              break;
          }
        }
      }
    }
  }
);
```

## Tracking page views[](#tracking-page-views)

When you use the JavaScript snippet, we automatically send a `page()` call on every page load. If you use client-side routing, as many of the frameworks on this page do, you’ll need to send your own `page()` calls when routes change.

The browser library automatically enriches `page()` calls with:

*   `path`: The URL path
*   `referrer`: The previous page URL
*   `search`: Query string parameters
*   `title`: The page title
*   `url`: The full page URL

You can override any of these values by passing them explicitly.

```javascript
cioanalytics.page('Category', 'Page Name', {
  title: 'Custom Title',
  url: 'https://example.com/custom-path'
});
```

## Set the `cdnURL` if you’re in our EU data center[](#set-the-cdnurl-if-youre-in-our-eu-data-center)

If you’re in our EU data center, set the `cdnURL` parameter to use our EU regional endpoint.

```javascript
import { AnalyticsBrowser } from '@customerio/cdp-analytics-browser'

const cioanalytics = AnalyticsBrowser.load({
  cdnURL: 'https://cdp-eu.customer.io',
  writeKey: '<YOUR_WRITE_KEY>'
});
```