# vuepress-theme-reco 2: a Tailwind based theme for VuePress

> vuepress-theme-reco 2 is the second generation of the reco theme for VuePress 2, built on Tailwind CSS and postcss, extended through a dedicated page plugin, and documented separately from the VuePress default theme because its configuration barely overlaps.

**vuepress-reco/vuepress-theme-reco** — 🎨 This is the repo for vuepress-theme-reco 2.

- Repository: https://github.com/vuepress-reco/vuepress-theme-reco
- Website: https://vuepress-theme-reco.recoluan.com
- Stars: 667 · Forks: 220
- Language: TypeScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/vuepress-reco-vuepress-theme-reco

## Why the 1.x code was pushed into a separate repository

The repository states its own scope in the first line: this is the repo for vuepress-theme-reco 2, and the 1.0 repository has been migrated to a separate project, vuepress-theme-reco-1.x. The author explains the reasoning in terms of professionalism and flexibility, and says that some advanced features of the earlier versions required a level of expertise that was hard for people who are not frontend specialists. That is a design position rather than a technical one, but it has an obvious consequence for anyone arriving from the old theme. There is no compatibility path in this repository, and upgrading from 1.x is a migration between two codebases rather than a version bump. The last push to the repository was on 2026-07-23, and it publishes no GitHub releases, so versions are tracked through the package registry and the changesets directory.

## Tailwind and postcss replace the scss pipeline

The style approach is the clearest signal of the rewrite. The theme adopts the tailwindCSS scheme, and the optimisation list records that scss was removed in favour of a css plus postcss solution. The sidebar styles were also reworked and the documentation was expanded. What is missing from that list is as informative as what is on it. An entry for a tailwind custom config entry is still unchecked in both the alpha and beta lists, with a note that later official styles and plugins all move to the css plus tailwindcss approach. In practice that means the theme ships with Tailwind as a given, and a project that needs to extend the Tailwind configuration itself has no documented entry point yet. A second unchecked item is PWA style optimisation, and another is a configuration option for images adapting to dark mode.

## The configuration document is the theme's own, not the default theme's

This is the single most important line in the documentation for an adopter. Some functions of reco 2.x refer to the default theme of vuepress 2.x, but it is no longer magically changed on the default theme the way 0.x and 1.x were. The theme has its own set of solutions, and the project states plainly that you must rely on this document to configure your project, and that you cannot compare it with the official default theme document because only a small amount of configuration overlaps. That is a real cost of the rewrite. A team arriving from the 1.x theme, or from the default theme, will find that familiar configuration keys behave differently or not at all, and the migration is a read through the theme documentation rather than a diff of two option lists.

## Page extension happens through a separate plugin

