> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microapp.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CodeGroup>
  ```bash npm theme={null}
  npm install @microapp-io/user-preferences
  ```

  ```bash yarn theme={null}
  yarn add @microapp-io/user-preferences
  ```

  ```bash pnpm theme={null}
  pnpm add @microapp-io/user-preferences
  ```
</CodeGroup>

### 2. Initialize the SDK

Create an instance of the `UserPreferences` class.

```typescript theme={null}
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:

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

<Warning>
  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.
</Warning>

### 3. Access Theme Preferences

Get the user's current theme preference.

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

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

### 4. Listen to Theme Changes

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

```typescript theme={null}
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.

```css theme={null}
/* 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;
}
```

```typescript theme={null}
// 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:

```html theme={null}
<!-- 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>
```