ng-common-libs

Pure TypeScript library with Auth0 authentication service and framework-agnostic event bus.

🎯 Simple Architecture

One import path. Everything you need. Framework-agnostic.

All services, utilities, and types are exported from a single package:

import { 
  AuthService, 
  EventBus, 
  APP_CONFIG,
  UserInfo
} from '@opensourcekd/ng-common-libs';

📖 Complete Guide: See docs/CONSUMPTION_GUIDE.md for detailed usage instructions.

🚀 Features

• AuthService: Complete Auth0 authentication with token management (Pure TypeScript - no Angular dependency)
• EventBus: Framework-agnostic event bus using RxJS
• Logger: OpenTelemetry-compliant structured logging with observable log streams
• CSS Tokens: Shared design tokens (colors, typography, spacing, shadows, and more) as CSS custom properties
• Works with any framework: Angular, React, Vue, Svelte, vanilla JS
• Module Federation Support: Singleton pattern works across shell + MFEs
• Zero Framework Lock-in: Core services are pure TypeScript classes

📦 Installation

npm install @opensourcekd/ng-common-libs

Note: mitt and @auth0/auth0-spa-js are bundled. No separate installation needed.

🔧 Quick Start

Pure TypeScript Usage (Framework-Agnostic)

import { AuthService, EventBus } from '@opensourcekd/ng-common-libs';

// Create instances
const eventBus = new EventBus();
const authConfig = {
  domain: 'your-domain.auth0.com',
  clientId: 'your-client-id',
  redirectUri: window.location.origin,
  logoutUri: window.location.origin,
  scope: 'openid profile email'
};
const authService = new AuthService(authConfig, eventBus);

// Use the service
await authService.login();
const user = authService.getUser();
const token = await authService.getToken();

// Subscribe to events
eventBus.on('auth:login_success').subscribe(data => {
  console.log('User logged in:', data);
});

API URL Access

No configuration needed - API URL is automatically available:

import { APP_CONFIG } from '@opensourcekd/ng-common-libs';

// API URL is baked into the library during build from GitHub repository variables
const apiUrl = APP_CONFIG.apiUrl;
const endpoint = `${apiUrl}/users`;

ℹ️ Note: The API URL is configured in GitHub repository variables (API_URL) and baked into the library during the CI/CD build process. No runtime configuration is needed in consuming applications.

📚 Documentation

All documentation is in the /docs folder:

• CONSUMPTION_GUIDE.md - Complete setup guide and API reference
• AUTH.md - Authentication with Auth0 (setup, usage, debugging)
• INTEGRATION.md - Angular, Module Federation, auto-deployments
• EVENT_BUS_USAGE.md - Cross-application event patterns
• DEPLOYMENT.md - Publishing and deployment
• ARCHITECTURE_ANALYSIS.md - Architecture overview
• MICROAPP_SETUP_REQUIRED.md - Microapp setup
• COPILOT_EFFICIENCY.md - ⚡ How to use GitHub Copilot efficiently

🎨 CSS Design Tokens

Shared CSS custom properties for consistent styling across all micro-frontends.

Usage

In your global stylesheet (styles.css / styles.scss):

@import '@opensourcekd/ng-common-libs/styles/tokens.css';

Available Token Categories

| Category | Example Tokens | |---|---| | Colors | --color-primary-500, --color-success-600, --color-error-500 | | Semantic Colors | --color-brand, --color-text-primary, --color-bg-surface | | Typography | --font-size-md, --font-weight-bold, --line-height-normal | | Spacing | --space-4 (16px), --space-8 (32px), --space-16 (64px) | | Border Radius | --radius-sm, --radius-lg, --radius-full | | Shadows | --shadow-sm, --shadow-md, --shadow-xl, --shadow-focus | | Z-index | --z-index-modal, --z-index-toast, --z-index-tooltip | | Transitions | --transition-fast, --transition-normal, --duration-fast | | Opacity | --opacity-50, --opacity-75, --opacity-100 | | Breakpoints | --breakpoint-sm (640px), --breakpoint-lg (1024px) |

Example

.my-button {
  background-color: var(--color-brand);
  color: var(--color-text-on-brand);
  padding: var(--space-2) var(--space-4);
  border-radius: var(--radius-md);
  font-size: var(--font-size-sm);
  font-weight: var(--font-weight-semibold);
  box-shadow: var(--shadow-sm);
  transition: var(--transition-normal);
}

.my-button:hover {
  background-color: var(--color-brand-hover);
  box-shadow: var(--shadow-md);
}

📝 What's Exported

Everything you need from one import:

import { 
  // Services
  AuthService,
  EventBus,
  Logger,
  
  // Helper Functions
  configureAuth0,
  createAuthService,
  
  // Configuration
  APP_CONFIG,
  AUTH0_CONFIG,
  STORAGE_CONFIG,
  STORAGE_KEYS,
  
  // Utilities
  getStorageItem,
  setStorageItem,
  removeStorageItem,
  
  // Types & Interfaces
  UserInfo,
  UserData,
  TokenPayload,              // Decoded JWT access token payload
  EventPayload,
  Auth0Config,
  Auth0ConfigOptions,
  StorageConfig,
  StorageKeys,
  AppState,
  AuthorizationParams,
  CallbackResult,
  LogRecord,
  LogAttributes,
  LogSeverity,
  LoggerOptions,
} from '@opensourcekd/ng-common-libs';

🛠️ Development

# Install dependencies
npm install

# Build the library
npm run build

# Run linter
npm run lint

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

🧪 Testing

This library maintains high test coverage:

• 99.26% statement coverage
• 83.45% branch coverage
• 100% function coverage

All core utilities and services are thoroughly tested using Jest and Angular testing utilities.

📄 License

MIT

👤 Author

Koustubh Desai [email protected]

🤝 Contributing

Contributions, issues, and feature requests are welcome!

⭐ Show your support

Give a ⭐️ if this project helped you!