vc-shell

Vue 3 frontend framework for building specialized back-office applications on VirtoCommerce Platform.

Overview

vc-shell is a monorepo containing the core UI framework, CLI tools, shared configs, and reference applications for VirtoCommerce back-office development. It provides a complete Vue 3 design system, a blade-based navigation paradigm, and a dynamic module system for building extensible admin applications.

Overview
Tech Stack
Monorepo Structure
Getting Started
Development
Testing PR Previews
Local Development via portal: Protocol
Architecture
Component Library
Documentation
Contributing
License

Key Features

Blade Navigation — stacked panel navigation with useBlade() composable for opening, closing, and communicating between blades
Component Library — Atomic Design hierarchy (atoms, molecules, organisms) with Tailwind CSS styling
Dynamic Module System — runtime-loaded Vue plugins with semver compatibility and extension points
VcDataTable — compositional table with declarative <VcColumn> API, virtual scroll, column switching, global filters, drag-and-drop reorder, and state persistence
Rich Text Editor — Tiptap-based editor with tables, images, links, and markdown support
Dashboard & Widgets — grid-based dashboard with GridStack, customizable widget system
Responsive Design — mobile-first with dedicated mobile component variants
i18n — built-in internationalization via vue-i18n
Core Composables — reusable logic for API clients, assets, notifications, settings, permissions, and more

Tech Stack

Layer	Technology
Framework	Vue 3 (Composition API, `<script setup>`)
Language	TypeScript (strict mode)
Build	Vite 6
Styling	Tailwind CSS (`tw-` prefix) + SCSS custom properties
Package Manager	Yarn 4 Berry (workspaces)
Testing	Vitest + Vue Test Utils
Storybook	Storybook 10
Linting	ESLint 9 + Prettier
Charts	Unovis
Forms	VeeValidate

Monorepo Structure

vc-shell/
├── framework/                  # @vc-shell/framework — main UI library
│   ├── core/                   #   API clients, composables, plugins, services
│   │   ├── api/                #     Generated API clients
│   │   ├── composables/        #     Composables (useBlade, useAsync, etc.)
│   │   ├── plugins/            #     Modularity, extensions, AI agent
│   │   └── services/           #     Menu, Dashboard, Toolbar, GlobalSearch
│   ├── ui/                     #   Vue components (Atomic Design)
│   │   └── components/
│   │       ├── atoms/          #     Base components (Button, Badge, Icon...)
│   │       ├── molecules/      #     Form & interactive components (Input, Select, Editor...)
│   │       └── organisms/      #     Complex components (Table, Blade, Gallery...)
│   ├── shell/                  #   App chrome: sidebar, auth, dashboard, settings
│   ├── modules/                #   Built-in modules (assets, assets-manager)
│   └── assets/styles/          #   SCSS theme & CSS custom properties
│
├── cli/                        # CLI tools
│   ├── api-client/             #   @vc-shell/api-client-generator
│   ├── create-vc-app/          #   @vc-shell/create-vc-app — project scaffolder
│   ├── migrate/                #   @vc-shell/migrate — migration tool
│   └── vc-app-skill/           #   @vc-shell/vc-app-skill — AI-assisted app generation
│
├── configs/                    # Shared configurations
│   ├── ts-config/              #   @vc-shell/ts-config
│   └── vite-config/            #   @vc-shell/config-generator
│
├── packages/                   # Module Federation packages
│   ├── mf-config/              #   @vc-shell/mf-config
│   ├── mf-host/                #   @vc-shell/mf-host
│   └── mf-module/              #   @vc-shell/mf-module
│
├── apps/                       # Apps for local framework development & debugging
│   └── ...                     #   Place vc-shell apps here (see "Local Development via portal: Protocol")
│
└── .storybook/                 # Storybook configuration

Getting Started

Prerequisites

Node.js >= 22
Yarn 4.x (Corepack: corepack enable)

Create a New App

There are two official workflows for creating vc-shell applications:

CLI scaffolder (@vc-shell/create-vc-app) — deterministic project bootstrap from templates
AI skill (@vc-shell/vc-app-skill) — intent-driven app and module generation in AI coding tools

Option A: CLI Scaffolder (`@vc-shell/create-vc-app`)

Create a new project interactively:

npx @vc-shell/create-vc-app my-app

Or use non-interactive flags:

npx @vc-shell/create-vc-app my-app --type standalone --module-name "Products" --dashboard --mocks

Add a module to an existing app:

npx @vc-shell/create-vc-app add-module orders

See full options and project types in cli/create-vc-app/README.md.

Option B: AI Skill (`@vc-shell/vc-app-skill`) for Claude Code and Codex

Install skill runtime:

# Claude Code runtime (default)
npx @vc-shell/vc-app-skill@alpha install

# Codex runtime
npx @vc-shell/vc-app-skill@alpha install --runtime codex

Restart your AI tool session, then use slash commands in your app workspace:

/vc-app create
/vc-app connect
/vc-app generate
/vc-app add-module orders

