Project setup

1. Copy the source/assets/ directory into your project root or a subdirectory such as frontend/.
2. Copy source/assets/package.json and install dependencies with npm install from that directory.
3. Ensure your tsconfig.json has "jsx": "react-jsx" and includes "assets/js/**/*" in include.
4. Configure path aliases if needed; the source uses relative imports throughout, so no aliases are required by default.
5. Set the following environment/build variables before bundling:
   • BUILD_EXTRA - set to true to enable funnel and exploration features (optional, defaults to falsy)
   • PLAUSIBLE_SITE_DOMAIN - the site domain for API path construction
6. The entry point for the dashboard is assets/js/dashboard.tsx; wire this into your bundler (esbuild, Vite, or Webpack) as the main chunk.
7. Global CSS entry point is assets/css/app.css; import it in your bundler config or at the top of your entry JS file.
8. Static browser icon assets referenced by browserIconFor() must be served from /images/icon/browser/.

Public API

Dashboard

// assets/js/dashboard/index.tsx
export default function Dashboard(): JSX.Element

The root dashboard component. Renders the full analytics page including the visitor graph, all stat panels, and the top navigation bar. Wrap in your router and context providers before mounting. Requires GraphIntervalProvider, ImportsIncludedProvider, and dashboard state context to be available up the tree (these are composed internally).

DashboardStats

// assets/js/dashboard/index.tsx
function DashboardStats(props: {
  importedDataInView?: boolean
  updateImportedDataInView?: (v: boolean) => void
}): JSX.Element

Renders the grid of stat panels: VisitorGraph, Sources, Pages, Locations, Devices, and Behaviours. Pass importedDataInView and its setter for historical mode; pass undefined for both props in real-time mode. Used internally by Dashboard but can be composed independently.

browserIconFor

// assets/js/dashboard/stats/devices/index.js
export function browserIconFor(browser: string): JSX.Element

Returns an <img> element for a named browser. Handles Chrome, Safari, Firefox, Edge, and many others with fallback to a generic icon. Use this when rendering browser breakdown rows in a custom devices panel or report table.

Working examples

Scenario - Mounting the full dashboard

Drop the Dashboard component into an existing React app. All internal state and context is self-contained.

// src/App.tsx
import React from 'react'
import Dashboard from '../source/assets/js/dashboard/index'
import { SiteContextProvider } from '../source/assets/js/dashboard/site-context'
import { DashboardStateContextProvider } from '../source/assets/js/dashboard/dashboard-state-context'

const site = {
  domain: 'example.com',
  offset: '0',
  hasGoals: true,
  funnelsAvailable: false,
  propsAvailable: true,
  flags: {},
  validIntervalsByPeriod: {}
}

export default function App() {
  return (
    <SiteContextProvider site={site}>
      <DashboardStateContextProvider>
        <Dashboard />
      </DashboardStateContextProvider>
    </SiteContextProvider>
  )
}

Scenario - Rendering only the stat panels

Use DashboardStats directly when you have your own nav bar and want just the data panels.

// src/StatsOnly.tsx
import React, { useState } from 'react'
import { DashboardStats } from '../source/assets/js/dashboard/index'
import { GraphIntervalProvider } from '../source/assets/js/dashboard/stats/graph/graph-interval-context'
import { ImportsIncludedProvider } from '../source/assets/js/dashboard/stats/graph/imports-included-context'

export default function StatsOnly() {
  const [importedDataInView, setImportedDataInView] = useState(false)
  return (
    <GraphIntervalProvider>
      <ImportsIncludedProvider>
        <DashboardStats
          importedDataInView={importedDataInView}
          updateImportedDataInView={setImportedDataInView}
        />
      </ImportsIncludedProvider>
    </GraphIntervalProvider>
  )
}

Scenario - Displaying a browser icon in a custom table

Use browserIconFor when building a custom devices breakdown table outside the default panel.

// src/BrowserTable.tsx
import React from 'react'
import { browserIconFor } from '../source/assets/js/dashboard/stats/devices/index'

const browsers = ['Chrome', 'Firefox', 'Safari', 'Microsoft Edge']

export default function BrowserTable() {
  return (
    <ul>
      {browsers.map((b) => (
        <li key={b} className="flex items-center">
          {browserIconFor(b)}
          <span>{b}</span>
        </li>
      ))}
    </ul>
  )
}

File walkthrough

