siujamo
42e95594d2
- Rewrite README with project overview, structure, and script reference - Add CONTRIBUTING guide with development workflow and coding standards - Add MIT LICENCE
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
@themecustom 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
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.cssunder:rootand.dark - Components use semantic utilities like
bg-surface,text-foreground,border-border - The
useTheme()composable toggles thedarkclass on<html>and persists tolocalStorage - 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 |