air-conditioner: an embeddable virtual AC widget for web pages

What air-conditioner is and what it is explicitly not

air-conditioner is a web widget that displays a simulated portable air conditioner unit. The README lists its advantages as: can be opened at any time and any place, is portable, has low power consumption, is silent, is simple to operate, and is easy to install. It then lists its disadvantages as a single entry: no wind.

The project is a novelty and a demonstration of what can be built with web technologies. The README describes it as 'Yun Portable Air Conditioner' and links to a blog post by the author describing the origin of the project. Its purpose is not to provide temperature information or simulate cooling in any functional sense. The widget renders a styled HTML and CSS representation of an air conditioner panel with a temperature readout, interactive buttons, working sounds, and a fan animation.

The hosted demo is at ac.yunyoujun.cn. A test environment is at ac.yyj.moe, and a sample embedded page is linked in the README.

Why HTML and CSS instead of Canvas

The README lists low power consumption as one of the project's explicit design characteristics and attributes it to the use of HTML and CSS rendering rather than Canvas. Canvas-based animations run via JavaScript on every frame, consuming CPU even when the animation is simple. HTML and CSS animations offload compositing to the browser's rendering engine and can take advantage of GPU acceleration with fewer main-thread cycles.

The practical outcome for an embeddable widget is that a page with an embedded air-conditioner iframe uses less CPU than one embedding a canvas-based animation of comparable visual complexity. For personal blogs or pages where the widget is a secondary element, that difference matters.

The package.json shows the project uses UnoCSS as its atomic CSS engine and packages under a pnpm workspace with both React and Vue front-end variants (packages/react and packages/vue). The build pipeline uses TypeScript and Vite. The UnoCSS-based styling also means the final CSS output contains only the utility classes actually used, keeping the stylesheet small.

Embedding with an iframe

The simplest way to add the widget to a page is a single iframe tag from the README:

<iframe height="740" src="https://ac.yunyoujun.cn"></iframe>

This embeds the hosted version at its default size. No width is specified in the README's example; the layout adjusts within the iframe container. The README links to a sample room page at www.yunyoujun.cn/air-conditioner-room/ that shows the widget embedded in a styled page.

For Hugo-based static sites, the README notes that a Hugo shortcode for embedding the air conditioner is available at the kuole-o/Hugo-air-conditioner repository. The README links to it as an example of a third-party integration rather than a first-party plugin.

Self-hosting with Docker and the available environment variables

The README documents Docker as the self-hosting method, with two environment variables for configuration:

- AC_NGINX_DOMAIN sets the domain name for the Nginx configuration - AC_NGINX_PORT sets the listening port

For local development, clone the repository and use pnpm:

yarn start
# http://localhost:3000/

The package.json shows the dev script runs the React variant by default via pnpm -C packages/react run dev. The build command produces output in the packages/ directories. A full build and check sequence runs lint, typecheck, tests, and build:

yarn build

The repository also documents a Tencent Cloud one-click deployment option using Webify. The .env.example file in the repository root contains a single variable:

VITE_DISABLE_ADSENSE=true

Setting VITE_DISABLE_ADSENSE=true in a .env file disables the AdSense integration when self-hosting, which is the standard configuration for private deployments that do not need to show ads.

Features: temperature range, audio, and dark mode

The README's todo list documents which features are complete. The temperature display supports a range of 16 to 31 degrees Celsius. The fan animation is rendered in CSS. Sound effects include button click sounds and a working fan sound; the README credits the fan sound to a freesound.org recording and lists the Digital 7 font used for the numeric display as free for personal use.

Dark and light mode switching is automatic, adapting to the operating system preference. The package.json browserslist configuration targets browsers with more than 0.2% market share in production and the latest versions of Chrome, Firefox, and Safari in development.

The repository uses Playwright for end-to-end tests, as shown by the playwright.config.ts file at the root. The vitest.config.ts file handles unit tests. The pnpm workspace structure and the packages/ directory indicate the core widget logic is published as a separate @yunlefun-home/air-conditioner-core package, distinct from the React and Vue wrappers.

Limitations and when to use something else

The project is a single-purpose decorative widget. It does not accept configuration for temperature units, locale, or custom visual themes beyond what is built in. The README documents no API for controlling the widget from the parent page via JavaScript, which means embedding applications cannot drive its state programmatically.

A developer who wants a weather widget that displays real current temperature data from an API would need an entirely different project. A developer who wants an animated background element without the air conditioner visual metaphor would find a simpler CSS animation more maintainable, since the air conditioner's interactive controls (the on/off button, temperature adjustment, and mode switching) are specific to the AC metaphor and do not generalize to other widget types.

The self-hosting workflow requires pnpm (the README's package manager, specified as [email protected] in package.json) for the development and build steps. The Docker deployment path simplifies production hosting but still requires a build step to produce the static files the Nginx container serves. The repository uses EdgeOne as a CDN, as shown by the edgeone.json file at the root, though this is specific to the author's own deployment rather than a requirement for self-hosters.

The last push to the repository was on 2026-07-26. The project is under recent activity based on that date.

Editorial conclusion

air-conditioner is appropriate for personal blogs, portfolio sites, or developer tools pages that want a lightweight interactive widget with no backend requirements. The iframe embed requires a single line of HTML and no configuration. Self-hosting requires a working pnpm and Node environment plus Docker for containerized deployment. The project is not appropriate for any use case where the visual element must communicate real temperature data: the README explicitly lists 'no wind' as a design characteristic, confirming the widget is decorative. The last push was on 2026-07-26.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. YunYouJun/air-conditioner on GitHub