Template

Files

T

docs: add README, CONTRIBUTING, and MIT LICENCE

- Rewrite README with project overview, structure, and script reference
- Add CONTRIBUTING guide with development workflow and coding standards
- Add MIT LICENCE

2026-06-18 16:47:36 +08:00

3.6 KiB

Raw Permalink Blame History

Vue SPA Template

A production-ready Vue 3 single-page application template with TypeScript, Pinia, Vue Router, and Tailwind CSS v4.

Features

Vue 3 with Composition API and <script setup> syntax
TypeScript — strict mode, path aliases, project references
Vue Router 5 — nested routes, layout system, navigation guards
Pinia 3 — state management with example stores
Tailwind CSS v4 — utility-first CSS with @theme custom tokens
Dark mode — system-aware with manual toggle, persisted to localStorage
Authentication — mock login flow with route guards and token management
Axios — pre-configured HTTP client with auth interceptor
dayjs — date utility with duration plugin
Vitest — unit testing with jsdom and Vue Test Utils
Prettier + ESLint + oxlint — consistent code quality

Project Structure

src/
  assets/          # Static assets and global CSS
  components/      # Reusable Vue components
  layouts/         # Page layout components
  router/          # Vue Router configuration and guards
  stores/          # Pinia stores
  utils/           # Utility modules (axios, dayjs)
  views/           # Page-level components

Getting Started

Prerequisites

Node.js 20.19+ or 22.12+
pnpm 9+

Setup

pnpm install

Copy the environment file and adjust as needed:

cp .env.example .env

Development

pnpm dev

Build

pnpm build

Preview Production Build

pnpm preview

Scripts

Command	Description
`pnpm dev`	Start development server with hot reload
`pnpm build`	Type-check and build for production
`pnpm preview`	Preview the production build locally
`pnpm lint`	Run oxlint and ESLint
`pnpm format`	Format source files with Prettier
`pnpm test:unit`	Run unit tests in watch mode
`pnpm test:unit:run`	Run unit tests once
`pnpm type-check`	Run TypeScript type checking

Authentication

The template includes a mock authentication flow for demonstration:

The auth store manages a mock JWT token in localStorage
Protected routes use meta.requiresAuth — unauthenticated users are redirected to /login
Guest-only routes use meta.guestOnly — authenticated users are redirected to home
The axios client automatically attaches the token and redirects on 401

Replace the login() function in src/stores/auth.ts with a real API call for production use.

Theming

Dark mode uses Tailwind CSS v4's @custom-variant dark with CSS custom properties:

Colour tokens are defined in src/assets/main.css under :root and .dark
Components use semantic utilities like bg-surface, text-foreground, border-border
The useTheme() composable toggles the dark class on <html> and persists to localStorage
System preference is respected until the user makes an explicit choice

Environment Variables

See .env.example for available variables.

Variable	Default	Description
`VITE_API_BASE_URL`	`/api`	Base URL for axios requests
`VITE_APP_TITLE`	`Vue SPA Template`	Document title

Licence

MIT

3.6 KiB Raw Permalink Blame History