A polished, serverless browser for Xiaomi MIoT specifications. It runs entirely in the browser, reads the official public API at miot-spec.org, and exports as a static Next.js site for GitHub Pages.
- Fast product-name, model, brand, device-type, and URN search across the official specification index
- Released specifications by default, with Preview and Debug data loaded only on demand
- Draft/apply multi-select device-type filters with Chinese and English labels
- Smart relevance/time sorting, localized alphabetical sorting, and automatic infinite scrolling
- Separate landing and explorer routes, version switching, and shareable query-string URLs
- Two-column device details with a sticky overview and a flat service-member tree
- Official
zh_cn/ English specification translations with safe fallback behavior - Responsive shadcn/ui interface with system, light, and dark themes
- Category icons derived from the MIoT URN device type, with a generic fallback
- Browser-only API access: no API routes, server actions, database, or application backend
The instance index is fetched from:
https://miot-spec.org/miot-spec-v2/instances?status=released
Each status has its own entry in the browser Cache Storage:
- A cached response younger than 24 hours is used without making a network request.
- Clicking Refresh data bypasses the fresh cache and replaces it with the latest response.
- Once the cache is older than 24 hours, the next visit refreshes it automatically.
- If that refresh fails, the stale cached response remains usable and the UI shows an offline-cache warning.
- Specification details and translations use the same cache policy.
The behavior is implemented and tested in lib/miot/cache.ts.
The product photographs shown by home.miot-spec.com come from product-center icon_real URLs; those URLs are not part of the public specification index and cannot be reconstructed from a MIoT URN.
This project instead parses the device:<type> segment of each URN and maps it to a Lucide icon. The mapping is centralized in components/miot/device-icon.tsx, so adding aliases or new device categories does not affect the card and detail components.
Requirements:
- Bun 1.3.14 or newer
- Node.js-compatible environment supported by Next.js 16
bun install
bun run devOpen http://localhost:3000.
Quality checks:
bun run lint
bun run typecheck
bun run test
bun run buildbun run build writes the static site to out/.
The browser ships a compact static model → localized name/alias dictionary. It is not fetched from a third-party service while a user searches. To explicitly refresh the committed snapshot from the public product sitemap and search metadata used by the reference site:
bun run data:update-productsThe updater groups models by manufacturer, limits concurrency, retries transient failures, writes checkpoints, and falls back to exact-model lookups only for missing records.
The landing page is /; search and detail state live on the static /explore/ route so direct links work on GitHub Pages:
| Parameter | Purpose | Example |
|---|---|---|
q |
Search query | ?q=yeelink.light |
statuses |
Comma-separated status filters | ?statuses=released,preview |
types |
Comma-separated device types | ?types=light,switch |
sort |
Explicit list sort (name or time) |
?sort=name |
order |
Sort direction (asc or desc) |
?order=asc |
model |
Open a device detail | ?model=yeelink.light.ceiling22 |
version |
Select a specification version | ?version=2 |
The workflow in .github/workflows/pages.yml runs linting, type checking, tests, and the static build before deploying out/.
- Push the repository to GitHub.
- Open Settings → Pages.
- Set Source to GitHub Actions.
- Push to the default
mainormasterbranch, or run the workflow manually.
The checked-in workflow targets the custom domain miot.sky2333.top, so it builds with an empty base path and serves the site from /. To build for a standard GitHub project site instead, provide the repository path explicitly:
PAGES_BASE_PATH=/miot-spec bun run buildKeep it empty for a custom domain or an owner-level *.github.io repository.
app/ Static landing/explorer routes and global theme
components/miot/ Search, cards, header, icons, and spec detail UI
components/ui/ shadcn/ui source components
hooks/ Client-side search worker integration
data/ Static product-name snapshot
lib/miot/ API, cache, aliases, device types, URN parsing, search, and i18n
scripts/ Explicit offline data refresh utilities
workers/ Off-main-thread device search
- MIoT specification service: https://miot-spec.org/
- MIoT documentation: https://iot.mi.com/v2/new/doc/introduction/knowledge/spec
- Product-name reference metadata: https://home.miot-spec.com/
This is an independent browser for public technical specifications and is not an official Xiaomi product site.