🌐 Devkit Vue 3

📖 Presentation

A Vue 3 / Vuetify 3 / Vite / JWT stack that can be run as a standalone frontend or in a fullstack setup with another repo (ex: Node, Swift).

Designed to be cloned into downstream projects and kept up-to-date via git merge from the stack repo.

📦 Technology Overview

Subject	Informations
Architecture	Layered Architecture : everything is separated in layers, and the upper layers are abstractions of the lower ones, that's why every layer should only reference the immediate lower layer (vertical modules architecture)
Security	JWT Stateless + CASL abilities (@casl/ability, @casl/vue) - take a look at the Node stack for more information
CI	GitHub Actions
Linter	ESLint ecmaVersion 10 (2019)
Developer	Dependabot - Snyk semantic-release - commitlint - commitizen
Dependencies	npm
Deliver	Docker & Docker-compose

🎉 Features Overview

Core

• User : classic register / auth
• Organizations : create, manage members, invite, switch context (optional — controlled by backend config)
• CASL Abilities : route guards + navigation + template helpers powered by @casl/ability and @casl/vue

Examples

• Tasks : list - add - edit - delete
• Mails Subscriptions : add

📌 Prerequisites

• Git - Download & Install Git
• Node.js (22.x or 24.x) - Download & Install Node.js
  • Recommended: Use nvm for Node version management

💥 Installation

git clone https://github.com/pierreb-devkit/Vue.git && cd Vue
npm install

🏃 Running Your Application

Development

npm run dev   # or: npm start

Runs dev server with hot-reload at http://localhost:8080/

CORS Note: When connecting to the Node stack, ensure CORS is configured:

WAOS_NODE_cors_origin=['http://localhost:8080'] npm start

Production

npm run build      # Build for production
npm run preview    # Preview production build locally

Testing

npm test                  # Run tests in watch mode
npm run test:watch        # Run tests in watch mode (explicit alias)
npm run test:unit         # Run unit tests once (one-shot)
npm run test:coverage     # Generate coverage report

Tests are organized per module in src/modules/*/tests/

Code Quality

npm run lint              # Check code quality
npm run lint:fix          # Auto-fix linting issues
npm run format            # Format code with Prettier

Commits & Releases

npm run commit                                    # Commit with commitizen
npm run release -- --first-release                # First release (standard-version)
npm run release -- --release-as 1.1.1             # Release specific version
GITHUB_TOKEN=xxx npm run release:auto             # Semantic release (CI)

🔧 Configuration

Configuration is split between a global file and per-module files, then merged at build time into a single src/config/index.js.

File layout

Config files follow the module.env.kind.js naming convention.

src/config/defaults/
  development.config.js          ← infra only (app, port, api, cookie, analytics)
  production.config.js           ← production overrides (optional)
  test.config.js                 ← test overrides (optional)

src/modules/<name>/config/
  <name>.development.config.js   ← module defaults (e.g. auth.development.config.js)

Merge order (priority ascending)

Layer	Source	Example
1	Module defaults	src/modules/*/config/*.development.config.js
2	Global development defaults	src/config/defaults/development.config.js
3	Global env overrides	src/config/defaults/<env>.config.js
4	DEVKIT_VUE_* env vars	DEVKIT_VUE_app_title='my app'

Layer 3 is only applied when NODE_ENV is not development.

Merge semantics

• Objects are merged recursively — keys from higher layers override lower layers, unmentioned keys are preserved.
• Arrays are replaced entirely — a higher-priority layer defining a 2-item array replaces a 4-item array from a lower layer. Items are never merged by index.
• undefined values are skipped — they do not overwrite existing keys.

Environment variables

DEVKIT_VUE_app_title='my app'        # sets config.app.title
DEVKIT_VUE_api_port=4000             # sets config.api.port

The merged result is written to src/config/index.js via npm run generateConfig.

Downstream projects

When running a downstream project that clones this stack, set NODE_ENV to the project name and create matching config files:

src/config/defaults/
  myproject.config.js            ← global project overrides

The generator discovers files named ${NODE_ENV}.config.js in src/config/defaults/ — module config files are always loaded regardless of environment.

Migration note: if your CI workflows still reference WAOS_VUE_* environment variables, rename them to DEVKIT_VUE_*.

🐳 Docker

docker run --rm -p 8080:80 pierreb/vue

Build yourself:

docker build -t pierreb/vue . --build-arg DEVKIT_VUE_api_port=4000

With Node stack as API:

docker-compose up

🤖 AI Setup

This stack ships preconfigured instruction and prompt files for Claude Code, GitHub Copilot, and OpenAI Codex. Each tool requires its own client installation and authentication — the repository provides the configuration so it works out-of-the-box once the tool is set up.

Tool	Config
Claude Code	.claude/ — skills embedded, works on clone
GitHub Copilot	.github/copilot-instructions.md + .github/prompts/
OpenAI Codex	AGENTS.md

Claude Code — Available Skills

Skills available via /verify, /feature, /create-module, /update-stack, /naming, /pull-request — see .claude/skills/ for details.

Stack Merge Workflow

git remote add devkit-vue https://github.com/pierreb-devkit/Vue.git
git fetch devkit-vue
git merge devkit-vue/master

Caution: resolve conflicts manually to preserve downstream customizations before pushing.

Migration Guides

• Organizations & CASL — see MIGRATIONS.md for step-by-step instructions on migrating downstream projects to the ability-based auth system and optional organizations module.

✏️ Contribute

Open issues and pull requests on GitHub.

📜 History

This work is based on MEAN.js and more precisely on a fork named Riess.js. The goal is a simple, easy-to-use toolbox to start and maintain fullstack projects across multiple languages (Vue, Node, Swift ...).

📋 Licence

🔗 Links