See full command reference in cli/vc-app-skill/README.md.

Contribute to This Monorepo

# Clone the repository
git clone https://github.com/VirtoCommerce/vc-shell.git
cd vc-shell

# Install dependencies (also sets up Husky git hooks)
yarn install

# Build all packages
yarn build

Development

Common Commands

Build

yarn build                          # Build all publishable packages
yarn build:framework                # Build only @vc-shell/framework (hidden source maps)
yarn build:framework:debug          # Build framework with full source maps (browser auto-loads)
yarn build:analyze                  # Build with bundle analyzer
yarn build:cli:config               # Build @vc-shell/config-generator
yarn build:cli:api-client           # Build @vc-shell/api-client-generator
yarn build:cli:create-vc-app        # Build @vc-shell/create-vc-app

Development

yarn dev:storybook                  # Storybook dev server at :6006

Test

yarn test                           # Run tests (single run, CI-friendly)
yarn test:watch                     # Run tests in watch mode (interactive)
yarn test:unit                      # Run unit tests against framework/vitest.config
yarn test:coverage                  # Tests with coverage report
yarn test:storybook                 # Run Storybook interaction tests
yarn test:snapshot:update           # Update Storybook snapshots

Lint, Format & Type Check

yarn lint                           # ESLint with --fix (dev)
yarn lint:check                     # ESLint verification (CI)
yarn format                         # Prettier --write (dev)
yarn format:check                   # Prettier verification (CI)
yarn stylelint                      # Stylelint --fix (dev)
yarn stylelint:check                # Stylelint verification (CI)
yarn typecheck                      # Framework type check
yarn check                          # Umbrella: all verifications (lint + format + stylelint + typecheck + locales + circular + layers)

Code Quality

yarn check:locales                  # Validate locale files
yarn check:circular                 # Detect circular dependencies (madge)
yarn check:layers                   # Enforce layer dependency direction

API Client Generation

Generate TypeScript API clients from VirtoCommerce Platform modules:

yarn generate:api-client

Release

See RELEASING.md for the release process.

yarn release:dry                    # Dry run (preview changes)

Utilities

yarn clean                          # Remove all node_modules + dist directories
yarn changed                        # List commits since last release tag
yarn diff                           # Diff stats since last release tag

Testing PR Previews

Every push to a PR in this repository automatically publishes preview versions of all managed packages to npm with a pr-<N> dist-tag. The preview workflow comments on the PR with install instructions.

Install a PR preview in a consuming project:

npm install @vc-shell/framework@pr-<N>

See CONTRIBUTING.md — Testing PR Previews for details, including the fork-PR caveat and exact-commit install pattern.

Local Development via `portal:` Protocol

This repository supports one local-linking approach: Yarn portal:.

If your app lives outside this monorepo and you want to debug against a local build of @vc-shell/framework without moving the app.

Quick setup — drop your app into apps/<name>/ (this directory is gitignored and not a Yarn workspace) and run:

yarn setup:apps

