JeecgBoot/jeecgboot-vue3/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

JeecgBoot Vue3 frontend — an enterprise low-code platform built with Vue 3 + Vite 6 + Ant Design Vue 4 + TypeScript. Uses pnpm as package manager. Node 18 or 20+ required (engines: "^18 || >=20").

Common Commands

pnpm dev              # Start dev server (port 3100, mock enabled)
pnpm build            # Production build (output: dist/)
pnpm build:docker     # Docker production build
pnpm build:dockercloud # Docker cloud production build
pnpm build:report     # Build with bundle visualizer
pnpm preview          # Build + preview

# Linting (no unified "lint" script — run individually)
npx eslint src/path/to/file.vue          # Lint specific file
npx stylelint "src/**/*.{vue,less,css}"  # Stylelint
pnpm batch:prettier                       # Format all src files

# Testing (Jest configured but not integrated into npm scripts)
# Tests exist in tests/ directory but no test script in package.json
# Run manually if needed: npx jest

pnpm clean:cache      # Clear Vite cache
pnpm gen:icon         # Regenerate icon data
pnpm reinstall        # Clean reinstall all dependencies

Path Aliases

• /@/ and @/ → src/
• /#/ and #/ → types/
• ~icons/{collection}/{name} → unplugin-icons (compile-time icon imports)

The /@/ prefix (with leading slash) is the project's conventional alias — prefer it for consistency.

Architecture

Bootstrap Sequence (src/main.ts)

createApp → createRouter → setupStore (pinia) → setupProps → i18n → initAppConfigStore → registerPackages (@jeecg/online) → registerGlobComp (core Ant Design components) → SSO login → registerSuper (dynamic module discovery) → setupRouter → guards → directives → error handler → registerThirdComp (vxe-table, emoji, dayjs) → setupElectron → router.isReady() → mount

Routing & Permissions

• Permission mode: BACK — routes and menus are fetched from the backend API via getBackMenuAndPerms()
• Dynamic routes added at runtime in src/store/modules/permission.ts
• Static routes: login, oauth2-login, token-login, error pages, AI dashboard
• Router mode: HTML5 history (hash mode when running in Electron)
• Super modules discovered dynamically via import.meta.glob('./**/register.ts') in src/views/super/registerSuper.ts

State Management (Pinia)

Key stores in src/store/modules/:

• user.ts (app-user) — auth token, user info, roles, tenant, dict items
• permission.ts (app-permission) — dynamic routes, permission codes, backend menus
• app.ts (app) — project config, theme, layout settings
• locale.ts (app-locale) — i18n locale
• multipleTab.ts (app-multiple-tab) — tab state

Auth persisted in localStorage via src/utils/auth/index.ts.

API Layer

• Custom Axios wrapper: src/utils/http/axios/ — configured instance exported as defHttp
• All requests signed with MD5 via signMd5Utils
• Tenant ID injected as header when VITE_GLOB_TENANT_MODE is enabled
• Response format: { code, result, message, success } where code === 200 is success

Component Registration

• Auto-import: unplugin-vue-components with AntDesignVueResolver auto-imports all Ant Design Vue components (no manual import needed in templates)
• Global manual: registerGlobComp.ts registers Icon, AIcon, JUploadButton, Button, TinyMCE Editor
• Third-party: registerThirdComp.ts registers vxe-table (full import), custom vxe cell components, emoji picker, dayjs plugins
• Async loading: Heavy components use src/utils/factory/createAsyncComponent.tsx

Icon System

Three icon approaches:

1. Iconify runtime — <Icon icon="mdi:home" /> via @iconify/iconify CDN lazy-load
2. SVG sprites — <Icon icon="icon-name|svg" /> via vite-plugin-svg-icons
3. unplugin-icons — import IconName from '~icons/collection/name' for compile-time tree-shaken icons

Theme System

• Less variables generated by build/generate/generateModifyVars.ts
• Dark mode via Ant Design Vue theme.darkAlgorithm
• CSS variable --j-global-primary-color set dynamically from theme color
• CSS class prefix: jeecg (defined in src/settings/designSetting.ts)

External Packages

• @jeecg/online and @jeecg/aiflow are external monorepo packages excluded from Vite optimizeDeps (CJS compatibility issues)
• Registered via registerPackages(app) in main.ts

Performance Optimization Patterns

Critical: Use dynamic imports for non-critical modules

• Static import at top of file causes the entire dependency chain to load on initial page
• Use await import('module') or import('path/to/module').then() for lazy loading
• Key files using dynamic imports:
  • src/settings/registerThirdComp.ts — vxe-table, emoji picker (loaded after mount)
  • src/views/super/registerSuper.ts — dynamic module discovery
  • Non-critical Ant Design Vue components loaded asynchronously

Vite optimizeDeps

• Pre-bundled dependencies in vite.config.ts include: dayjs, axios, pinia, nprogress, qs, crypto-js, md5, sortablejs, xe-utils, vue-i18n, lodash-es, xss, mockjs
• External packages (@jeecg/*) excluded due to CJS issues

Micro-Frontend (Qiankun)

• Can run as master (hosting sub-apps) or child (embedded in parent)
• Config in src/qiankun/, sub-apps via VITE_APP_SUB_* env vars
• Child mode activated when VITE_GLOB_QIANKUN_MICRO_APP_NAME is set

Electron Support

• src/electron/ — uses hash router mode
• Platform detected via VITE_GLOB_RUN_PLATFORM === 'electron'

Key Configuration

Environment Variables

• .env — base config (port 3100, app title, SSO/qiankun flags)
• .env.development — mock enabled, proxy to localhost:8080/jeecg-boot
• .env.production — mock disabled, gzip compression
• .env.docker — Docker production build config
• .env.dockercloud — Docker cloud production build config
• .env.prod_electron — Electron production build config
• VITE_GLOB_* vars are injected at runtime via dist/_app.config.js (changeable post-build)

Build

• Manual chunks: vue-vendor, antd-vue-vendor, vxe-table-vendor, emoji-mart-vue-fast, china-area-data-vendor
• Post-build: build/script/postBuild.ts generates runtime config; copyChat.ts copies chat assets
• Console/debugger stripped in production via esbuild

Code Style

• Prettier: 150 char width, single quotes, trailing commas (es5), 2-space indent, endOfLine: 'auto', vueIndentScriptAndStyle: true (indent inside <script>/<style>), htmlWhitespaceSensitivity: 'strict'
• ESLint: Vue3 recommended + TypeScript recommended + Prettier. any is allowed. Unused vars prefixed with _ are ignored. Note: prettier/prettier rule is 'off' — Prettier is not enforced via ESLint, run it separately
• Commits: Conventional commits enforced via commitlint. Types: feat, fix, perf, style, docs, test, refactor, build, ci, chore, revert, wip, workflow, types, release. Max header: 108 chars
• i18n: Chinese (zh-CN) and English supported. Locale files in src/locales/lang/

Important Directories

build/                    # Vite plugins, build scripts, theme generation
src/api/                  # API definitions (sys/, common/, demo/)
src/components/jeecg/     # Jeecg-specific components (JVxeTable, OnLine, etc.)
src/layouts/default/      # Main app layout (header, sider, tabs, menu)
src/settings/             # Project settings (design, components, locale, encryption)
src/utils/http/axios/     # HTTP client configuration
src/views/system/         # System management pages (user, role, menu, dict, etc.)
src/views/super/          # Dynamically-discovered extension modules
types/                    # Global TypeScript declarations