widget-js/widgets: React desktop widgets for Windows, built around a Widget Hub client

What widget-js/widgets actually ships

This is a desktop widget collection for Windows, written in TypeScript and built with React. The README describes it as "桌面组件 - Widget Hub" and links a preview page at https://widget-js.github.io/widgets/#/ where every widget can be browsed before you build anything. The repository's topic list names the widget types that exist: clock, countdown, todo, reminder, water-reminder, clipboard-history, and several AI-oriented entries including chatgpt and deepseek. There is also a "funny" tag, which tells you the maintainers are not aiming exclusively at productivity software.

The audience is narrower than the topic list suggests. You need Windows, because the description says desktop widgets for windows and nothing in the README contradicts that. You need Node.js, because the AI workflow installs a skill through npx and the repository is a Vite application. And you need to be willing to run a separate desktop client, the WidgetHub Desktop Client, which is distributed through the project's GitHub releases page rather than through npm. That last requirement is the one that decides whether this project is usable for you: the repository you clone is the widget application, not the runtime that puts widgets on your desktop.

The repository itself is a private npm package named @widget-js/react-app with version 0.0.0, so it is not published as a library you can import. It is an application you build and run yourself.

The React app, the core packages, and the MCP server

The dependency list shows the architecture more clearly than the README does. Three first-party packages carry the widget behaviour: @widget-js/core, @widget-js/react, and @widget-js/web-api. The application layer on top is ordinary modern React: react 19.2, react-router-dom 7, tailwindcss 4 through @tailwindcss/vite, Radix primitives, framer-motion and gsap for animation, i18next with a browser language detector, and Supabase clients for auth and data.

The AI path is the part worth understanding. According to the README, you install an AI coding tool, Node.js, and the WidgetHub Desktop Client, then add a skill with npx skills@latest add widget-js/skills. After that you point your coding tool at an MCP server running locally on port 3606. The README gives the configuration as a streamableHttp transport at http://127.0.0.1:3606/mcp. That means the desktop client is expected to expose an MCP endpoint on localhost, and the skill teaches the agent how to call it. The prompt example in the README asks for a stock widget of a given size that lets users pick stock codes and shows real-time prices and price changes.

So the data flow is: agent reads the skill, agent calls the local MCP server, the server produces widget code against @widget-js/core and @widget-js/react, and the desktop client loads the result. The README does not describe what the MCP server exposes beyond the transport and URL, and it does not document the widget manifest format. If you want to write widgets by hand rather than through an agent, you are reading the source.

Installing widget-js/widgets and generating your first widget

The README lays out four steps, and they are the only install instructions in the repository. Start by installing an AI coding tool (the README names Claude Code, Trae and Codex as examples), Node.js, and the WidgetHub Desktop Client from the releases page. The client is the piece that renders widgets on your desktop, so install it before anything else.

Then add the skill. This pulls the widget-js/skills package into your coding tool:

npx skills@latest add widget-js/skills

Next, configure the MCP server in your AI coding tool. The README gives this exact JSON, and the port matters because the client is expected to be listening on it:

{
  "mcpServers": {
    "widgetjs": {
      "transport": "streamableHttp",
      "url": "http://127.0.0.1:3606/mcp"
    }
  }
}

Finally, invoke the skill and describe the widget you want. The README's example prompt is:

/widget Generate a stock widget, 4 by 4 in size, where users can select stock codes and the widget displays real-time prices and price changes.

If the setup is correct, the agent writes the widget and the desktop client displays it. The README does not say what error you see when the MCP server is unreachable, and it does not say whether the client must be running before you configure the tool. Those are the two things to check first if nothing appears.

If you prefer to work on the app itself rather than generate widgets, the repository is a standard Vite project: npm run dev starts the development server, npm run build runs tsc -b followed by vite build, and npm run lint runs eslint with cache. The README does not document these scripts; they come from package.json.

Where widget-js/widgets breaks down

