@cluster-data-experience/qlik-modules

A comprehensive and type-safe React library for integrating Qlik Sense into your applications with powerful hooks, providers, and utilities.

✨ Features

• 🚀 Easy Integration - Simple setup with Qlik Sense applications
• ⚛️ React Hooks - Modern React patterns with custom hooks for all Qlik objects
• 🎯 Type Safety - Full TypeScript support with comprehensive type definitions
• 🔄 Real-time Updates - Reactive data updates from Qlik Engine
• 📊 Rich Visualizations - Support for Charts, KPIs, Tables, Lists, and more
• 🛡️ Error Handling - Robust error handling and loading states
• 🎨 Customizable - Flexible configuration and theming options

🎯 What it does

qlik-modules provides a set of React hooks and utilities for integrating Qlik Sense into your applications. It simplifies working with Qlik's Enigma.js and handles common tasks such as:

• 🔐 Multiple authentication methods (OAuth2 PKCE, Web Integration, On-Premise)
• Connection Management - Seamless connection to Qlik Sense Cloud and Enterprise servers
• State Management - Centralized state for Qlik sessions and app data
• Object Lifecycle - Automatic creation and cleanup of Qlik objects
• Data Visualization - Ready-to-use hooks for charts, KPIs, tables, and lists
• Selection Handling - Complete selection management with history support
• Variable Management - Easy variable creation and manipulation
• Performance Optimization - Built-in performance strategies
• Modular architecture following SOLID principles

✨ Features

🔐 Enterprise-Grade Authentication

• OAuth2 PKCE Flow: RFC 7636 compliant with secure token management
• Web Integration: Session-based authentication with CSRF protection
• On-Premise Support: Cookie-based authentication for Qlik Sense Enterprise
• Type-Safe: Full TypeScript support across all authentication methods

🎯 Developer Experience

• React Hooks: Easy-to-use hooks for all Qlik functionality
• Auto-Reconnection: Automatic session management and recovery
• Debug Mode: Comprehensive logging for troubleshooting
• Custom Callbacks: Flexible authentication flow customization
• Zero Config: Sensible defaults for quick setup

📊 Visualization Support

• KPIs and metrics
• Charts and graphs
• Filter objects
• Pivot tables
• Custom visualizations

📦 Installation

npm install @cluster-data-experience/qlik-modules

Peer Dependencies

This library requires the following peer dependencies:

npm install react enigma.js

🚀 Quick Start

1. Basic Setup

import React from "react";
import {
  QlikProvider,
  useQlikApp,
  useGenericKPI,
} from "@cluster-data-experience/qlik-modules";

// Connection configuration
const config = {
  isSecure: true,
  host: "your-qlik-server.com",
  port: 443,
  appId: "YOUR-APP-ID",
  prefix: "/prefix/",
  webIntegrationId: "YOUR-WEB-INTEGRATION-ID", // For Qlik Sense Cloud
};

// Root component with Qlik Provider
const App = () => {
  return (
    <QlikProvider config={config}>
      <Dashboard />
    </QlikProvider>
  );
};

2. Using Hooks

// Component using Qlik hooks
const Dashboard = () => {
  const { app } = useQlikApp();

  // Your Qlik-enabled component logic

  return <div>{/* Your Qlik-enabled components */}</div>;
};

Authentication

qlik-modules supports multiple authentication methods for both Qlik Sense Cloud and on-premise deployments:

Qlik Sense Cloud

OAuth2 with Client ID (Recommended)

const config = {
  host: "your-tenant.qlikcloud.com",
  appId: "YOUR-APP-ID",
  clientId: "YOUR-OAUTH-CLIENT-ID", // OAuth2 PKCE flow
};

Web Integration ID

const config = {
  host: "your-tenant.qlikcloud.com",
  appId: "YOUR-APP-ID",
  webIntegrationId: "YOUR-WEB-INTEGRATION-ID", // Session-based auth
};

Qlik Sense On-Premise

const config = {
  host: "your-qlik-server.local",
  appId: "YOUR-APP-ID",
  isSecure: false, // or true for HTTPS
  port: 4848, // or 443 for HTTPS
};

Authentication Architecture

The authentication module has been completely refactored into a modular, maintainable architecture:

• 🔐 OAuth2 PKCE: RFC 7636 compliant implementation with secure token management
• 🌐 Web Integration: Session-based authentication with CSRF protection
• 🏢 On-Premise: Cookie-based authentication for Qlik Sense Enterprise
• 📦 Modular Design: 16 specialized modules following SOLID principles
• 🧪 100% Testable: Each authentication provider independently testable
• 📚 Comprehensive Docs: Complete architecture and usage documentation

For detailed authentication documentation, see:

• Authentication Module - Complete usage guide
• Authentication Architecture - System design and diagrams
• Authentication Changelog - Version history

Custom Authentication Callback

You can customize the authentication flow with an onAuthRequired callback:

const config = {
  host: "your-tenant.qlikcloud.com",
  appId: "YOUR-APP-ID",
  webIntegrationId: "YOUR-WEB-INTEGRATION-ID",
};

const options = {
  debugMode: "verbose", // Enable detailed logging
  onAuthRequired: (loginUrl) => {
    // Custom authentication handling
    // e.g., show a custom login modal instead of redirecting
    console.log("Authentication required. Login URL:", loginUrl);
    showCustomLoginModal(loginUrl);
  },
};

<QlikProvider config={config} options={options}>
  <App />
</QlikProvider>;

Documentation

For detailed documentation, see the docs folder:

Getting Started

• Getting Started - Quick start guide
• Core Concepts - Understanding the library
• Authentication - Complete authentication guide

API & Hooks

• API Reference - Full API documentation
• Hooks - Available React hooks
• useKPIs Hook - Detailed guide for multiple KPIs
• Visualizations - Visualization components

Advanced

• Advanced Usage - Advanced patterns
• Troubleshooting - Common issues and solutions

Authentication Module (Deep Dive)

• Auth Module README - Module usage and API
• Auth Architecture - System design and diagrams
• Auth Changelog - Version history and migrations

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide to learn how to:

• Set up the development environment
• Use the internal playground for testing
• Link the package to other projects with npm link
• Follow our code conventions and workflow

License

ISC

Table Component

const ProductTable = () => {
  const { data, columns, loading, sort, pagination, nextPage, previousPage } =
    useTable({
      dimensions: ["Product", "Category"],
      measures: ["Sum(Sales)", "Sum(Quantity)"],
      pageHeight: 20,
    });

  return (
    <div className="table-container">
      <table>
        <thead>
          <tr>
            {columns.map((col, i) => (
              <th
                key={col.id}
                onClick={() => sort(i, "asc")}
                style={{ cursor: col.sortable ? "pointer" : "default" }}
              >
                {col.title}
              </th>
            ))}
          </tr>
        </thead>
        <tbody>
          {data?.map((row, i) => (
            <tr key={i}>
              {row.qMatrix[0].map((cell, j) => (
                <td key={j}>{cell.qText}</td>
              ))}
            </tr>
          ))}
        </tbody>
      </table>

      <div className="pagination">
        <button onClick={previousPage} disabled={pagination.currentPage === 0}>
          Previous
        </button>
        <span>
          Page {pagination.currentPage + 1} of {pagination.totalPages}
        </span>
        <button onClick={nextPage} disabled={!pagination.hasNext}>
          Next
        </button>
      </div>
    </div>
  );
};

Built with ❤️ by Cluster Data Experience