Skip to Content
Vuesho

CLI

Copy the theme and the UI into your project to change them.

When the options of a layout or a component aren't enough, copy its source into your project with @vuesho/cli, and edit the copy.

npx @vuesho/cli add layouts/docs

The CLI copies from the vuesho package installed in your project.

Changing a Layout

Copy the Theme

npx @vuesho/cli add theme

The default theme lands in src/theme, where Vuesho picks up src/theme/index.ts as the theme of your site. Its layouts/Docs.vue renders the content pages with the docs layout, imported from the package.

Copy the Layout

npx @vuesho/cli add layouts/docs

The layout lands in src/ui/layouts/docs, and src/theme/layouts/Docs.vue now imports your copy:

+ src/ui/layouts/docs/DocsLayout.vue
...
~ src/theme/layouts/Docs.vue (now imports your copy)

Edit the Copy

Change the files under src/ui/layouts/docs. The pages of your site render with them.

The UI is styled with Tailwind CSS classes. The compiled stylesheet of the site has the classes the UI uses, so a class you add in a copy needs Tailwind CSS in your site.

A site with a src/theme.ts loads that file instead of src/theme/index.ts, so the CLI refuses to copy the theme next to it. Move the file into the folder first, for example to src/theme/own.ts, and update its relative imports, since it is one folder deeper. Then copy the theme, and add what your file exports to src/theme/index.ts.

Commands

list prints the modules you can copy:

npx @vuesho/cli list

They are theme and the modules of the UI, by their path under vuesho/ui, like layouts/notebook, components/card or provider/base. A module comes with the modules inside its folder, so layouts/docs includes its page and its slots.

add copies one or more modules:

npx @vuesho/cli add components/card components/callout

add theme copies the default theme: the base theme with its Root, NotFound and stylesheet, and the docs and home layouts in layouts. The index.ts of the copy is the default theme, which you edit like your own theme. Another layout, like vuesho/layouts/notebook, is copied when a file of your project imports it, and every file of your project then imports the copy.

Options

  • --dir <path>: where modules go, src/ui by default.
  • --theme-dir <path>: where the theme goes, src/theme by default.
  • --overwrite: replace files that exist. Without it, the CLI keeps your files and lists them.
  • --cwd <path>: the project, the current folder by default.

Imports of a Copy

A copy imports the rest of the UI from the package, like vuesho/ui/contexts/tree, and keeps the relative imports inside its own folder. When you copy a module that other copies or other files of your project import, the CLI changes their imports to your copy and marks them with ~.

Modules you don't copy stay in the package and keep receiving its updates. Copy only what you change.

A copy imports the packages the UI uses, like class-variance-authority. When your project doesn't depend on one, the CLI prints the command to add it, with the package manager of the lockfile of your project:

Your copies import packages your project doesn't depend on yet. Add them:
  npm install class-variance-authority@^0.7.1

Copies Nothing Imports

Your site uses a copy only when a file of your project imports it. The theme and the other modules of the package import the modules of the package, so a copy nothing imports changes nothing. The CLI then lists the modules of the package that import it:

Nothing in your project imports your copy of components/card yet, so your site doesn't use it. Copy a module that imports it, or import it from a file of your project:
  vuesho add mdx

Copy one of them. After add mdx, your copy of mdx imports your copy of the card, and a components module that imports your copy of mdx uses both. The CLI doesn't copy them for you, since a module like components/ui/button is imported by most of the UI.

Primitives

The UI is built on Reka UI, and the package includes the primitives it uses, so there is nothing to install. A copy imports them by family, with every part of the family available:

import { DialogClose, DialogContent, DialogRoot } from "vuesho/reka/dialog";

The families are accordion, collapsible, config-provider, dialog, dropdown-menu, focus-scope, navigation-menu, popover, primitive, scroll-area and tabs.

For another primitive, like a tooltip, install reka-ui. Don't mix the two inside one family: a DialogClose of reka-ui doesn't find a DialogRoot of vuesho/reka/dialog.