• assets/js/dashboard/index.tsx - Root Dashboard component; composes all stat panels and context providers.
• assets/js/dashboard/stats/ - One subdirectory per stat category (graph, sources, pages, locations, devices, behaviours); each exports its panel component.
• assets/js/dashboard/stats/behaviours/index.js - Behaviours panel: goals, conversions, funnels, custom props; conditionally loads extra/funnel if BUILD_EXTRA is set.
• assets/js/dashboard/stats/devices/index.js - Devices panel with browser/OS/screen tabs; exports browserIconFor for reuse.
• assets/js/dashboard/stats/locations/index.js - Locations panel with Countries, Regions, Cities tabs and a choropleth map.
• assets/js/dashboard/stats/pages/index.js - Pages panel with Top Pages, Entry Pages, Exit Pages tabs.
• assets/js/dashboard/nav-menu/ - TopBar component: date picker, filters bar, site switcher, current visitors badge.
• assets/js/dashboard/util/ - Pure utility modules: filters.ts (filter construction/parsing), url.ts (API path helpers), storage.ts (localStorage wrappers).
• assets/js/dashboard/components/ - Reusable primitives: Tabs, Pill, FeatureSetupNotice, dropdown components.
• assets/js/dashboard/dashboard-state-context.tsx - React context + hook useDashboardStateContext exposing global query state (period, filters, comparisons).
• assets/js/dashboard/api.ts - Typed fetch wrapper for Plausible's stats API endpoints.
• assets/css/app.css - Tailwind base + component layer; import as the CSS entry point.
• tracker/ - Standalone tracker script (separate from dashboard; built independently).
• lib/ - Elixir/Phoenix backend; not consumed by the JS frontend directly.
• mix.exs - Elixir project definition; irrelevant for pure frontend integration.

Common pitfalls and fixes

• BUILD_EXTRA is undefined at runtime - The behaviours panel uses if (BUILD_EXTRA) guards; define this global in your bundler config (e.g., esbuild define: { BUILD_EXTRA: 'false' }) or the build will throw a ReferenceError.
• Browser icons return 404 - browserIconFor constructs paths like /images/icon/browser/chrome.svg; copy the icon assets from priv/static/images/icon/browser/ to your static server root.
• Missing context provider crash - useDashboardStateContext and useSiteContext throw if rendered outside their providers; always wrap the dashboard tree with both SiteContextProvider and DashboardStateContextProvider.
• API calls return 401 or 404 - The api.ts module fetches relative URLs (/api/stats/...); your dev server must proxy those paths to a running Plausible backend or mock server.
• Tailwind styles missing - The dashboard relies on Tailwind utility classes; configure content in tailwind.config.js to include source/assets/js/**/*.{js,ts,tsx} or styles will be purged.
• BUILD_EXTRA funnel modules missing - If BUILD_EXTRA is true, extra/funnel and extra/exploration must exist; these are closed-source Plausible EE modules not included in the open-source repo. Set BUILD_EXTRA to false unless you have the EE source.

Vibe-coding prompt template

I have purchased the Plausible Analytics frontend block. The source is in the
`source/` directory of my project, and there is a USAGE.md with full
integration details.

Please help me integrate the Plausible Analytics dashboard into my existing
React + TypeScript project step by step:

1. Read USAGE.md and the file excerpts for:
   - source/assets/js/dashboard/index.tsx
   - source/assets/js/dashboard/stats/devices/index.js
   - source/assets/js/dashboard/stats/behaviours/index.js
   - source/assets/js/dashboard/stats/pages/index.js
   - source/assets/js/dashboard/stats/locations/index.js

2. Install all required npm dependencies listed in USAGE.md.

3. Configure my bundler to define `BUILD_EXTRA=false` and to proxy
   `/api/stats/` requests to my Plausible backend at `http://localhost:8000`.

4. Mount the `Dashboard` component from `source/assets/js/dashboard/index.tsx`
   in my app, wrapping it with the required context providers.

5. Serve static browser icon assets from the correct path.

6. Show me any tsconfig or Tailwind config changes needed.

Use only the real exports documented in USAGE.md. Do not invent new APIs.

License and credit

Plausible Analytics is released under the GNU Affero General Public License v3.0 (AGPL-3.0). The core analytics library is open source; certain enterprise features (extra/funnel, extra/exploration) are under a separate commercial license. See source/LICENSE.md for the full text.

Upstream repository: https://github.com/plausible/analytics

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.