@ubnt/unifi-credential-server

UniFi Organization Manager

Figma link: https://www.figma.com/design/TzTMQrLhOy2ryCQLP3GyRN/ORG-Manager?node-id=0-1&p=f&m=dev

📚 Documentation

For comprehensive documentation, see the llm-docs/ directory:

• Architecture - System design and technology stack
• Development Process - Complete setup and workflow guide
• Coding Style - Standards and conventions

Prerequisites

• Node.js: v20.19.5 (see .nvmrc)
• pnpm: v9.x

Development Workflow

IMPORTANT: This project is developed as a library that integrates into the UniFi Portal. Standalone development commands like pnpm dev-cloud-prd, pnpm dev-cloud-stg, and pnpm dev are DEPRECATED.

Setup and Run

1. In This Repository (Org Manager)

# Install dependencies
pnpm install

# Start watch mode for automatic rebuilds
pnpm dev-lib

2. In UniFi Portal Repository

# Link org-mgr (one-time, or after unlinking)
pnpm link /path/to/unifi.hw.org-mgr

# Follow the UniFi Portal README.md to setup certificates (one-time setup)

# Start the dev server
pnpm dev-cloud

UniFi Portal's build config automatically detects the linked package and configures the build to resolve org-mgr's externals from Portal's node_modules.

Development Flow

Terminal 1 (Org Manager)      Terminal 2 (UniFi Portal)
├─ pnpm dev-lib (watch)       ├─ pnpm dev-cloud
└─ Auto-rebuild on changes ──>└─ Triggers page reload

Note: Since org-mgr outputs a single bundled JS file, changes trigger a full page reload rather than true hot module replacement.

Unlinking

When done with local development:

# In UniFi Portal
pnpm unlink @ubnt/unifi-credential-server
pnpm install  # Restore from npm registry

Authentication Setup

The application requires SSO authentication when running in UniFi Portal.

Extract AUTH Cookie

• Login to UniFi Portal:

  • Production: https://unifi.ui.com/
  • Staging: https://unifi.stg.ui.com/

• Extract Cookie:

  • Open DevTools → Application → Cookies
  • Find UBIC_AUTH (production) or STG_UBIC_AUTH (staging)
  • Copy the cookie value

• Add to Localhost:

  • Navigate to UniFi Portal's localhost URL
  • Open DevTools → Application → Cookies
  • Add the cookie with the copied value

Multi-Organization Support

If your account has multiple organizations:

• Open browser console
• Set the organization ID:

  localStorage.setItem('localStorageOrgId', 'your-org-id');
  

• Refresh the page

Note: The organization ID must exist in your account's organization list.

Remote Access Debugging

Display API Requests in Network Tab

Enter in browser console and refresh:

setSwTrafficLoggerTTL(1000 * 60 * 60 * 24); // 24 hours

View API Logs in Console

If network logging doesn't work, use console logging:

openIdentityHubLog(24); // 24 hours

API responses will print in the browser console.

Additional Information

Static HTML Development

For static HTML page development, see Static HTML README

Comprehensive Documentation

For detailed information about architecture, coding standards, troubleshooting, and more:

• Architecture Documentation
• Development Process Guide
• Coding Style Guide

Available Scripts

# Library development
pnpm dev-lib             # Watch mode for development
pnpm build-lib           # Production library build

# Application build
pnpm build               # Production build (cloud)
pnpm build-local         # Production build (local)
pnpm analyze             # Bundle analysis

# Code quality
pnpm eslint --fix        # Fix linting issues
pnpm prettier --write .  # Format code

Technology Stack

• React: 18.3.1
• TypeScript: 5.6.2
• Node: v20.19.5 (see .nvmrc)
• State Management: Redux + React Query
• Styling: Emotion CSS-in-JS
• Build: Webpack 5

For complete technology stack details, see Architecture Documentation