Installation

@xocialive/ui-components is published to a private Azure Artifacts npm feed. You need to authenticate before you can install it.

1. Configure .npmrc

Create or update the .npmrc file in the root of your consuming project:

@xocialive:registry=https://pkgs.dev.azure.com/XocialiveProjects/Xocialive-Assets/_packaging/XOC-UI-Components/npm/registry/

//pkgs.dev.azure.com/XocialiveProjects/Xocialive-Assets/_packaging/XOC-UI-Components/npm/registry/:username=XocialiveProjects
//pkgs.dev.azure.com/XocialiveProjects/Xocialive-Assets/_packaging/XOC-UI-Components/npm/registry/:_password=[BASE64_ENCODED_PAT]
//pkgs.dev.azure.com/XocialiveProjects/Xocialive-Assets/_packaging/XOC-UI-Components/npm/registry/:email=npm requires email to be set but doesn't use the value
//pkgs.dev.azure.com/XocialiveProjects/Xocialive-Assets/_packaging/XOC-UI-Components/npm/registry/:always-auth=true

Replace [BASE64_ENCODED_PAT] with your Azure DevOps Personal Access Token encoded in Base64. The PAT needs Packaging (Read) scope at minimum.

Encode your PAT

Linux / macOS:

echo -n ":<YOUR_PAT>" | base64

Windows PowerShell:

[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes(":<YOUR_PAT>"))

2. Install the package

# pnpm (recommended)
pnpm add @xocialive/ui-components

# npm
npm install @xocialive/ui-components

3. Install peer dependencies

pnpm add react react-dom \
  @mui/material @mui/icons-material \
  @emotion/react @emotion/styled \
  react-router-dom recharts

See Peer Dependencies for the full list with version requirements.

4. Import fonts

In your application's main entry file (main.tsx, App.tsx, or index.tsx):

import "@xocialive/ui-components/style.css";

This single import provides all bundled fonts (Tajawal, Cairo, IBM Plex Sans Arabic, IBM Plex Sans, Playpen Sans Arabic) and component-level global styles. Without it, fonts will not render correctly.

5. Wire the providers

src/App.tsx

import { ErrorBoundary, ConfigLoader } from "@xocialive/ui-components/components";
import { AppProvider } from "@xocialive/ui-components/contexts";
import { Provider } from "react-redux";
import { store } from "@/store";

function App() {
  return (
    <ErrorBoundary level="app">
      <ConfigLoader configPath="/config.json">
        <Provider store={store}>
          <AppProvider
            config={{
              fetchPreferences: async () => ({}),
              savePreferences: async () => {},
              currentApplicationId: "my-app",
            }}
          >
            {/* your app */}
          </AppProvider>
        </Provider>
      </ConfigLoader>
    </ErrorBoundary>
  );
}

AppProvider fetches user preferences, wraps ThemeProvider and LanguageProvider, and connects the Redux toast store. See App Setup for the full wiring guide and AppProvider for all configuration options.

---

Troubleshooting

Issue	Solution
401 Unauthorized during install	Regenerate your PAT (Packaging Read scope) and re-encode it in Base64.
404 Not Found for the package	Verify the .npmrc registry URL matches exactly and the @xocialive scope is mapped.
Fonts not loading	Ensure @xocialive/ui-components/style.css is imported in your entry file.
Type errors after install	Confirm @types/react and @types/react-dom are installed.