🍪 Fake Cloudflare Zaraz Consent

A development tool that provides a fake Cloudflare Zaraz consent management system for local development. Perfect for testing consent-dependent features without requiring a live Zaraz instance.

🌐 Try the online demo →

📚 API Reference: This package implements the official Cloudflare Zaraz Consent Management API. All methods and behaviors match the production Zaraz consent system.

✨ Features

• 🎯 Drop-in replacement for Cloudflare Zaraz consent API
• 🖼️ Built-in consent modal with customizable styling
• 📝 TypeScript support with comprehensive type definitions
• 🛠️ Development utilities - Shared constants, logging helpers, and validation

🚀 Quick Start

Installation

npm install --save-dev @imviidx/fake-cloudflare-zaraz-consent

Basic Usage

import { initFakeZaraz } from '@imviidx/fake-cloudflare-zaraz-consent';

// Initialize with default configuration
const zaraz = initFakeZaraz();

// Access the consent API (same as real Zaraz)
window.zaraz.consent.get('analytics'); // false
window.zaraz.consent.set({ analytics: true });
window.zaraz.consent.modal = true; // Show consent modal

🚀 Enhanced Setup with zaraz-ts

This package works seamlessly with zaraz-ts. You can use zaraz-ts for type-safe access to the consent API:

// Import fake Zaraz setup functions
import {
  initFakeZaraz,
  createLogger,
} from '@imviidx/fake-cloudflare-zaraz-consent';

// Import zaraz-ts for type-safe API access
import { zaraz } from 'zaraz-ts';

// Use zaraz-ts for type-safe access
const analyticsConsent = zaraz.consent.get('analytics');
zaraz.consent.set({ analytics: true, marketing: false });

// All standard Zaraz consent API is available
const allConsent = zaraz.consent.getAll();
zaraz.consent.setAll(true); // Accept all

// Use shared utilities
const logger = createLogger('My App', true);
logger.log('App initialized');

🎮 Live Demo

Experience the package in action with our interactive demo, or run it locally:

# Run the demo (uses standalone Vite setup)
cd demo
npm install
npm run dev

# The demo will be available at http://localhost:3000

📖 API Reference

💡 Complete API Documentation: See the official Cloudflare Zaraz Consent Management API docs for detailed information about all methods and properties.

Core Functions

initFakeZaraz(config?)

Initializes the fake Zaraz instance with optional configuration.

import {
  initFakeZaraz,
  ZarazConfig,
} from '@imviidx/fake-cloudflare-zaraz-consent';

const config: Partial<ZarazConfig> = {
  purposes: [
    {
      id: 'analytics',
      name: 'Analytics',
      description: 'Track website usage',
      order: 1,
      required: false,
    },
  ],
  defaultConsent: { analytics: false },
  enableLogging: true,
  enableModal: true,
  autoShow: false,
};

const zaraz = initFakeZaraz(config);

Consent API

Once initialized, access the API via window.zaraz.consent or zaraz-ts:

// Check if API is ready
window.zaraz.consent.APIReady; // boolean

// Get consent for specific purpose
window.zaraz.consent.get('analytics'); // boolean | undefined

// Set consent for multiple purposes
window.zaraz.consent.set({
  analytics: true,
  marketing: false,
});

// Get all consent preferences
window.zaraz.consent.getAll(); // { [purposeId]: boolean }

// Set all purposes to same value
window.zaraz.consent.setAll(true); // Accept all
window.zaraz.consent.setAll(false); // Reject all

// Modal control
window.zaraz.consent.modal = true; // Show modal
window.zaraz.consent.modal = false; // Hide modal

// Available purposes
window.zaraz.consent.purposes; // { [id]: Purpose }

// Send queued events (for testing)
window.zaraz.consent.sendQueuedEvents();

🔧 Configuration

Purpose Configuration

interface Purpose {
  id: string; // Unique identifier
  name: string; // Display name
  description: string; // User-friendly description
  order: number; // Display order
  required?: boolean; // Cannot be disabled (custom property, not in Cloudflare API)
}

const customPurposes: Purpose[] = [
  {
    id: 'functional',
    name: 'Essential Cookies',
    description: 'Required for basic site functionality',
    order: 1,
    required: true,
  },
  {
    id: 'analytics',
    name: 'Analytics',
    description: 'Help us improve our website',
    order: 2,
  },
];

Modal Customization

const modalConfig = {
  title: 'Cookie Preferences',
  description: 'We use cookies to enhance your experience...',
  acceptAllText: 'Accept All',
  rejectAllText: 'Reject All',
  saveText: 'Save Preferences',
  closeText: 'Close',
  theme: 'light' | 'dark',
  position: 'center' | 'bottom',
};

🌍 Environment-Specific Usage

Development Only

// Only load in development
if (process.env.NODE_ENV === 'development') {
  import('@imviidx/fake-cloudflare-zaraz-consent').then(({ initFakeZaraz }) => {
    initFakeZaraz({
      ...
    });
  });
}

Production Detection

// Check if running fake vs real Zaraz
import { isFakeZaraz } from '@imviidx/fake-cloudflare-zaraz-consent';

isFakeZaraz(window.zaraz);
// true or false

Browser Console Debugging

You can access the consent API directly in the browser console for debugging:

// Available in browser console once initialized
window.zaraz.consent.getAll(); // Get all consent status
window.zaraz.consent.get('analytics'); // Get specific consent
window.zaraz.consent.set({ analytics: true }); // Set consent
window.zaraz.consent.setAll(true); // Accept all
window.zaraz.consent.setAll(false); // Reject all
window.zaraz.consent.modal = true; // Show modal

// Check available purposes
console.log(window.zaraz.consent.purposes);

📦 What's Included

• Core API: Full Zaraz consent API implementation
• Modal UI: Accessible consent dialog with customization
• Storage: Persistent consent via cookies + localStorage backup
• Events: Standard Zaraz events (zarazConsentAPIReady, zarazConsentChoicesUpdated)
• TypeScript: Complete type definitions
• Utilities: Helper functions for common operations
• 🚀 Enhanced Integration: Seamless integration with zaraz-ts for type-safe API access
• 🛠️ Development Tools: Direct console API access for debugging
• 📦 Standard API: Complete implementation of Cloudflare Zaraz consent API

🤝 Contributing

Contributions welcome! Please read the integration guide for detailed examples.

� Publishing

This package uses np for streamlined publishing:

# Interactive release (will prompt for version)
npm run release

# Dry run (test without publishing)
npm run release:dry

�📄 License

Apache 2.0 - see LICENSE file for details.

Note: This is a development tool. In production, use real Cloudflare Zaraz for consent management.