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
This commit is contained in:
@@ -1,48 +1,113 @@
|
||||
# vue-template
|
||||
# Vue SPA Template
|
||||
|
||||
This template should help get you started developing with Vue 3 in Vite.
|
||||
A production-ready Vue 3 single-page application template with TypeScript, Pinia, Vue Router, and Tailwind CSS v4.
|
||||
|
||||
## Recommended IDE Setup
|
||||
## Features
|
||||
|
||||
[VS Code](https://code.visualstudio.com/) + [Vue (Official)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
|
||||
- **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
|
||||
|
||||
## Recommended Browser Setup
|
||||
## Project Structure
|
||||
|
||||
- Chromium-based browsers (Chrome, Edge, Brave, etc.):
|
||||
- [Vue.js devtools](https://chromewebstore.google.com/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
|
||||
- [Turn on Custom Object Formatter in Chrome DevTools](http://bit.ly/object-formatters)
|
||||
- Firefox:
|
||||
- [Vue.js devtools](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)
|
||||
- [Turn on Custom Object Formatter in Firefox DevTools](https://fxdx.dev/firefox-devtools-custom-object-formatters/)
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
## Type Support for `.vue` Imports in TS
|
||||
## Getting Started
|
||||
|
||||
TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) to make the TypeScript language service aware of `.vue` types.
|
||||
### Prerequisites
|
||||
|
||||
## Customize configuration
|
||||
- [Node.js](https://nodejs.org/) 20.19+ or 22.12+
|
||||
- [pnpm](https://pnpm.io/) 9+
|
||||
|
||||
See [Vite Configuration Reference](https://vite.dev/config/).
|
||||
|
||||
## Project Setup
|
||||
### Setup
|
||||
|
||||
```sh
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### Compile and Hot-Reload for Development
|
||||
Copy the environment file and adjust as needed:
|
||||
|
||||
```sh
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
### Development
|
||||
|
||||
```sh
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
### Type-Check, Compile and Minify for Production
|
||||
### Build
|
||||
|
||||
```sh
|
||||
pnpm build
|
||||
```
|
||||
|
||||
### Lint with [ESLint](https://eslint.org/)
|
||||
### Preview Production Build
|
||||
|
||||
```sh
|
||||
pnpm lint
|
||||
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](LICENCE)
|
||||
|
||||
Reference in New Issue
Block a user