Install Grain

Grain has two packages for your site: Grain Tag, the browser script, and Analytics Web, the TypeScript SDK. This page picks one for your situation, shows the install command, and shows how to make sure that events arrive. Every install needs the tenant alias from the dashboard.

Your situation

Your situation	Install	Read
A website without a build step	Grain Tag, as a script tag	Script tag
Google Tag Manager	Grain Tag, as a custom HTML tag	Google Tag Manager
Shopify	Grain Tag, in the theme	Shopify
WordPress	Grain Tag, with a plugin or a theme edit	WordPress
React	Grain Tag, npm `@grainql/tag`	React
React with remote configuration or hooks	Analytics Web, npm `@grainql/analytics-web`	React hooks
Next.js	Grain Tag in the browser, Analytics Web on the server	Next.js
Vue, Svelte, Angular, or another framework	Grain Tag, as a script tag or npm `@grainql/tag`	Plain JavaScript, Vue, and Svelte
Node.js or a server	Analytics Web, npm `@grainql/analytics-web`	Node.js and servers
A dashboard or an export of data	Nothing. Call the Query API with an API key.	Export and query data
An AI assistant	Nothing. Connect the assistant to the MCP server.	MCP server

Grain Tag or Analytics Web

Capability	Grain Tag, script tag	Grain Tag, npm `@grainql/tag`	Analytics Web, npm `@grainql/analytics-web`
Automatic page views, sessions, heartbeat	Yes	Yes	Yes
Heatmaps and DOM snapshots	Yes	Yes	Heatmaps by default. No snapshots.
Custom events and `identify`	Yes	Yes	Yes
Remote configuration	No	No	Yes
React hooks	No	No	Yes, from `@grainql/analytics-web/react`
Runs on a server	No	No	Yes
Authentication strategies	None. Tenant alias only.	None. Tenant alias only.	`NONE`, `SERVER_SIDE`, `JWT`
Build step	Not required	Required	Required

The script tag and the npm package are the same Grain Tag code. The script tag is an IIFE build with the tenant alias injected. Read Authentication for the strategies.

Install Grain Tag with a script tag

Add one tag to the HTML of every page:

<script src="https://tag.grainql.com/v4/your-tenant-id.js"></script>

Grain Tag then collects page views, clicks, scroll depth, heatmaps, rage clicks, dead clicks, sessions, and DOM snapshots. GrainTag.track sends a custom event, and GrainTag.identify sets the user ID after a login:

<script>
  GrainTag.track('signup_clicked', { location: 'hero' });
  GrainTag.identify('user_123');
</script>

Install Grain Tag with npm

For an app with a build step, install @grainql/tag:

npm install @grainql/tag

yarn add @grainql/tag

pnpm add @grainql/tag

Call init one time. track and identify are safe to call before init completes. The package queues the calls and replays them:

import { init, track, identify } from '@grainql/tag';

init({ tenantId: 'your-tenant-id' });

track('button_clicked', { button_id: 'signup' });
identify('user_123');

The package ships TypeScript types. Read TypeScript.

Install Analytics Web

For a server, or for React hooks and remote configuration, install @grainql/analytics-web:

npm install @grainql/analytics-web

Read Node.js and servers for the server configuration and React hooks for the provider.

The tenant alias

Every install uses the tenant alias, not the tenant UUID. The alias is the human-readable identifier that the dashboard shows at https://grainql.com/dashboard. Replace your-tenant-id with it in every example on this site. Grain Tag is cookieless by default. Its consentMode has three values:

Value	Behavior
`auto`	The default. Cookieless analytics with daily rotating IDs. No consent is required.
`opt-in`	No tracking until the user grants consent.
`opt-out`	Tracking by default. The user can revoke consent.

consent.grant() moves the visitor to a persistent ID in localStorage, not in a cookie. consent.revoke() clears the stored ID and returns to daily rotating IDs. Read Privacy and consent.

Platform support

Environment	Supported
Browsers	Chrome, Firefox, Safari, Edge
JavaScript	ES6 and later, and legacy ES5
Bundlers	Vite, Webpack, esbuild
Frameworks	React, Next.js (App Router and Pages Router), Vue, Svelte, Angular, plain JavaScript
Server	Node.js 14 and later
Serverless	AWS Lambda, Vercel, Netlify

Make sure that Grain receives events

For a script tag install:

Open the browser console on a page that loads the script. Grain Tag writes its initialization logs there.
Run GrainTag.track('installation_test') in the console.
Open the dashboard at https://grainql.com/dashboard. The event shows within 30 seconds.

For an npm install, set debug: true and send one event:

import { init, track } from '@grainql/tag';

init({
  tenantId: 'your-tenant-id',
  debug: true
});

track('installation_test');

The console then shows the batching and sending activity. If no event arrives, read Troubleshooting.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

Your situation

Grain Tag or Analytics Web

Install Grain Tag with a script tag

Install Grain Tag with npm

Install Analytics Web

The tenant alias

Platform support

Make sure that Grain receives events

​Your situation

​Grain Tag or Analytics Web

​Install Grain Tag with a script tag

​Install Grain Tag with npm

​Install Analytics Web

​The tenant alias

​Consent

​Platform support

​Make sure that Grain receives events

Your situation

Grain Tag or Analytics Web

Install Grain Tag with a script tag

Install Grain Tag with npm

Install Analytics Web

The tenant alias

Consent

Platform support

Make sure that Grain receives events