Where the old theme relied on being able to reshape the default theme, the 2.x line moves that capability into a plugin: page extension is realised through @vuepress-reco/vuepress-plugin-page. The repository layout supports that reading. The root package.json is a private pnpm workspace with two workspace globs, packages/vuepress-theme-reco and packages/@vuepress-reco/*, so the theme and the scoped plugin packages are developed together but published separately. The example directory then shows what the result looks like in practice, with separate folders for bar, blogs, docs, en, foo, group and series, plus a .vuepress directory, which is the per-folder functional support the beta list describes for series, docs and blogs.

## Starting a project with the theme CLI

The quick start offers three routes, and all of them end in the same place. With npx, no global install is needed:
```bash
npx @vuepress-reco/theme-cli init
```
With npm, the CLI is installed globally first and then run:
```bash
npm install @vuepress-reco/theme-cli@1.0.7 -g
theme-cli init
```
And with yarn:
```bash
yarn global add @vuepress-reco/theme-cli@1.0.7
theme-cli init
```
In each case the comment in the documentation is the same: init, and choose 2.x. The pinned CLI version, 1.0.7, is worth noticing, because a scaffold that defaults to the 1.x layout would leave you with the old theme's directory structure and the old configuration expectations.

## The plugins that are already in the box

The alpha list of completed features is a decent inventory of what a site gets on day one. There is a custom home page function, an nprogress plugin for the loading bar, a back-to-top plugin, a comment plugin, a container plugin, an announcement plugin, a code preview plugin, and automatic setting of categories from the folder structure. The comment plugin is where a caveat belongs, because the documentation notes that it currently supports only Valine and that Vssue is not yet supported for Vue 3. The beta list adds more: the icon feature and whole-site encryption are done, the Algolia search styling is optimised, the comment plugin is enhanced, and per-folder support for series, docs and blogs is in place. Still open in the beta list are the Tailwind custom config entry and PWA style optimisation.

## The repository as a working example of the monorepo layout

The project is organised as a pnpm workspace with a full toolchain, and the scripts are readable enough to show how the pieces fit together. Documentation and example builds are separate scripts, with vuepress build docs for the documentation site and a clean-cache build of the example application:
```json
    "example:build": "vuepress build example --clean-cache",
    "example:dev": "DEBUG=vuepress* vuepress dev example --clean-cache",
```
The root also holds a changesets directory for versioning, commitlint with an angular conventional changelog, husky hooks for lint-staged and commit messages, eslint and stylelint configuration, and a vetur configuration for editor support. The release path is a build followed by a shell script, and the update path is pnpm up --latest. For a reader deciding whether to adopt the theme, this tree is the honest answer to the question of what maintaining a fork of it would involve.

## Where vuepress-theme-reco 2 is the wrong choice

Three boundaries are visible in the documentation itself. The first is version 2 only. If you need the older layout or its plugins, that code has moved to vuepress-theme-reco-1.x, and the 1.x repository is where the migration target lives. The second is the configuration split. A team that knows the VuePress default theme documentation will not find a matching document here, and the theme says so itself, which means a documentation-first team without time to read a second guide will stall. The third is the extension model. Where a generic documentation site is the goal, a theme that ships its own home page, announcements, container blocks and a page extension plugin is more machinery than the job needs. The alternative approach in that case is the VuePress default theme with its own plugin ecosystem, which shares no configuration with reco and therefore does not carry reco's setup cost, at the price of the blog, series and home page features that reco provides out of the box.

## Conclusion

vuepress-theme-reco 2 fits a VuePress 2 site that wants a blog, documentation and series layout with Tailwind styling, a home page of its own, and plugins such as progress, back-to-top and announcements already wired in. It does not fit a site still on the 1.x theme, since that code now lives in a separate repository, and it does not fit a team unwilling to follow a theme-specific configuration document rather than the VuePress default theme documentation. Before adopting it, read the theme's own documentation, note that the tailwind custom config entry is still on the todo list, and check that the comment plugin supports the provider you need, since only Valine is supported today and Vssue is not yet working with Vue 3.

## FAQ

### How do I start a new project with vuepress-theme-reco 2?

Run npx @vuepress-reco/theme-cli init and choose 2.x, or install the CLI globally with npm install @vuepress-reco/theme-cli@1.0.7 -g or yarn global add @vuepress-reco/theme-cli@1.0.7 and then run theme-cli init.

### Where is the documentation for vuepress-theme-reco 2?

The theme documents itself at vuepress-theme-reco.recoluan.com, and the README insists you rely on that document rather than the official default theme documentation, since only a small amount of configuration overlaps between the two.

### Can I still use the old 1.x version of the reco theme?

Not from this repository. This one holds reco 2, and the 1.0 code has been migrated to the separate vuepress-theme-reco-1.x repository, so moving between them is a migration rather than a version change.

### Which CSS approach does vuepress-theme-reco 2 use?

It adopts the tailwindCSS scheme, and scss was removed in favour of a css plus postcss solution. A custom Tailwind config entry is still listed as an open item in both the alpha and beta todo lists.

### Which comment providers does the reco 2 theme support?

The comment plugin currently supports only Valine. The documentation notes that Vssue is not yet supported for Vue 3, and the comment plugin is listed as enhanced in the beta todo list.

## Sources

- [Issues](https://github.com/vuepress-reco/vuepress-theme-reco/issues)
- [License: MIT](https://github.com/vuepress-reco/vuepress-theme-reco/blob/main/LICENSE)
- [Project website](https://vuepress-theme-reco.recoluan.com)
- [README](https://github.com/vuepress-reco/vuepress-theme-reco/blob/main/README.md)
- [vuepress-reco/vuepress-theme-reco on GitHub](https://github.com/vuepress-reco/vuepress-theme-reco)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vuepress-reco-vuepress-theme-reco