TypeScript SDK

Microapp Theming for Any Web App

The TypeScript SDK enables you to access and respond to user theme preferences without requiring a particular frontend framework.

Getting Started

1. Install the SDK

Install the SDK with your preferred package manager.

npm

npm install @microapp-io/user-preferences

2. Initialize the SDK

Create an instance of the UserPreferences class.

import { UserPreferences } from '@microapp-io/user-preferences';

// Initialize the SDK
const userPreferences = new UserPreferences();

For local development, you can use the sandbox configuration to test different theme preferences:

// Sandbox initialization with custom theme preference
const userPreferences = new UserPreferences({
  sandbox: {
    theme: 'dark',
  },
});

The sandbox prop should only be used for local development. Make sure to remove it before deploying to production. In production, theme preferences are controlled by the user through the Microapp platform.

3. Access Theme Preferences

Get the user’s current theme preference.

// Get the user's theme preference
const { theme } = userPreferences.getPreferences();
console.log(`User theme: ${theme}`);

The theme preference is controlled by the user through the Microapp platform. Your application should respect this preference and adapt accordingly.

4. Listen to Theme Changes

The SDK provides a way to listen to updates to the user’s theme preference with the onUpdate() method:

userPreferences.onUpdate((newPreferences) => {
  const { theme } = newPreferences;
  console.log(`Theme updated: ${theme}`);
  
  // Update your application based on the new theme
  updateAppTheme(theme);
});

5. Create and Apply Theme Styles

Define your theme styles in separate files and apply them based on the user’s theme preference.

/* styles.css */
:root {
  /* Light theme (default) */
  --background-color: #ffffff;
  --text-color: #333333;
  --primary-color: #0070f3;
  --border-color: #e0e0e0;
}

[data-theme="dark"] {
  --background-color: #121212;
  --text-color: #f5f5f5;
  --primary-color: #90caf9;
  --border-color: #333333;
}

.container {
  background-color: var(--background-color);
  color: var(--text-color);
  padding: 20px;
  border-radius: 8px;
  border: 1px solid var(--border-color);
}

.button {
  background-color: var(--primary-color);
  color: white;
  border: none;
  padding: 10px 20px;
  border-radius: 4px;
  cursor: pointer;
}

// theme.ts
import { UserPreferences } from '@microapp-io/user-preferences';
import './styles.css';

// Initialize the SDK
const userPreferences = new UserPreferences();

// Apply theme function
function applyTheme() {
  // Get the user's theme preference
  const { theme } = userPreferences.getPreferences();
  
  // Apply theme to document
  document.documentElement.setAttribute('data-theme', theme);
  console.log(`Applied theme: ${theme}`);
}

// Apply theme initially
applyTheme();

// Update theme when preference changes
userPreferences.onUpdate(() => {
  applyTheme();
});

// Export the function if you need to apply the theme from elsewhere
export { applyTheme };

You can then use these styles in your HTML:

<!-- index.html -->
<div class="container">
  <h1>Themed Content</h1>
  <p>This content adapts to the user's theme preference.</p>
  <button class="button">Click Me</button>
</div>