The largest limitation is platform. The description says desktop widgets for windows, and nothing in the README, the topics, or the file listing suggests macOS or Linux support. The related searches people run against this name include "widgets for mac" and "widgets for macbook", and the project does not answer those. If you are on a Mac, the WidgetHub Desktop Client is not described as available to you.

The second limitation is that the repository is not self-contained. The widget runtime lives in a separate downloadable client, and the AI workflow depends on a local MCP server on port 3606 that the client is expected to provide. The README never explains what happens when that server is missing, misconfigured, or blocked by a firewall. There is no troubleshooting section, no mention of logging, and no documented way to run widgets without the client.

The third is documentation depth. The README links a full guide at https://widgetjs.cn/guide, which is where anything beyond the four-step AI flow would live. Judged on the repository alone, the widget API, the manifest format, and the packaging story for distributing your own widget are undocumented. Release notes exist for versions 26.8.26, 26.8.31 and 26.9.3, but the README does not explain the versioning scheme, and the package.json version is 0.0.0, so the release numbers and the package version do not correspond.

Finally, the licence. The repository metadata does not name one, and the top-level file listing shows no LICENSE file. That is not a detail you can defer if you plan to redistribute anything built on this.

How this differs from general-purpose widget tools

The obvious comparison is a tool like Widgetsmith, which is what most people mean when they search for how to use widgets. Widgetsmith is a configurator: you pick a template, adjust appearance, and place the result on a phone or tablet home screen. You do not write code, and you cannot add behaviour that the app does not already offer.

widget-js/widgets inverts that. The unit of work is a React component, the extension path is an AI coding agent talking to a local MCP server, and the output is a widget that runs on a Windows desktop rather than a mobile home screen. That means the ceiling is much higher (a stock widget with live price data is not something a template configurator produces) and the floor is much lower, because you need Node.js, an AI coding tool, a desktop client, and a working localhost MCP connection before you see anything at all.

A closer comparison is building the widget yourself as a plain Electron or Tauri window. That gives you full control of packaging, updates and distribution, at the cost of writing the widget host, the settings UI, and the inter-widget plumbing that @widget-js/core and @widget-js/react appear to provide. widget-js/widgets is worth considering precisely when you want that plumbing to already exist and you accept the Windows-only runtime that comes with it.

Maintenance, releases and what the licence means for you

The repository is not archived, and the last push was on 2026-09-08. Releases are frequent and dated: 26.8.26 on 2026-08-26, 26.8.31 on 2026-08-31, and 26.9.3 on 2026-09-03. The version numbers track dates rather than semantic versions, which is consistent with a project that ships continuously and does not promise API stability between releases. The dependency ranges are also loose (react ^19.2.0, tailwindcss ^4.2.0, framer-motion ^12.34.3), so a fresh install can pull newer minor versions than the ones the maintainers last ran.

The upgrade cost is dominated by the desktop client, not the repository. Because the client is downloaded from the releases page rather than installed through a package manager, updating it is a manual step, and the README does not describe an in-app update path or a rollback procedure. If a new client version changes the MCP endpoint or the widget API, you find out at runtime. On the app side, upgrading means pulling master and reinstalling dependencies, and the lint setup (@antfu/eslint-config plus @eslint-react/eslint-plugin) will flag style drift if you contribute back.

On licensing, the honest answer is that no licence is stated. The repository metadata leaves the licence field unknown and no LICENSE file appears in the top-level listing. Without a named licence, the default position is that the maintainers retain their rights, which affects redistribution and commercial use. If you need to ship something built on this, confirm the licence with the maintainers before you build on it. That is a factual gap, not legal advice, and it is the single easiest thing to resolve before committing.

Editorial conclusion

Adopt widget-js/widgets if you are on Windows, comfortable with React 19 and Vite, and want a starting point for agent-generated desktop widgets rather than a finished product. Do not adopt it if you need macOS or Linux support, a documented public API, or a licence you can confirm before shipping. Verify first that the WidgetHub Desktop Client release installs on your machine, that http://127.0.0.1:3606/mcp answers after the client starts, and that the repository actually contains a LICENSE file, because the metadata does not name one.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. widget-js/widgets on GitHub