Integration Libraries

Integration packages for Productify framework - frontend and backend.

GitHub Packages (Public)

ProductifyFW packages are published as public packages on GitHub Packages. Add to .npmrc:

@productifyfw:registry=https://npm.pkg.github.com

No authentication required. See Frontend Integration or Backend Integration for details.

Frontend Integration

@productifyfw/core

TypeScript client library for accessing Productify configuration injected by the proxy.

Features:

• Type-safe access to window.__PRODUCTIFY__
• User, tenant, and application context
• Configuration management with defaults
• Pilet loading system - Dynamic ES module loading from feed service
• Framework integration (Vue, React, Angular)

Installation:

npm install @productifyfw/core

Quick Start:

import { ProductifyClient, loadPilets } from "@productifyfw/core";
import { reactive } from "vue";

const pfy = new ProductifyClient();

// User and tenant context
const user = pfy.getUser();
const tenant = pfy.getTenant();

// Configuration
const theme = pfy.getConfig<string>("theme", { defaultValue: "light" });

// Modules (Pilets)
const enabledModules = pfy.getEnabledModules();
if (pfy.isModuleEnabled("dashboard")) {
  // Load dashboard module
}

// Load pilets dynamically
const piletRegistry = reactive({ extensions: {}, pages: {} });
loadPilets("/pilet-feed", piletRegistry);

// Themes
const enabledThemes = pfy.getEnabledThemes();
const defaultTheme = pfy.getDefaultTheme();

// Locales
const enabledLocales = pfy.getEnabledLocales();
const defaultLocale = pfy.getDefaultLocale();

Vue 3 + Pilet Loading Example

Complete example application demonstrating microfrontend architecture with Vue 3, ES module pilets, and @productifyfw/core.

Features:

• Vue 3 shell application with Composition API
• Dynamic ES module pilet loading from feed service
• Custom pilet API (Piral-compatible without framework dependency)
• Example pilet implementations with dashboard widgets
• Productify proxy integration
• CLI pilet upload support with PAT authentication

See the Vue 3 + Pilet Loading Example Guide for detailed documentation.

Backend Integration

@productifyfw/node-express

Express.js middleware for accessing Productify authentication headers.

Features:

• Extract user/tenant from HTTP headers
• Type-safe request context via req.productify
• Authentication middleware
• Permission checking helpers

Installation:

npm install @productifyfw/node-express

Quick Start:

import express from "express";
import {
  productifyMiddleware,
  requireProductify,
} from "@productifyfw/node-express";

const app = express();
app.use(productifyMiddleware({ applicationId: "my-app" }));

app.get("/api/profile", requireProductify, (req, res) => {
  const { user, tenant } = req.productify;
  res.json({ user, tenant });
});

Architecture

Data Flow

┌─────────┐      ┌───────┐      ┌─────────┐      ┌─────────┐
│ Client  │─────▶│ Proxy │─────▶│ Backend │─────▶│ Manager │
└─────────┘      └───────┘      └─────────┘      └─────────┘
     │               │                │                │
     │           Auth Token       X-Headers        Config
     │               │                │             API
     │               ▼                │                │
     │          Validate          Extract           Fetch
     │               │                │                │
     │               ▼                ▼                ▼
     │          User/Tenant      req.productify   /frontend-config
     │               │                │
     │               ▼                │
     └──────▶ window.__PRODUCTIFY__  │
                     │                │
                     ▼                ▼
             @productifyfw/core   @productifyfw/node-express

Frontend (Browser)

1. Proxy injects window.__PRODUCTIFY__ into HTML
2. Application loads and accesses via @productifyfw/core
3. Type-safe access to user, tenant, and configuration

Backend (Server)

1. Proxy forwards requests with authentication headers
2. Express middleware extracts headers into req.productify
3. Route handlers access authenticated context

Type Consistency

Both packages use types that map to the same proxy structures:

Proxy Source	Frontend Type	Backend Type
X-User-ID	user.id	user.id
X-User-Email	user.email	user.email
X-User-Name	user.name	user.name
X-User-Username	user.username	user.username
X-Tenant-ID	tenant.id	tenant.id
X-Tenant-Name	tenant.name	tenant.name
X-Auth-Type	authType	authType
Manager API	config	-

Security Considerations

Frontend

• Configuration is injected by trusted proxy
• No sensitive data should be in frontend config
• Use for UI preferences and feature flags only

Backend

• Headers are injected after authentication
• Headers can be trusted - they come from validated tokens
• Always validate permissions for actions
• Never rely on client-side checks alone
• Implement tenant isolation in database queries

Development Workflow

Setting Up Local Development

1. Start Proxy with authentication enabled
2. Configure Application ID in proxy
3. Add Middleware to backend
4. Access Context in frontend and backend

Testing

Both packages include comprehensive test suites:

Frontend:

cd fe-integrations/packages/core
pnpm test

Backend:

cd be-integrations/packages/node-express
pnpm test

Common Patterns

Full-Stack Type Safety

// Shared types (optional)
interface AppConfig {
  theme: "light" | "dark";
  maxItems: number;
  features: string[];
}

// Frontend
const config = pfy.getConfig<AppConfig>("ui");

// Backend
const { user, tenant } = req.productify;

Permission Checking

// Frontend (UI only)
if (pfy.getConfig<boolean>("features.admin")) {
  // Show admin UI
}

// Backend (actual permission check)
app.get("/api/admin", requireProductify, async (req, res) => {
  const hasPermission = await checkPermission(req.productify.user.id, "admin");
  if (!hasPermission) {
    return res.status(403).json({ error: "Forbidden" });
  }
  // Process admin request
});

Monorepo Structure

Both integration libraries use pnpm workspaces for monorepo management:

fe-integrations/
└── packages/
    └── core/              # @productifyfw/core

be-integrations/
└── packages/
    └── node-express/      # @productifyfw/node-express

This structure allows for future platform-specific packages while sharing common configurations.

Further Reading

• Frontend Integration Guide
• Backend Integration Guide
• Proxy Configuration
• Manager API