The script rewrites every @vc-shell/* dependency in the app's package.json to a portal: path pointing at the matching package in this repository, enables preserveSymlinks in app tsconfig and Vite config, stores a rollback snapshot at .vc-shell/setup-apps-backup.json, and runs yarn install inside the app directory. After setup, start the app from its own directory (cd apps/<name> && yarn dev).

To rollback app coupling and restore original files:

yarn unsetup:apps

Manual setup (same flow in full detail):

Build framework locally in the vc-shell clone:
```
yarn build:framework
```
The portal: protocol symlinks to the package directory — it does not build on demand. Re-run yarn build:framework after each framework change (no watch mode yet).

Replace the @vc-shell/* entries in your app's package.json with absolute portal: paths to the corresponding packages in this repository:

{
  "dependencies": {
    "@vc-shell/framework": "portal:/absolute/path/to/vc-shell/framework",
    "@vc-shell/config-generator": "portal:/absolute/path/to/vc-shell/configs/vite-config",
    "@vc-shell/api-client-generator": "portal:/absolute/path/to/vc-shell/cli/api-client"
  }
}

Include every @vc-shell/* package the app actually imports — portal entries are not auto-discovered like workspace deps.

Enable preserveSymlinks on the app side so the app's bundler and TypeScript follow the portal symlink back to the real package on disk. Skipping this creates two copies of Vue (one through the symlink, one through the app's own node_modules), breaking reactivity with warnings like "Vue has already been registered".

If you used yarn setup:apps, this step is applied automatically.

In the app's tsconfig.json:
```
{
  "compilerOptions": {
    "preserveSymlinks": true
  }
}
```
In the app's Vite config:
```
export default defineConfig({
  resolve: {
    preserveSymlinks: true,
  },
});
```
Match peer-dependency versions. The portal-linked framework brings its own node_modules/; if the app has a different vue or vue-router version, you still end up with dual instances. Verify with:
```
# Inside the app
yarn why vue
# Inside the vc-shell clone
yarn why vue
```
Both commands should report the same version. If they diverge, bump the app's package.json to match the vc-shell framework peer range.

Install and run the app as usual:

yarn install
yarn dev   # or whatever the app's dev script is called

Troubleshooting

"Vue has already been registered" / lost reactivity — preserveSymlinks is not enabled on either Vite or TypeScript. Check both configs.
Changes in framework/ not reflected in the app — portal: doesn't trigger rebuilds. Run yarn build:framework in the vc-shell clone after edits, then restart the app's dev server (Vite HMR may not pick up changes to symlinked dist/).
Type errors after rebuild — stale .tsbuildinfo or dist/ remnants. Clean vc-shell with yarn clean (and rebuild) before retrying.
Yarn refuses to install with lockfile conflicts — the app's yarn.lock may reference npm-registry versions of @vc-shell/*. Delete the app's yarn.lock and re-run yarn install so Yarn re-resolves through portal entries.

Debugging Framework Source Maps

The framework build always generates .map files so source maps are available when you need them:

Build command	Source maps	Browser auto-loads?
`yarn build:framework`	Hidden (`.map` files generated, no `sourceMappingURL` in bundle)	No
`yarn build:framework:debug`	Full (`.map` files + `sourceMappingURL` comment)	Yes

For local debugging, use yarn build:framework:debug — Chrome DevTools will automatically load source maps and show original TypeScript/Vue sources.

For production builds, .map files are still generated (hidden mode) but not referenced from the bundle. To use them, open Chrome DevTools → Sources tab, right-click the JS file → "Add source map...", and point to the .map file.

Contributing

See CONTRIBUTING.md for development setup, workflow, and PR requirements.

Architecture

vc-shell follows a blade-first modular architecture:

Blade Navigation — stacked panel UX with context-aware navigation and blade-to-blade messaging
Module Runtime — modules are Vue plugins that register blades, locales, and notification contracts
Extension Points — cross-module composition via named slots and registration APIs

For implementation details, patterns, and code examples, see:

ARCHITECTURE.md

Component Library

The framework follows Atomic Design methodology:

Atoms (base building blocks)

VcBadge VcBanner VcButton VcCard VcContainer VcHint VcIcon VcImage VcLabel VcLink VcLoading VcProgress VcSkeleton VcStatus VcTooltip and more

Molecules (composite form elements)

VcInput VcSelect VcDatePicker VcEditor VcFileUpload VcCheckbox VcRadioGroup VcSwitch VcSlider VcAccordion VcDropdown VcPagination VcTextarea VcMultivalue VcColorInput VcInputCurrency and more

Organisms (complex UI blocks)

VcBlade VcDataTable VcGallery VcImageUpload VcPopup VcSidebar VcApp VcAuthLayout VcDynamicProperty

Live Demo

Explore all components interactively: Storybook

Documentation

Resource	Description
Storybook	Interactive component explorer
ARCHITECTURE.md	Architecture guide and patterns
create-vc-app README	Scaffolder usage and flags
vc-app-skill README	AI skill commands for app/module generation
WHATS_NEW.md	v2.0.0 feature highlights
MIGRATION_GUIDE.md	Migration from v1 to v2
RELEASING.md	Release process documentation
CHANGELOG.md	Full changelog

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

vc-shell

Overview

Table of Contents

Key Features

Tech Stack

Monorepo Structure

Getting Started

Prerequisites

Create a New App

Option A: CLI Scaffolder (`@vc-shell/create-vc-app`)

Option B: AI Skill (`@vc-shell/vc-app-skill`) for Claude Code and Codex

Contribute to This Monorepo

Development

Common Commands

Build

Development

Test

Lint, Format & Type Check

Code Quality

API Client Generation

Release

Utilities

Testing PR Previews

Local Development via `portal:` Protocol

Troubleshooting

Debugging Framework Source Maps

Contributing

Architecture

Component Library

Atoms (base building blocks)

Molecules (composite form elements)

Organisms (complex UI blocks)

Live Demo

Documentation

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

vc-shell

Overview

Table of Contents

Key Features

Tech Stack

Monorepo Structure

Getting Started

Prerequisites

Create a New App

Option A: CLI Scaffolder (@vc-shell/create-vc-app)

Option B: AI Skill (@vc-shell/vc-app-skill) for Claude Code and Codex

Contribute to This Monorepo

Development

Common Commands

Build

Development

Test

Lint, Format & Type Check

Code Quality

API Client Generation

Release

Utilities

Testing PR Previews

Local Development via portal: Protocol

Troubleshooting

Debugging Framework Source Maps

Contributing

Architecture

Component Library

Atoms (base building blocks)

Molecules (composite form elements)

Organisms (complex UI blocks)

Live Demo

Documentation

License

Option A: CLI Scaffolder (`@vc-shell/create-vc-app`)

Option B: AI Skill (`@vc-shell/vc-app-skill`) for Claude Code and Codex

Local Development via `portal:` Protocol