@mywallpaper/sdk-react

React SDK for building native MyWallpaper widgets.

Installation

npm install @mywallpaper/sdk-react

Or link locally for development:

{
  "devDependencies": {
    "@mywallpaper/sdk-react": "file:../MyWallpaper/packages/sdk-react"
  }
}

Usage

import { useSettings, useViewport } from '@mywallpaper/sdk-react'

interface Settings {
  color: string
  speed: number
}

export default function MyWidget() {
  const { color = '#ff0000', speed = 1.0 } = useSettings<Partial<Settings>>()
  const { width, height } = useViewport()

  return (
    <div style={{ width: '100%', height: '100%', background: color }}>
      {width}x{height}
    </div>
  )
}

Available Hooks

| Hook | Purpose | |------|---------| | useSettings<T>() | Reactive settings from sidebar | | useViewport() | Widget container dimensions | | useStorage() | Per-widget persistent storage | | useSystem() | System info (OS, CPU, memory, battery, disk, network) | | useSystemActions() | Open URLs, files, protocols | | useMediaControl() | Media playback control (play/pause/next/prev) | | useFiles() | Load uploaded file blobs | | useOAuth() | Authenticated API requests | | useSettingsActions() | Update settings, handle button clicks | | useWidgetSDK() | Low-level SDK context |

Network requests use the transparent fetch proxy — just call fetch() directly.

How It Works

This package provides type stubs for development and type checking. At runtime inside the Canvas Iframe, the actual implementations are provided by packages/canvas/src/sdk/ via private runtime module injection.

When you build a widget with external: ['@mywallpaper/sdk-react'], the imports are rewritten to reference the Canvas runtime globals by the WidgetLoader.

Documentation

• Developer Guide
• Architecture
• Quick Reference

Exports

Hooks

export { useSettings } from './hooks/useSettings'
export { useViewport } from './hooks/useViewport'
export { useSystem } from './hooks/useSystem'
export { useStorage } from './hooks/useStorage'
export { useSettingsActions } from './hooks/useSettingsActions'
export { useFiles } from './hooks/useFiles'
export { useOAuth } from './hooks/useOAuth'
export { useSystemActions } from './hooks/useSystemActions'
export { useMediaControl } from './hooks/useMediaControl'
export { useWidgetSDK } from './context/WidgetContext'

Types

export type { ViewportInfo } from './hooks/useViewport'
export type { SystemInfo } from './hooks/useSystem'
export type { WidgetSDKContextValue } from './context/WidgetContext'
export type { FilesHook } from './hooks/useFiles'
export type { OAuthResponse, OAuthHook } from './hooks/useOAuth'
export type { SystemActionsHook } from './hooks/useSystemActions'
export type { MediaControlHook } from './hooks/useMediaControl'
export type { LaunchActionValue, OpenableLaunchActionValue } from './types/settings'
export { isOpenableLaunchAction } from './types/settings'

Launch Action Helper

import {
  isOpenableLaunchAction,
  type LaunchActionValue,
  useSettings,
  useSystemActions,
} from '@mywallpaper/sdk-react'

interface Settings {
  launchAction: LaunchActionValue
}

export default function Button() {
  const { launchAction } = useSettings<Settings>()
  const { openPath } = useSystemActions()

  const handleClick = () => {
    if (!isOpenableLaunchAction(launchAction)) return
    void openPath(launchAction.target, launchAction.kind)
  }

  return <button onClick={handleClick}>Open</button>
}