This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
npm run dev # Vite dev server (PWA enabled in dev via vite-plugin-pwa)
npm run build # Production build (terser, manual vendor chunks, drops console.*)
npm run preview # Preview built bundle
npm test # Jest (ts-jest, node env) — runs ./tests
npm run typecheck # vue-tsc --noEmit (same check the PR "Tests" workflow runs)
npx jest path/to/file.test.ts # Run a single test file
JEST_TZ=Asia/Dubai npx jest src/local/__tests__/routines-api.test.ts src/local/__tests__/routines-recurrence.test.ts src/utils/__tests__/dnd.test.ts # jest pins TZ=UTC; JEST_TZ runs local-day tests in another zone
npm run format # Prettier (singleQuote, trailingComma: all, printWidth 80)
npm run test:visual # Screenshot diff of two builds, local only (not CI); usage in playwright.visual.config.mjsEnv: copy .env.example to .env. The required var is VITE_API_BASE_URL. Pusher/ntfy/Telegram vars are needed only if exercising those features.
Vue 3 SPA for the TMGR task manager. Backend is the Java/Spring app in task-manager/backend-java (prod runs only Java; Laravel is legacy). Local API: http://localhost:8080/api/. Path alias @/* → src/*.
The codebase splits languages by role — keep this convention when adding files:
- TypeScript:
src/actions/tmgr/*(API layer),src/composable/*,src/utils/*,src/types/*. - JavaScript:
src/router/*,src/store/*(Vuex),src/mixins/*, and most.vue<script>blocks. - Vue components use Options API with
defineComponent. The Composition API is used insidesetup()(never<script setup>). This is enforced project-wide.
The performance layer in src/utils/ is load-bearing — actions in src/actions/tmgr/* are expected to use it:
requestCache(src/utils/requestCache.ts) — TTL-keyed, single-flight in-memory cache. Reference data (workspaces, statuses, categories, members) is cached for 5 min; per-task data for ~1 min. Mutating actions must callrequestCache.invalidate(key | regex)or stale data will render.store.dispatch('logout')clears the cache. Wrap GETs inrequestCache.getOrFetch(key, fn, { ttl, cache }): it serves a fresh cached value, otherwise coalesces concurrent identical requests onto a single in-flight Promise (registered synchronously, so there is no miss window for duplicates), then stores the result underttl. Passcache: falseto coalesce without persisting.$axios(src/plugins/axios.ts) — single instance with 30s timeout, bearer token fromstore.state.token, one refresh-and-replay on 401 (thenlogout). 5xx errors are not retried: the caller or an explicit UI retry handles them.
src/store/index.js holds auth/session/UI flags; modules live in src/store/modules/ (pusher, boardFilters, featureToggles). Reference collections are kept normalized: workspaces + workspacesById, workspaceStatuses + workspaceStatusesById. Prefer the *ById lookups and the currentWorkspace / userSettingByKey getters over scanning arrays.
Modal state is controlled via root mutations: setCurrentTaskIdForModal, setShowCreatingTaskModal, closeTaskModal. The modal stack (modalStack, openModals) is central — don't manage modal visibility with local refs alone if it competes for ESC/backdrop handling.
colorScheme (light/dark) is mirrored to localStorage and toggles the dark class on <html> via the setColorScheme mutation.
src/router/index.js resolves the user's landing page on / for logged-in users: it fetches user → workspaces → user feature toggles → workspace feature toggles, then redirects to /{workspace.code}/{landing} where landing ∈ list | board | dashboard (gated by workspace toggles). All app URLs are workspace-scoped: /:workspace_code/....
Route meta flags drive the guard:
allowedGuests: true— public route (login, register, etc.).notOnlyForLoggedUsers: true— also accessible when authenticated.- Anything else requires auth and redirects to
Loginwhen token is missing.
src/store/modules/pusher.js+src/store/plugins/pusher.js— Pusher/Soketi channel subscriptions, paired with theusePushercomposable.src/store/plugins/ntfy-client.jsandpusher-beams-client.js— push notification transports.usePusher,useNotifications,useNetworkStatuscomposables wrap subscription lifecycles.
vite.config.ts defines manual vendor chunks: vendor-vue, vendor-editor (Editor.js + plugins), vendor-ui (Radix/Headless/Lucide), vendor-utils, vendor-markdown, vendor-pusher. When adding a heavy dependency, slot it into the appropriate chunk to avoid bloating the entry. Production strips console.log/info/debug via terser.
PWA is configured in vite.config.ts with NetworkFirst for /api/* (5min TTL, 10s network timeout). Fonts (Inter, JetBrains Mono, Quicksand, Instrument Serif) are self-hosted via @fontsource/* and excluded from the precache via globIgnores. The service worker imports only clear-private-api-cache.js (importScripts in pwa/pwaWorkbox.ts); the Pusher Beams SW is no longer loaded.
- Don't use
<script setup>— the project standardizes ondefineComponent({ setup() { ... } })for Composition API and Options API otherwise. - Don't rename existing methods/fields or do drive-by refactors — the
.cursorrulescalls this out explicitly; respect existing names even if they look improvable. - Don't write comments unless the why is genuinely non-obvious.
- Dark mode: every visual change needs the
dark:variant. - shadcn-vue components live in
src/components/ui/; brand colorstmgr-blue,tmgr-light-blue,tmgr-grayare defined intailwind.config.js. - Workspace context must be in URLs and API calls — pull
currentWorkspace.codefrom the store rather than hardcoding. - The full style guide (
.cursorrules) has extensive examples for Options API, Vuex modules, composables, and shadcn usage; consult it for boilerplate but treat the points above as the binding constraints.
- UI text goes through vue-i18n keys only:
$t('area.key')in templates,t()from@/i18nin code. New copy is written in English insrc/locales/en/<area>.json; other languages are translated from it. Rules, message syntax and plural forms:docs/i18n/README.md, terms:docs/i18n/glossary.md. npm testrunssrc/i18n/__tests__/catalogs.test.ts: every message compiles, placeholders and plural forms match English, every literal key used insrcexists. A missing translation is not an error (falls back to English).- Status and category names stored in the database stay English; translate by status type in the UI.
- A desktop release is the tag
desktop-vX.Y.Z; the version must matchsrc-tauri/tauri.conf.json,src-tauri/Cargo.tomland thetmgrentry insrc-tauri/Cargo.lock. - Every desktop release needs a changelog. Before pushing the tag, add a
## X.Y.Z — YYYY-MM-DDsection tosrc-tauri/CHANGELOG.md(newest on top): short user-facing bullets — what changed for the user, notable fixes, PR numbers only where useful. The release workflow puts that section into the GitHub release and the in-app update notes (latest.json) and fails if the section is missing. - Other sessions release too: check
git tagfor the next free version before bumping.
This project tracks project-boilerplate-monorepo via .boilerplate.json.
A commit that touches a generic path (see .boilerplate.json) is a
candidate to upstream — run the upstreaming-to-boilerplate skill or
/upstream on it.