Ray Template

Ray Template is an open-source Vue 3 admin dashboard template for building admin dashboards, operations consoles, and internal tools, written in TypeScript/TSX with Naive UI, Vite, Pinia, and Vue Router. It ships a working admin application, shared workspace packages, interactive VitePress documentation, and a task-indexed engineering context so developers and coding agents follow the same path through the codebase.

What is Ray Template?

Ray Template is a Vue 3 admin dashboard template that takes a pnpm monorepo workspace and produces a runnable admin application plus a documentation site and exportable source distributions. The application is built with Vue 3, TypeScript/TSX, Naive UI, Vite/Rolldown, Pinia, Vue Router, Vue I18n, Axios, MSW, and Vitest, and is maintained by XiaoDaiGua-Ray on GitHub under the MIT License. Version 6 introduced the monorepo architecture with no in-place upgrade path from v5.

What makes Ray Template stand out?

• AI-collaboration context — AGENTS.md defines collaboration rules and llms.txt maps tasks to source, contracts, examples, and checks; pnpm harness context <scope> loads task context and pnpm harness verify <scope> runs scoped checks with reports saved under .harness-local/runs/.
• Four visual styles — Modern (blue accents), Naive UI (green accents, native library controls), Material (tonal surfaces, capsule buttons), and Plain (neutral, flat), each with light and dark modes driven by semantic theme tokens.
• Five navigation layouts — Side, Top, Mixed, Right, and Split, with fluid or fixed-width content, pinnable header/footer, and a menu drawer on narrow screens.
• TablePro table component — one component handling local data, remote requests, and controlled pagination, with advanced search, column settings, export, printing, automatic height, virtual scrolling, and instance hooks; 11 runnable examples are documented.
• Shared API contracts — shared TypeScript types, Valibot schemas, and generated OpenAPI 3.1 definitions, with pnpm api:check verifying contract synchronization; MSW mocks serve both development and the static hosted demo.
• Visual route editing — edit menu order, roles, visibility, and caching through a visual editor or JSON, with tree previews, import/export, JSON Schema, and registered view IDs.
• Ten shared packages — ui, admin-shell, composables, directives, icons, http, api-contracts, demo-data, routing, and utils, with boundary checks covering imports, dependency declarations, and cycles.
• Optional fullstack edition — export a standalone frontend with pnpm dist:frontend or include a NestJS, PostgreSQL, and Redis backend via pnpm dist:fullstack.

Who should use Ray Template?

• Frontend developers building internal tools: start from working admin pages (users, organization tree, tables, forms) instead of scaffolding login, routing, and permissions from scratch.
• Teams adopting AI coding agents: hand an agent the repository's AGENTS.md and task index so it locates the owning module, reuses existing components, and runs the registered verification scope.
• Developers integrating a business API: follow the backend integration guide, set VITE_API_BASE_URL and VITE_API_MOCK=false, and rely on the shared schemas and OpenAPI definitions to align mock and real responses.
• Teams needing a fullstack starting point: export the NestJS/PostgreSQL/Redis source with sessions, API permissions, audits, and rate limits already implemented.

What can you do with Ray Template?

• Admin console setup: use the built-in login, logout, session restoration, screen lock, organization tree, and role-based navigation to assemble an account management console, switching between demo, manager, and read-only accounts to inspect permission differences.
• Data-heavy list pages: build a project list with name, status, and owner filters plus remote pagination using TablePro, reusing its request-race, cancellation, and failure-recovery contracts.
• Themeable dashboards: change style and layout in the Settings panel and let custom pages inherit colors, corners, and shadows through semantic theme tokens.
• Runnable distribution: run pnpm dist:frontend to generate ray-template-frontend-<version>.tar.gz with Admin, docs, shared packages, and mocks, excluding local configuration, credentials, build output, and installed dependencies; distribution.json records version, commit, workspace state, and content digest.

How does Ray Template work?

Clone the repository, install Node.js 26.13.0 and pnpm 12.16.1 as pinned, run pnpm install --frozen-lockfile, then pnpm dev, and open http://127.0.0.1:9527/ray-template/ and click Continue with demo account — no database or business backend is required for the demo. For a fullstack run, pnpm fullstack:setup creates apps/server/.env.local, starts PostgreSQL and Redis via Docker Compose, applies migrations, and initializes the administrator.

FAQ

Is Ray Template free?

Yes. Ray Template is released under the MIT License and its source is public on GitHub. The repository is described as open source, and its live demo and documentation are hosted on GitHub Pages.

Does Ray Template work with AI coding agents?

Yes. The repository includes AGENTS.md for collaboration rules and an llms.txt task index that maps tasks to implementations, callers, contracts, and tests. Agents that can read files and run commands use pnpm harness context and pnpm harness verify the same way maintainers do.

Can I upgrade an existing v5 project to v6?

No in-place upgrade is provided. v6 introduces the monorepo architecture, and compatibility with v5 internal imports, APIs, deployment settings, and browser data is not guaranteed. Existing projects can stay on the legacy/v5 branch or the v5.2.5 tag.

Does the frontend demo need a backend?

The frontend demo requires no database or business backend because it serves data through MSW HTTP mocks. To connect a real service, configure VITE_API_BASE_URL and set VITE_API_MOCK=false; frontend permissions shape the page experience while your backend validates real sessions and API authorization.