@iaceene/theme-detector

A tiny, zero-dependency utility to detect the user’s preferred color scheme in browser environments.

Table of Contents

• Features
• Installation
• Quick Start
• API
• Runtime Behavior
• Use Cases
• Development
• Contributing
• License

Features

• Zero dependencies
• TypeScript support out of the box
• ESM-compatible package exports
• Safe fallback for SSR/Node runtimes

Installation

npm install @iaceene/theme-detector

Quick Start

import Theme, { getTheme } from "@iaceene/theme-detector";

const currentThemeA = Theme.getTheme(); // "dark" | "light"
const currentThemeB = getTheme(); // "dark" | "light"

API

Theme.getTheme(): "dark" | "light"

Returns the current preferred color scheme using:

window.matchMedia("(prefers-color-scheme: dark)")

getTheme(): "dark" | "light"

A convenience function equivalent to Theme.getTheme().

Runtime Behavior

• Browser runtime: detects system preference and returns "dark" or "light".
• Non-browser runtime (SSR/Node): returns "light" as a safe default.

Use Cases

• Set default app theme on first load
• Choose dark/light assets based on user preference
• Keep SSR rendering stable with deterministic fallback

Development

npm install
npm run build

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening an issue or pull request.

License

ISC