react-audit-tracker

🎯 Try Live Demos

Experience react-audit-tracker instantly in your browser - no installation required!

⚡ Quick Start

npm install react-audit-tracker

npx audit-tracker-setup

import { AuditProvider } from 'react-audit-tracker';

function App() {
  return (
    <AuditProvider mode="local">
      {/* Your app components */}
    </AuditProvider>
  );
}

import { useAudit } from 'react-audit-tracker';

function MyComponent() {
  const { track } = useAudit();

  const handleAction = async () => {
    await track({
      action: 'BUTTON_CLICKED',
      entity: 'Button',
      entityId: 'submit-btn',
      description: 'User clicked submit button'
    });
  };

  return <button onClick={handleAction}>Submit</button>;
}

✨ Features

🛠️ Setup Guide

Using the CLI Wizard

npx audit-tracker-setup

The wizard will:

• Ask for your preferred storage mode (Local/Firebase/API)
• Collect necessary configuration details
• Generate ready-to-use setup files
• Provide next steps and documentation links

Manual Setup

If you prefer to configure manually, follow these steps:

npm install react-audit-tracker

import { AuditProvider } from 'react-audit-tracker';

function App() {
  return (
    <AuditProvider mode="local">
      <YourApp />
    </AuditProvider>
  );
}

import { AuditProvider } from 'react-audit-tracker';

const firebaseConfig = {
  config: {
    apiKey: "your-api-key",
    authDomain: "your-project.firebaseapp.com",
    projectId: "your-project-id",
    storageBucket: "your-project.appspot.com",
    messagingSenderId: "123456789",
    appId: "your-app-id"
  },
  collectionName: 'audit_events'
};

function App() {
  return (
    <AuditProvider mode="firebase" firebaseConfig={firebaseConfig}>
      <YourApp />
    </AuditProvider>
  );
}

import { AuditProvider } from 'react-audit-tracker';

const apiConfig = {
  baseUrl: 'https://api.example.com'
};

function App() {
  return (
    <AuditProvider mode="api" apiConfig={apiConfig}>
      <YourApp />
    </AuditProvider>
  );
}

💾 Storage Modes

Local Storage

Browser-based storage. Perfect for development and small applications.

<AuditProvider mode="local">

Pros: No setup, instant, works offline
Cons: Limited to ~5MB, browser-specific, lost on clear cache

Firebase Firestore

Cloud-based NoSQL database. Ideal for production applications.

<AuditProvider mode="firebase" firebaseConfig={config}>

Pros: Scalable, real-time, cross-device, persistent
Cons: Requires Firebase account, costs at scale

REST API

Your own backend API. Full control over storage and logic.

<AuditProvider mode="api" apiConfig={{baseUrl: '...'}}>

Pros: Full control, custom logic, any database
Cons: Requires backend development

📚 Examples

Basic Event Tracking

import { useAudit } from 'react-audit-tracker';

function UserProfile() {
  const { track } = useAudit();

  const handleProfileUpdate = async (data) => {
    // Update profile logic...
    
    await track({
      action: 'PROFILE_UPDATED',
      entity: 'User',
      entityId: userId,
      userId: currentUser.id,
      userName: currentUser.name,
      description: 'User updated their profile',
      metadata: {
        fields: ['name', 'email'],
        previousValues: { name: 'John', email: 'old@email.com' }
      }
    });
  };
}

Tracking with Metadata

await track({
  action: 'DOCUMENT_CREATED',
  entity: 'Document',
  entityId: doc.id,
  description: 'Created new document',
  metadata: {
    fileName: doc.name,
    fileSize: doc.size,
    fileType: doc.type,
    category: doc.category,
    changes: [
      { field: 'status', oldValue: null, newValue: 'draft' }
    ]
  }
});

Display Audit Logs

import { AuditTable } from 'react-audit-tracker';

function AuditLogsPage() {
  return (
    <div>
      <h1>Audit Logs</h1>
      <AuditTable 
        pageSize={20}
        showFilters={true}
      />
    </div>
  );
}

Custom Columns

import { AuditTable } from 'react-audit-tracker';

const customColumns = [
  {
    key: 'timestamp',
    label: 'Date',
    width: '180px',
    sortable: true,
    render: (value) => new Date(value).toLocaleString()
  },
  {
    key: 'action',
    label: 'Action',
    render: (value) => (
      <span className={`badge ${getActionColor(value)}`}>
        {value}
      </span>
    )
  }
];

function CustomAuditLogs() {
  return <AuditTable columns={customColumns} />;
}

📖 API Reference

AuditProvider Props

interface AuditProviderProps {
  mode: 'local' | 'firebase' | 'api';
  firebaseConfig?: FirebaseConfig;  // Required if mode='firebase'
  apiConfig?: ApiConfig;             // Required if mode='api'
  children: ReactNode;
}

useAudit Hook

const { track, loading, error } = useAudit();

// track function
await track({
  action: string;           // Required: Action type (e.g., 'USER_LOGIN')
  entity: string;           // Required: Entity type (e.g., 'User')
  entityId: string;         // Required: Entity identifier
  userId?: string;          // Optional: User who performed action
  userName?: string;        // Optional: User's display name
  description?: string;     // Optional: Human-readable description
  metadata?: any;           // Optional: Additional data
});

AuditTable Props

interface AuditTableProps {
  columns?: ColumnConfig[];  // Custom column definitions
  pageSize?: number;         // Items per page (default: 10)
  showFilters?: boolean;     // Enable filtering (default: false)
  className?: string;        // Custom CSS class
}

🔧 Troubleshooting

Error: useAudit must be used within an AuditProvider

<AuditProvider mode="local">
  <YourComponent />  {/* This component can use useAudit */}
</AuditProvider>

Firebase: Permission Denied

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /audit_events/{document} {
      allow read, write: if request.auth != null;  // Authenticated users
      // OR for development:
      allow read, write: if true;  // Warning: Open access
    }
  }
}

TypeScript Errors

💬 Support & Resources

📖 Documentation

📧 Need Help?

For bug reports, feature requests, or any questions, contact us: