CLI tool
Tencent/omi avatar
Tencent/omi

Omi's @tag decorator, its module-level signals, and two years between npm and master

Web Components Framework.

13,282 stars1,258 forksTypeScriptNOASSERTION

At a glance

What is it?
Omi is Tencent's Web Components framework: JSX, custom elements registered by a decorator, and reactivity through signals. The interesting parts are where the docs are quiet, including the gap between the newest release tag and the last commit on master, and the fact that most of the starter kits are not published at all.
Who is it for?
Omi suits a team that wants custom elements and JSX in one codebase and is willing to clone starter repos from GitHub instead of expecting scaffolding from npm. It is a poor fit when your release process depends on `npm i omi` matching the repository head, because the newest tag, v7.7.0, dates from 2024-09-08 while master was pushed through 2026-10-10.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 4 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Tencent/omi13,282 ★ · +14
Star history
Repository2026-09-222026-11-15
Tencent/omi13.3k13.3k

14 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The example puts its signal at module scope, so every instance shares one counter

The worked example in the README declares `const count = signal(0)` at module scope, outside the class, and the component reads `count.value` inside its render function. Two `counter-demo` elements on one page therefore share a single number and a single pair of `add` and `sub` functions. That is the reactive-signal model the project is built on, and it is the first thing to settle before committing to it: state lives in a signal rather than in a component field, so a counter per table row means a signal per row. The class itself carries its tag and its styles and little else:

