> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puntego.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Framework guides
> Mount Puntego in Next.js, React, and single-page apps, with a no-code Google Tag Manager path.
Puntego installs with a single script tag, but most apps want a tighter
integration: a layout that mounts the guide once, declared targets that raise
action success, and a no-code path for non-engineers. This page covers the
common stacks.
If you just want the raw script tag, see the [install guide](/install).
The script-tag and Google Tag Manager paths work today. The `@puntego/react`
and `@puntego/embed` npm packages are rolling out — if `npm install` returns a
404, the package has not published yet, so use the [install script](/install)
in the meantime.
Next.js (App Router)
Install the React wrapper and its peers:
```bash npm theme={null}
npm install @puntego/react @puntego/embed react
```
```bash pnpm theme={null}
pnpm add @puntego/react @puntego/embed react
```
```bash yarn theme={null}
yarn add @puntego/react @puntego/embed react
```
```bash bun theme={null}
bun add @puntego/react @puntego/embed react
```
Mount the provider once in your root layout. Because `` only
loads the guide in a client effect, it is safe to render on the server. Pass both
`appId` and `apiUrl` — `apiUrl` is required, since without a reachable worker URL
the runtime cannot boot.
```tsx theme={null}
// app/layout.tsx
import { PuntegoProvider } from '@puntego/react';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
If you serve a strict Content Security Policy with a per-request nonce, read
it from `next/headers` and pass it to the provider. It is propagated to both
`nonce` and `data-nonce` on the boot script. Keep `apiUrl` — the nonce does
not replace it.
```tsx theme={null}
// app/layout.tsx
import { headers } from 'next/headers';
import { PuntegoProvider } from '@puntego/react';
export default async function RootLayout({ children }: { children: React.ReactNode }) {
const nonce = (await headers()).get('x-nonce') ?? undefined;
return (
{children}
);
}
```
Allow the boot origin in `script-src` and the worker origin in
`connect-src`. See [the CSP guide](/csp) for the full policy.
### Declare targets
Declared targets are the highest-priority grounding tier — the guide resolves
them before falling back to DOM heuristics, which raises action success. Declare
the elements that matter on each page; the hook registers on mount and
unregisters on unmount.
```tsx theme={null}
'use client';
import { useRef } from 'react';
import { usePuntegoTarget } from '@puntego/react';
export function CheckoutButton() {
const ref = useRef(null);
usePuntegoTarget(ref, { id: 'checkout', description: 'Primary checkout CTA' });
return ;
}
```
React
The same `@puntego/react` package works in any React 18+ app (Vite, CRA,
Remix). Wrap your app once in `` (with `appId` and `apiUrl`),
then use `usePuntegoTarget` and `usePuntegoAction` to declare targets and
actions per component. Use `usePuntego()` for imperative calls such as `point`
or `sendMessage`. See the [SDK reference](/sdk-reference) for the full surface.
Single-page apps and client-side routing
The runtime hooks `history.pushState`, `popstate`, and `hashchange`, so
client-side route changes are detected automatically — there is nothing to wire
up for React Router, Vue Router, or SvelteKit navigation. The guide re-reads the
page on each route change, and an in-progress tour resumes across navigations.
For accuracy: the runtime compares the pathname, so query-only changes and
`replaceState` updates are deliberately not treated as navigations (many apps
sync scroll position or filters into the query string, and re-reading on every
such change would thrash). If you mount or unmount declared targets across those
transitions, call the registration hooks — use the framework hooks, or call
`window.Puntego.registerTarget` / `unregisterTarget` from your own lifecycle —
so the registry always matches what is on screen.
Google Tag Manager (no code)
If you cannot edit your site's HTML but you have a GTM container, use the
community template.
In GTM, open **Templates → Tag Templates → New**, then import the template.
Get it by [downloading the Puntego Embed template](https://puntego.com/gtm/template.tpl),
or find **Puntego Embed** in the GTM Community Template Gallery.
Add a **Puntego Embed** tag and fill in your **App ID** and **Worker API
origin** (copy both from **Dashboard → Install**).
Trigger on **All Pages** (Initialization), then Preview and Publish.
The tag injects `boot.js` once and publishes a `window.__PUNTEGO_CONFIG__`
object that the boot script reads when no `data-app-id` attribute is present.
The GTM and hand-pasted paths share the same runtime.
## Programmatic loader
For custom integrations, the loader injects the boot script imperatively and is
SSR-safe (a no-op on the server):
```ts theme={null}
import { loadPuntego, whenPuntegoReady } from '@puntego/embed/loader';
loadPuntego({ appId: 'gp_your_app_id', apiUrl: 'https://worker.puntego.com' });
const sdk = await whenPuntegoReady();
sdk?.registerTarget('#checkout', { id: 'checkout', description: 'Checkout' });
```
## Next steps
The raw script tag and every launch attribute.
Tune launcher mode, routes, voice, and wake behavior.
Imperative methods, hooks, and runtime events.
Build product-owned helpers and declared targets.
The full Content Security Policy for strict sites.
Allow the origins where the guide may mount.