PKM

Effort — Vuexy Next.js Frontend Customisation

6 min read

Vuexy Next.js Frontend Customisation

Status: 🟡 In progress — research done, customisation not started
Started: 2026-05-12
Goal: Use Vuexy Next.js 15 as the base template and customise it into the app frontend using Claude Code to navigate and modify the codebase

Template details

  • Product: Vuexy by PixInvent (sold on ThemeForest)
  • Stack: Next.js 15 (App Router + SSR), Material UI v5, Tailwind CSS
  • Includes: 10 pre-built apps (Email, Chat, Calendar, Kanban…), 6 layout options
  • Version note: Use the new App Directory Routing version — Pages Router version is deprecated
  • License note: Each end product / client requires its own license

Plan

  1. Get Vuexy Next.js package set up locally
  2. Point Claude Code at the vuexy-next.js/ directory
  3. Walk Claude Code through the template structure
  4. Provide app requirements → let Claude Code modify components, routes, and styles

Progress log

2026-05-12 (morning)

  • Confirmed Vuexy Next.js 15 version exists with App Router + MUI v5 + Tailwind ✅
  • Started conversation with Claude to plan approach — cut off before specifying app details
  • Claude asked: where is the project located? what app are you building? what’s the tech stack?

2026-05-12 (afternoon)

  • Answered Claude’s questions: local machine, SaaS / Dashboard, all phases ✅
  • Received 4-phase Claude Code prompt (ready to paste into claude):
    • Phase 1 — Audit & Map: scan entire project, list routes, config files, mock data locations
    • Phase 2 — Branding: replace Vuexy/PixInvent branding, update colors (#2563EB primary)
    • Phase 3 — Clean demo: remove eCommerce/gaming/crypto pages; keep Auth, Dashboard, Users, Settings
    • Phase 4 — SaaS foundation: /dashboard, /users, /settings, /auth/login, /auth/register
  • Made monorepo decision: single repo with frontend/, backend/, docker-compose.yml ✅
    • Backend: Django + Ninja (REST API)
    • DB: SQLite for dev, Postgres for prod (switched in settings.py via DEBUG flag)
  • Discussed CLAUDE.md for the project root to give Claude Code permanent context

Monorepo structure (decided)

my-app/
├── frontend/          # Next.js (Vuexy-based)
├── backend/           # Django + Ninja
├── docker-compose.yml
├── .env.example
├── CLAUDE.md
└── README.md

Open tasks

  • Set up monorepo folder structure locally
  • Download / set up Vuexy Next.js package into frontend/
  • Create CLAUDE.md at repo root with stack, dev commands, git flow
  • Run Phase 1 audit in Claude Code (paste the prompt from the conversation)
  • Review Phase 1 output then continue with Phases 2-4

Reference

2026-05-12 (evening)

Codebase documentation strategy finalised — comprehensive prompt written for Claude Code to produce 12 documentation files under claude-docs/ in the Vuexy source directory. Purpose: create a persistent context map Claude can always refer to.

claude-docs/ file inventory

FileContents
CODEBASE_MAP.mdFull directory tree, tech stack, routing strategy
COMPONENTS.mdEvery component: location, props, variants, usage example
LAYOUTS.mdAll layout variants, slots, when to use each
PAGES_AND_APPS.mdEvery pre-built page/app: route, data needs, how to adapt
DATA_AND_CHARTS.mdFetch patterns, mock data locations, chart components
AUTH_AND_ACL.mdJWT/Auth Guard/session flow, role definitions, ACL patterns
THEMING_AND_STYLING.mdMUI theme, Tailwind config, dark mode, design tokens
FORMS_AND_VALIDATION.mdForm library, validation patterns, reusable form components
STATE_MANAGEMENT.mdRedux/Zustand/Context usage, store structure
HOOKS_AND_UTILS.mdEvery custom hook and utility with usage examples
TYPESCRIPT_TYPES.mdCore types/interfaces and where they are used
SKILL.mdCrown jewel — dense context anchor Claude loads before every task

SKILL.md structure

  • Codebase identity (one paragraph)
  • Golden rules (10–15 must-follow conventions)
  • Component quick-reference table (Name / Location / Use When)
  • Layout quick-reference table
  • Pattern cheatsheet (add page, add protected route, add chart, add form, etc.)
  • Compact directory map
  • Anti-patterns

How to use

# 1. Open Claude Code in the Vuexy source directory
cd ~/projects/vuexy-next.js
claude
 
# 2. Paste the Phase 1 documentation prompt
# (saved from "Next.js template framework contents" chat — 2026-05-12)
 
# 3. Let it run — writes all 12 files to claude-docs/
 
# 4. Every future build task starts with:
# "Read claude-docs/SKILL.md first, then..."
  • Paste Phase 1 documentation prompt into Claude Code (Vuexy dir)
  • Review SKILL.md output — verify Golden Rules are accurate
  • Add claude-docs/ to .gitignore or commit as part of the repo

2026-05-13

Codebase scan & SKILL.md approach confirmed — second comprehensive Claude Code prompt written: reads all claude-docs/ files + spot-checks real source, then writes a final SKILL.md with 21 structured sections.

Key additions today:

  • Confirmed SKILL.md must contain: Absolute Rules, Directory Map, Task Playbook, Anti-Patterns, Quick-Start Checklist, File Finder (21 sections total)
  • Monorepo structure reconfirmed: frontend/ + backend/ + docker-compose.yml + CLAUDE.md
  • CI/CD + Docker dev environment fully designed (self-hosted runner, blue-green deploy) → see reference/docker-dev-environment and reference/cicd-django-nextjs

Open tasks updated:

  • Set up monorepo folder locally
  • Download Vuexy Next.js into frontend/
  • Create CLAUDE.md at repo root
  • Run Phase 1 codebase scan in Claude Code
  • Run Phase 2 SKILL.md generation
  • Verify SKILL.md Golden Rules against real source files
  • Set up self-hosted GitHub Actions runner on local server

2026-05-15

Multi-agent team prompt architected for User Management phases 4–6.

  • Phases 1–3 (T001–T067) complete. Remaining scope: Phase 4 (T068–T088, Roles & Permissions), Phase 5 (T089–T112, Deactivate Users), Phase 6 (T113–T125, Polish & Security).
  • Created Lead spawn prompt with three permanent agents: django-agent (TDD backend), nextjs-agent (strict TypeScript frontend, waits on API contract), qa-agent (phase gate enforcer).
  • API-First rule enforced via progress.md — django-agent posts contract, nextjs-agent begins. Never reversed.
  • Phase gate: all tasks + qa-agent PASS → git commit “phase N complete: “.
  • Three-layer CLAUDE.md files generated: root (shared contract), backend/CLAUDE.md (Django expertise), frontend/CLAUDE.md (NextJS + Vuexy path reference).
  • → See reference/claude-code-multiagent-team for the reusable prompt template.

Open tasks updated:

  • Confirm progress.md reflects T001–T067 as complete before running Lead
  • Paste Lead prompt into Claude Code to kick off Phase 4
  • Monitor phase gate — re-engage if qa-agent posts FAIL
  • Set up monorepo folder structure locally
  • Download Vuexy Next.js into frontend/
  • Create CLAUDE.md at repo root (template ready from 2026-05-15 session)

2026-05-18

Design system clarity and Speckit workflow refined.

Conversation re: NotebookLM vs Claude for the learning-to-implementation pipeline surfaced key clarity on the stack and workflow.

Design system confirmed:

  • Vuexy Next.js = MUI v5 + Tailwind CSS (not Shadcn, not Ant Design)
  • The design system IS MUI — study MUI component names when prompting Claude for UI output
  • Prompt format: use specific MUI component names (e.g. DataGrid, Autocomplete) for better results

Speckit workflow clarified:

  • Feed one epic at a time — never vague feature names
  • Pre-generate a full epic spec in Claude first → then feed to Speckit
  • Speckit generates stories; quality depends on the context you provide
  • The long Claude-generated spec is for Claude to write and you to review — not manual work

Pain points acknowledged:

  1. Getting LLMs to produce best-practice requirements
  2. UX/UI output — functional but visually weak (MUI-specific prompting helps)

Open tasks added:

  • Try MUI-specific prompting format for next UI task (use component names in prompt)
  • Create one full epic spec in Claude as a template for Speckit workflow

Graph View