tsx
@tag('counter-demo')
export class CounterDemo extends Component {
  static css = 'span { color: red; }'

That `static css` field is the styling hook, and the framework's approach to style is built on Constructable Stylesheets, which means the rule travels with the element definition instead of living in a stylesheet you have to remember to load.

Three mounting styles, and the plainest one only works because an import already ran

Mounting is where the Web Components half of the framework shows itself. The README gives three routes. Render the tag as JSX:

tsx
render(<counter-demo />, document.body)

Or import the class and render it directly:

tsx
render(<CounterDemo />, document.body)

Or skip the framework entirely and let the DOM do it:

tsx
document.body.appendChild(document.createElement('counter-demo'))

The third route only works because `import './counter-demo'` ran first and the `@tag` decorator registered the custom element definition. That registration is the actual contract: without the side-effect import, `document.createElement` returns an unknown element and nothing renders. The second route carries its own warning in a code comment reading `// Prevent tree Shaking when importing other things`, which tells you that importing the class next to other exports changes what your bundler is allowed to drop.

Two snake games in the repo, one on the Signal class and one on reactivity functions

The examples directory is short and specific: `examples/form/`, `examples/forward-ref/`, `examples/suspense/` and `examples/transition/`. Under `packages/` sit two versions of the same toy, `snake-game-2tier` described as a snake game with the `Signal` class and `snake-game-3tier` described as one with reactivity functions. Neither is published to npm, so they are read rather than installed. The pairing tells you the framework carries two reactivity styles and expects you to choose, which is a tax on a small team learning the API surface. A component written against the Signal class path does not read like one written with reactivity functions, and the conversion is yours to do. The presence of `examples/forward-ref/` answers a question the README never asks out loud, which is what happens when components have to refer to each other inside a JSX tree.

v7.7.0 was tagged in 2024, and master has taken commits ever since

The maintenance signals disagree with each other, and the gap is the thing to weigh. The most recent release tags are v7.7.0 from 2024-09-08, v7.6.18 from 2024-09-03 and v7.6.6 from 2024-02-29, all clustered in the v7.6 to v7.7 range. The master branch was last pushed on 2026-10-10. In practice that means the newest tagged release is roughly two years behind the newest commit in the repository, so the code you read on GitHub may not be the code `npm i omi` installs. The feature list does not help calibrate this, since the claims of tiny size and fast performance carry no figures and the repository root holds no benchmark directory to check them against. Decide which of the two artefacts you are adopting, because a framework whose npm dist and GitHub head drift apart raises a different question from one that tags every change.

Most of the useful starting points are marked not published to npm

The package list is split by distribution channel, and the split matters before you plan anything. On npm: `omi`, `omi-router`, `omi-cli`, `omi-form`, `omiu`, `lucide-omi`, the components `omi-weui`, `omi-suspense` and `omi-auto-animate`, and the directives `omi-transition` and `omi-ripple`. Not on npm: every starter kit, including `omi-elements`, `omi-starter-spa`, `omi-starter-ts`, `omi-starter-tailwind`, `omi-starter-js` and `omi-vue`, plus the example repos. So `npm i omi-starter-spa` does not work and the scaffolding has to come from a clone. Two of the published packages also wrap work that is not Omi's own: `omi-auto-animate` is described as the Omi version of `@formkit/auto-animate`, and `omiu` exists to bring libraries such as vchart and vtable in as web components. Both matter when you audit a dependency tree, since one brings an upstream release cadence with it and the other binds your charting library to a component model.

Two CLI scaffolds that differ in how much they wire up for you

Two scaffolding commands cover the common cases, and the difference is scope rather than language:

bash
$ npx omi-cli init my-app    # or create js project by: npx omi-cli init-js my-app
$ cd my-app
$ npm start           # develop
$ npm run build       # release

The `init-spa` variant is the wider of the two, generating Omi plus Router plus Signal plus Suspense plus Tailwindcss on Vite and TypeScript:

bash
$ npx omi-cli init-spa my-app

Documentation is scattered rather than filed. The front page links a Chinese version of itself as `README.CN.md`, and the guides live on the project's own CDN domain on separate pages for the tutorial, the templates, the form component documentation and the form playground. There is no docs directory in the repository root, so grepping the checkout for an answer about routing or Suspense will not find one.

The front page names no licence, though a LICENSE file sits at the root

The monorepo root holds `.gitattributes`, `.gitignore`, `LICENSE`, `README.md`, `README.CN.md`, `assets/`, `examples/` and `packages/`, which tells you where to look for any given piece: framework code plus every starter, component and directive under `packages/`, runnable demos under `examples/`. On licensing, GitHub's licence field reads NOASSERTION and a `LICENSE` file exists at the repository root, so read that file before adopting. Ownership of the linked packages is also not uniform: `omi-cli` sits in the omijs organisation rather than Tencent, the Lucide icon set lives there too, and the rest of the framework sits under Tencent.

Editorial conclusion

Omi suits a team that wants custom elements and JSX in one codebase and is willing to clone starter repos from GitHub instead of expecting scaffolding from npm. It is a poor fit when your release process depends on `npm i omi` matching the repository head, because the newest tag, v7.7.0, dates from 2024-09-08 while master was pushed through 2026-10-10. Check three things before committing: which tagged version npm actually serves, whether the starter you want is one of the packages marked not published to npm, and what the LICENSE file at the repository root grants, since GitHub's licence field reads NOASSERTION.

Frequently asked questions

What is Omi the framework?

Omi is a Web Components framework from Tencent written in TypeScript, which registers custom elements with a `@tag` decorator and handles reactivity through signals built on reactive-signal. The README lists JSX, function components, a router, Suspense, directives and Tailwind integration, with the router, Suspense and directives shipped as separate packages.

How do you create a new Omi project?

`npx omi-cli init my-app` scaffolds an Omi plus Vite plus TypeScript project, and `npx omi-cli init-js my-app` does the same in JavaScript. Inside the new folder, `npm start` runs the development server and `npm run build` produces a release build.

How do you use Omi in an existing project?

Install it with `npm i omi`, then import `render` and `h` from 'omi' where you need them. Any component file imported only for its side effect must stay imported, because the `@tag` decorator registers the custom element and without that registration `document.createElement` returns an element that never renders.

Does Omi include routing and form handling?

Both arrive as separate packages: `omi-router` for single page apps and `omi-form`, described as a cross-framework form solution. The `npx omi-cli init-spa my-app` command scaffolds Omi together with Router, Signal, Suspense and Tailwindcss in one step.

Official sources

  1. Issues
  2. Project website
  3. README
  4. Releases
  5. Tencent/omi on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/tencent-omi.svg)](https://hysenlabs.com/projects/tencent-omi)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/tencent-omi.svg)](https://hysenlabs.com/projects/tencent-omi)

Was this useful?