Skip to main content
Looking for a quick start guide? Check out our platform-specific quick starts for step-by-step setup instructions.

​
Choose Your Installation Method

Pick the method that fits your setup:

npm / yarn / pnpm

For apps with a build step

CDN

For static sites or quick prototyping

​
Package Manager

Install via npm, yarn, or pnpm: 
npm install @grainql/analytics-web
The package includes:
  • Core analytics SDK
  • Remote configuration
  • React hooks (optional)
  • Full TypeScript support

​
Import and Use

// Vanilla JS or any framework
import { createGrainAnalytics } from '@grainql/analytics-web';

// React hooks
import { GrainProvider, useTrack, useConfig } from '@grainql/analytics-web/react';
Next steps: Check out the React Quick Start or Vanilla JS Quick Start for complete examples.

​
CDN (Browser)

For sites without a build step, use the CDN version: 
<script src="https://unpkg.com/@grainql/analytics-web/dist/index.global.js"></script>
<script>
  const grain = Grain.createGrainAnalytics({
    tenantId: 'your-tenant-id'
  });
  
  grain.track('page_viewed', { page: window.location.pathname });
</script>

​
Version Pinning

For production, pin to a specific version: 
<script src="https://unpkg.com/@grainql/[email protected]/dist/index.global.js"></script>
Check the npm package for available versions.

​
Alternative CDNs

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@grainql/analytics-web/dist/index.global.js"></script>

<!-- unpkg -->
<script src="https://unpkg.com/@grainql/analytics-web/dist/index.global.js"></script>
Next steps: See the CDN Quick Start for complete examples.

​
Platform Support

Grain Analytics works across multiple environments:

​
Browser

  • ✅ Chrome, Firefox, Safari, Edge
  • ✅ Modern ES6+ and legacy ES5
  • ✅ Module bundlers (Vite, Webpack, esbuild)

​
Frameworks

  • ✅ React (hooks included)
  • ✅ Next.js (App Router & Pages Router)
  • ✅ Vue, Svelte, Angular
  • ✅ Vanilla JavaScript

​
Server

  • ✅ Node.js 14+
  • ✅ Serverless (AWS Lambda, Vercel, Netlify)
  • ✅ React Native

​
Build Formats

The package includes multiple formats:
  • ESM (dist/index.mjs) — Modern bundlers
  • CommonJS (dist/index.js) — Node.js
  • IIFE (dist/index.global.js) — Browsers via CDN
  • TypeScript (dist/index.d.ts) — Type definitions
Your bundler automatically picks the right format.

​
TypeScript Support

Full TypeScript support out of the box—no additional packages needed: 
import { createGrainAnalytics, GrainConfig, GrainEvent } from '@grainql/analytics-web';

const config: GrainConfig = {
  tenantId: 'your-tenant-id',
  authStrategy: 'NONE',
  batchSize: 50
};

const grain = createGrainAnalytics(config);

​
Bundle Size

Grain is designed to be lightweight:
  • Core SDK: ~6 KB (gzipped)
  • With React Hooks: ~8 KB (gzipped)
  • Zero dependencies: No bloat
The SDK is tree-shakeable—you only bundle what you use.

​
Verify Installation

Test that everything works: 
import { createGrainAnalytics } from '@grainql/analytics-web';

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  debug: true // Enable console logging
});

grain.track('installation_test', {
  timestamp: new Date().toISOString()
});

console.log('Grain Analytics initialized!');
Check your browser console to see batching and sending activity.

​
Privacy & GDPR

Grain includes built-in privacy features:

​
Basic Setup

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  consentMode: 'opt-in',        // Require consent
  waitForConsent: true,          // Queue events until consent
  enableCookies: true,           // Use cookies after consent
  anonymizeIP: true              // Anonymize IP addresses
});

// Grant consent
grain.grantConsent(['necessary', 'analytics']);

// Revoke consent
grain.revokeConsent();

// Check consent
const hasConsent = grain.hasConsent('analytics');

import { GrainProvider, ConsentBanner } from '@grainql/analytics-web/react';

function App() {
  return (
    <GrainProvider config={{ 
      tenantId: 'your-tenant-id',
      consentMode: 'opt-in'
    }}>
      <ConsentBanner 
        position="bottom"
        theme="glass"
        privacyPolicyUrl="/privacy"
      />
      {/* Your app */}
    </GrainProvider>
  );
}
GDPR Compliance: In opt-in mode without consent, only ephemeral session IDs are used. No cookies or persistent tracking until consent is granted.

​
What’s Next?

Quick Start Guides

Platform-specific setup instructions

Authentication

Set up Auth0 or custom JWT authentication

Core Concepts

Learn about event tracking and remote config

React Hooks

Use Grain with React