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
parent 0da17ab0d7
commit 42e95594d2
3 changed files with 157 additions and 21 deletions
@@ -0,0 +1,50 @@
+# Contributing
+
+Thank you for considering contributing to this project.
+
+## Getting Started
+
+1. Fork the repository and clone it locally
+2. Install dependencies: `pnpm install`
+3. Create a branch for your changes: `git switch -c feature/my-change`
+4. Make your changes and ensure they pass checks
+
+## Development Workflow
+
+Before submitting a pull request, please verify:
+
+```sh
+pnpm type-check      # TypeScript type checking
+pnpm lint            # ESLint and oxlint
+pnpm test:unit:run   # Unit tests
+pnpm build           # Production build
+```
+
+## Coding Standards
+
+- Write all user-facing text in **British English**
+- Use the Composition API with `<script setup>` for Vue components
+- Format code with Prettier before committing: `pnpm format`
+- Follow existing patterns in the codebase for naming and structure
+
+## Commit Messages
+
+This project follows semantic commit conventions:
+
+```
+<type>(<scope>): <subject>
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+Keep the subject line under 50 characters and use imperative mood ("add" not "added").
+
+## Pull Requests
+
+- Keep changes focused — one feature or fix per pull request
+- Update or add tests when changing functionality
+- Ensure the CI pipeline passes before requesting review
+
+## Questions
+
+Open an issue for questions, bug reports, or feature requests.
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Onixbyte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -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)