TinyVue: a Vue 2 and Vue 3 component library that shares one codebase

The problem TinyVue solves: one component set for two Vue majors

Most Vue component libraries pick a side. Element Plus, for example, targets Vue 3 only, while Element UI stayed on Vue 2. That split forces teams with a large Vue 2 codebase into a rewrite before they can use a current component library, or into maintaining two component sets during a migration that may take years.

TinyVue's answer is a single source tree that compiles to both. The README states the library supports both Vue.js 2 and Vue.js 3, and that the same code covers PC and mobile. The repository layout backs this up: there are separate tsconfig.vue2.json, tsconfig.vue2.7.json and tsconfig.vue3.json files at the top level, and examples/vue2 and examples/vue3 sit side by side under examples/. The package.json exposes separate dev scripts, pnpm dev for Vue 3 and pnpm dev2 for Vue 2, so a contributor can run either example without editing configuration.

The intended audience is therefore not a greenfield side project. It is an enterprise team with an existing Vue 2 application, a design system that has to hold across desktop and mobile, and a migration to Vue 3 somewhere on the roadmap but not this quarter. The README also lists internationalization, theme customization and configuration-driven components for low-code platforms, which points at the same audience: teams building internal tooling rather than marketing pages.

How the cross-version and cross-device support is wired

The mechanism is a compatibility layer plus per-version TypeScript configuration, not two forks of the source. The README describes it as one code, support both Vue.js 2 and Vue.js 3, and one code, support both PC and Mobile. Concretely, the repository carries three tsconfig files for the Vue targets and a volar.config.js at the root, and the workspace is split by pnpm-workspace.yaml across packages/, internals/ and examples/.

The internals/ directory holds the build tooling. The package.json scripts reference internals/cli for build:entry, create:ui, create:mapping and build:entry-app. That matters more than it first appears: the entry points for each component are generated, not hand-written. A postinstall hook runs pnpm build:internals automatically, so the generated entry files exist before you start the dev server. If you clone the repository and skip the install step, the component entries will not be there.

The package is published under the name @opentiny/vue, with major-version tags doing the Vue routing: @opentiny/vue@3 for Vue 3 and @opentiny/vue@2 for Vue 2. That is a clean convention, though it means the version number you read in a bug report tells you which Vue major the reporter is on, and nothing about feature parity between the two lines.

Installing TinyVue and rendering a first component

Installation is a single npm command. The README gives the Vue 3 form first:

npm i @opentiny/vue@3

For a Vue 2 project the README gives the parallel command, which pulls the same package name at the v2 major tag:

npm i @opentiny/vue@2

After installing, import the component you need. The README's example imports Button under an alias and uses it in a template:

<script lang="ts" setup>
  import { Button as TinyButton } from '@opentiny/vue'
</script>

<template>
  <tiny-button>Tiny Vue</tiny-button>
</template>

The alias matters. The exported name is Button, and the README renames it to TinyButton so the template tag reads <tiny-button>. If you import it without the alias, you would write <Button> in the template, which collides with native HTML naming conventions and with other libraries. Follow the README's alias pattern unless you have a reason not to.

If you want to run the library's own examples rather than consume the package, the README's development section clones the repository and uses pnpm, with Node >=18 and pnpm >=9.5 required by the engines field in package.json:

git clone git@github.com:opentiny/tiny-vue.git
cd tiny-vue
pnpm i
pnpm dev

The README states the dev server is then reachable at http://127.0.0.1:7130/. Swap pnpm dev for pnpm dev2 to run the Vue 2 example instead. Note the preinstall hook: it runs npx only-allow pnpm, so npm install inside the repository will be rejected.

Where TinyVue is the wrong choice

The cross-version promise has a cost, and the cost lands on Vue 3-only projects. Every component in the package carries compatibility code so it can run under both Vue majors, and you pay for that in bundle size and in the indirection you read through when debugging. A team that started on Vue 3 and will never ship a Vue 2 build is carrying a layer it cannot use.

The second constraint is tooling. The repository is a pnpm workspace with a preinstall guard that rejects npm, a postinstall step that builds internals, and a generated entry-point system driven by internals/cli. That is fine inside the project and mostly invisible when you consume the published package, but it raises the cost of contributing a component or patching one locally. If you need to fork a single component and ship it yourself, you are forking a workspace, not a file.

The third is documentation depth. The README covers installation, a Button example, and the dev commands. It does not document the compatibility layer, the theming API, or the mobile behaviour beyond the claim that both are supported. The homepage at opentiny.design/tiny-vue is where component-level detail lives, and the README points there rather than reproducing it. Treat the README as an entry point, not a reference.

TinyVue compared with Element Plus and Vuetify

The closest comparison is Element Plus, which is Vue 3 only. If your application is already on Vue 3, Element Plus gives you a narrower dependency with no compatibility layer, and its ecosystem of third-party extensions is larger. TinyVue's advantage appears only when you have a Vue 2 application in the same organisation, because then one component vocabulary covers both codebases during the migration window.

Vuetify differs on a different axis. It implements Material Design as a system, so the visual language is decided for you and customization means working within Material's rules. TinyVue's README lists theme customization as a feature and ships a packages/theme directory in the workspace, which suggests a token-based approach rather than a fixed design system. Teams with an existing brand system usually prefer the latter; teams without a designer usually prefer the former.

There is also a headless option to consider. The package.json keywords include renderless-components and headless-components, which signals that TinyVue's architecture separates behaviour from presentation in places. If your team wants full control of markup and styling, a headless library plus your own CSS is a legitimate alternative, at the cost of writing the markup yourself for all 104 components.

Release cadence, licence and upgrade cost

The repository is not archived, and the last push was on 2026-07-28. The most recent release listed is v3.31.0 on the same date. The two prior releases, v3.29.0 and v3.30.0, landed on 2026-02-12 and 2026-04-03. That is roughly a quarterly rhythm with a gap in the middle of the year, which is worth knowing if you depend on a fix landing quickly.

One detail to check before you pin a version: the root package.json declares version 3.32.0, while the latest release listed is v3.31.0. The root package is private and versioned separately from the published @opentiny/vue package, so this is not necessarily a discrepancy in what you install, but confirm the published version on npm rather than reading the repository's package.json as the source of truth.

Upgrade cost is dominated by the Vue major you are on. If you are on Vue 2 and stay there, you track the @opentiny/vue@2 line, which the release list does not show at all, so its maintenance rhythm is not visible from this material. If you are migrating to Vue 3, the switch is a package tag change plus whatever API differences the two lines carry, and the README does not document a migration guide. That absence is the single largest unknown for a team planning the move.

The licence is MIT, declared in both the LICENSE file and the package.json license field. MIT permits commercial use, modification and redistribution with the copyright notice retained. This is a factual statement about the licence text, not legal advice; if your organisation has specific obligations around attribution or bundled dependencies, have counsel review it.

Editorial conclusion

Adopt TinyVue if you maintain a Vue 2 application that cannot move to Vue 3 yet and you want one component set for both, or if you need PC and mobile views from the same components. Do not adopt it if you only target Vue 3 and want a small dependency surface, because the cross-version layer is weight you will never exercise. Before committing, verify three things: which Vue minor the @opentiny/vue@2 line supports, whether the components you need are covered by the theme package, and how the dev branch's 3.32.0 version in package.json lines up with the published v3.31.0 release.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes