Skip to content

Commit 2b8b857

Browse files
suradet-pssuradet-ps
committed
docs: update README.md
1 parent 9ead41f commit 2b8b857

1 file changed

Lines changed: 179 additions & 72 deletions

File tree

‎README.md‎

Lines changed: 179 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -2,36 +2,66 @@
22

33
![CI Quality](https://github.com/pharmacist-sabot/vue-starter/actions/workflows/ci.yml/badge.svg)
44
[![Vue](https://img.shields.io/badge/Vue-3.5+-4FC08D?logo=vue.js)](https://vuejs.org/)
5-
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?logo=typescript)](https://www.typescriptlang.org/)
6-
[![Vite](https://img.shields.io/badge/Vite-6.0+-646CFF?logo=vite)](https://vitejs.dev/)
5+
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-3178C6?logo=typescript)](https://www.typescriptlang.org/)
6+
[![Vite](https://img.shields.io/badge/Vite-7.0+-646CFF?logo=vite)](https://vitejs.dev/)
7+
[![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-4.1+-06B6D4?logo=tailwindcss)](https://tailwindcss.com/)
8+
[![Vitest](https://img.shields.io/badge/Vitest-4.0+-6E9F18?logo=vitest)](https://vitest.dev/)
9+
[![pnpm](https://img.shields.io/badge/pnpm-10.17+-F69220?logo=pnpm)](https://pnpm.io/)
710

811
An opinionated, production-ready starter template for Vue 3 applications. Designed for scalability, code quality, and developer experience.
912

10-
## Features
13+
## ✨ Features
1114

12-
- **Framework:** Vue 3 (Script Setup) + TypeScript + Vite
13-
- **State Management:** Pinia (Store)
14-
- **Routing:** Vue Router (History mode)
15-
- **Linter & Formatter:** ESLint (AntFu Config) - No Prettier required.
16-
- **Git Hooks:** Husky + Lint-staged (Auto-fix on commit).
17-
- **Commit Convention:** Commitlint (Conventional Commits).
18-
- **Security:** Audit-CI (Vulnerability check) & Strict TypeScript settings.
19-
- **CI/CD:** GitHub Actions workflow ready.
20-
- **Utils:** VueUse included.
15+
### Core Stack
2116

22-
## Prerequisites
17+
- **Vue 3.5+** – Composition API with `<script setup>` syntax
18+
- **TypeScript 5.9+** – Strict mode enabled with enhanced type safety
19+
- **Vite 7** – Lightning-fast dev server and optimized builds
20+
- **Tailwind CSS 4.1** – Utility-first CSS via Vite plugin
2321

24-
- **Node.js:** version 22+ (LTS recommended)
25-
- **Package Manager:** PNPM (defined via `packageManager` in package.json)
22+
### State & Routing
2623

27-
## Getting Started
24+
- **Pinia 3** – Type-safe state management
25+
- **Vue Router 4** – File-based routing with history mode
26+
27+
### Code Quality
28+
29+
- **ESLint** – [Anthony Fu's config](https://github.com/antfu/eslint-config) (includes formatting, no Prettier needed)
30+
- **Husky** – Git hooks for pre-commit and commit-msg
31+
- **lint-staged** – Run linters on staged files only
32+
- **Commitlint** – Enforce [Conventional Commits](https://www.conventionalcommits.org/)
33+
34+
### Testing
35+
36+
- **Vitest** – Fast unit testing with Vue Test Utils
37+
- **Coverage** – V8 coverage reports
38+
39+
### Security & CI/CD
40+
41+
- **audit-ci** – Block builds on high-severity vulnerabilities
42+
- **GitHub Actions** – Automated quality gates on every PR
43+
44+
### Utilities
45+
46+
- **VueUse** – Collection of essential Vue Composition Utilities
47+
- **Path Aliases** – `@/` alias pre-configured
48+
49+
## 📋 Prerequisites
50+
51+
| Requirement | Version |
52+
| --------------- | ----------- |
53+
| Node.js | 22+ (LTS) |
54+
| Package Manager | pnpm 10.17+ |
55+
56+
> **Note:** pnpm version is enforced via `packageManager` field in `package.json`.
57+
58+
## 🚀 Getting Started
2859

2960
### 1. Clone the repository
3061

3162
```bash
32-
# Use this template to start a new project
33-
git clone https://github.com/pharmacist-sabot/vue-starter.git my-new-project
34-
cd my-new-project
63+
git clone https://github.com/pharmacist-sabot/vue-starter.git my-project
64+
cd my-project
3565
```
3666

3767
### 2. Install dependencies
@@ -40,79 +70,156 @@ cd my-new-project
4070
pnpm install
4171
```
4272

43-
### 3. Setup Environment
44-
45-
Copy the example environment file (if applicable in the future).
73+
### 3. Start development server
4674

4775
```bash
48-
cp .env.example .env
76+
pnpm dev
4977
```
5078

51-
### 4. Run Development Server
79+
The app will be available at `http://localhost:5173/`
80+
81+
## 📜 Available Scripts
82+
83+
| Script | Description |
84+
| -------------------- | --------------------------------------- |
85+
| `pnpm dev` | Start dev server with HMR |
86+
| `pnpm build` | Type-check and build for production |
87+
| `pnpm preview` | Preview production build locally |
88+
| `pnpm lint` | Check linting and formatting |
89+
| `pnpm lint:fix` | Auto-fix linting and formatting issues |
90+
| `pnpm type-check` | Run TypeScript compiler (no emit) |
91+
| `pnpm test:unit` | Run unit tests in watch mode |
92+
| `pnpm test:coverage` | Run tests with coverage report |
93+
| `pnpm audit` | Check for high-severity vulnerabilities |
94+
95+
## 📁 Project Structure
5296

53-
```bash
54-
pnpm dev
5597
```
98+
├── .github/
99+
│ └── workflows/
100+
│ └── ci.yml # GitHub Actions CI workflow
101+
├── .husky/
102+
│ ├── commit-msg # Commitlint hook
103+
│ └── pre-commit # Lint-staged hook
104+
├── src/
105+
│ ├── assets/ # Static assets (images, fonts, CSS)
106+
│ ├── components/
107+
│ │ └── common/ # Shared UI components
108+
│ │ ├── AppHeader.vue
109+
│ │ └── BaseButton.vue
110+
│ ├── composables/ # Vue composables (hooks)
111+
│ │ └── use-toggle.ts
112+
│ ├── layouts/ # Page layouts
113+
│ │ ├── BlankLayout.vue
114+
│ │ └── DefaultLayout.vue
115+
│ ├── router/ # Vue Router config
116+
│ │ └── index.ts
117+
│ ├── stores/ # Pinia stores
118+
│ │ └── counter.ts
119+
│ ├── types/ # TypeScript type definitions
120+
│ │ └── router.d.ts
121+
│ ├── utils/ # Helper functions
122+
│ │ └── formatters.ts
123+
│ ├── views/ # Page components
124+
│ │ ├── HomeView.vue
125+
│ │ └── NotFoundView.vue
126+
│ ├── App.vue # Root component
127+
│ └── main.ts # App entry point
128+
├── tests/ # Unit tests (mirrors src/ structure)
129+
│ ├── components/
130+
│ ├── composables/
131+
│ ├── stores/
132+
│ ├── utils/
133+
│ └── views/
134+
├── eslint.config.mjs # ESLint configuration
135+
├── vite.config.ts # Vite configuration
136+
├── vitest.config.ts # Vitest configuration
137+
├── tsconfig.json # TypeScript config (references)
138+
├── tsconfig.app.json # App TypeScript config
139+
└── tsconfig.node.json # Node TypeScript config
140+
```
141+
142+
## 🔧 Configuration
56143

57-
The app will be served at `http://localhost:5173/`.
58-
59-
## Available Scripts
60-
61-
| Script | Description |
62-
| :---------------- | :------------------------------------------------------------- |
63-
| `pnpm dev` | Start the development server with HMR. |
64-
| `pnpm build` | Build the application for production (includes type checking). |
65-
| `pnpm preview` | Preview the production build locally. |
66-
| `pnpm lint` | Lint and check formatting for all files. |
67-
| `pnpm lint:fix` | Auto-fix linting and formatting errors. |
68-
| `pnpm type-check` | Run TypeScript compiler check (no emit). |
69-
| `pnpm audit` | Check for high-severity security vulnerabilities. |
70-
71-
## Directory Structure
72-
73-
```text
74-
src/
75-
├── assets/ # Static assets (images, fonts, global css)
76-
├── components/ # Reusable UI components
77-
├── composables/ # Shared Vue logic (hooks)
78-
├── layouts/ # App layouts (e.g., Default, Auth)
79-
├── router/ # Routing configuration
80-
├── stores/ # Global state management (Pinia)
81-
├── types/ # TypeScript interfaces & types
82-
├── utils/ # Helper functions & constants
83-
└── views/ # Page components associated with routes
144+
### TypeScript
145+
146+
Strict mode is enabled with additional safety options:
147+
148+
```json
149+
{
150+
"strict": true,
151+
"noImplicitOverride": true,
152+
"noUncheckedIndexedAccess": true,
153+
"verbatimModuleSyntax": true
154+
}
84155
```
85156

86-
## Contribution Guidelines
157+
### ESLint
158+
159+
Using [@antfu/eslint-config](https://github.com/antfu/eslint-config) with:
160+
161+
- 2-space indentation
162+
- Single quotes
163+
- Semicolons required
164+
- Auto-sorted imports via `perfectionist`
165+
- Kebab-case or PascalCase filenames enforced
87166

88-
### Commit Message Convention
167+
### Commit Types
89168

90-
We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. Husky and Commitlint will verify your commit messages automatically.
169+
Allowed commit types (enforced by Commitlint):
170+
171+
| Type | Description |
172+
| ---------- | ----------------------------- |
173+
| `feat` | New feature |
174+
| `fix` | Bug fix |
175+
| `docs` | Documentation changes |
176+
| `style` | Code style (formatting, etc.) |
177+
| `refactor` | Code refactoring |
178+
| `perf` | Performance improvements |
179+
| `test` | Adding or updating tests |
180+
| `build` | Build system or dependencies |
181+
| `ci` | CI configuration |
182+
| `chore` | Other changes |
183+
| `revert` | Revert a previous commit |
91184

92185
**Format:** `<type>: <subject>`
93186

94187
**Examples:**
95188

96-
- `feat: add user profile page`
97-
- `fix: resolve login api error`
98-
- `chore: update dependencies`
99-
- `style: fix landing page responsive layout`
189+
```
190+
feat: add user authentication
191+
fix: resolve login validation error
192+
docs: update API documentation
193+
```
100194

101-
### Branching Strategy
195+
## 🔒 Quality Gates
102196

103-
- `main` / `master`: Production-ready code.
104-
- `feature/*`: For new features (e.g., `feature/login-screen`).
105-
- `fix/*`: For bug fixes (e.g., `fix/header-alignment`).
197+
The CI pipeline runs the following checks on every push and PR:
198+
199+
1. **Linting** – Code style must follow ESLint rules
200+
2. **Type Checking** – No TypeScript errors (`strict: true`)
201+
3. **Unit Tests** – All tests must pass
202+
4. **Build** – Production build must succeed
203+
5. **Security Audit** – No high-severity vulnerabilities
204+
205+
## 🤝 Contributing
206+
207+
### Branching Strategy
106208

107-
## Quality Gates
209+
| Branch | Purpose |
210+
| ----------- | ----------------------------------- |
211+
| `main` | Production-ready code |
212+
| `feature/*` | New features (e.g., `feature/auth`) |
213+
| `fix/*` | Bug fixes (e.g., `fix/login-error`) |
108214

109-
Before merging code, the following checks must pass (automated via GitHub Actions):
215+
### Workflow
110216

111-
1. **Linting:** Code style must follow the defined rules.
112-
2. **Type Checking:** No TypeScript errors allowed (`strict: true`).
113-
3. **Build:** The project must build successfully.
114-
4. **Audit:** No high-severity vulnerabilities.
217+
1. Create a branch from `main`
218+
2. Make your changes
219+
3. Ensure all quality gates pass locally
220+
4. Submit a pull request
221+
5. Wait for CI checks and code review
115222

116-
## License
223+
## 📄 License
117224

118-
This project is licensed under the MIT License.
225+
This project is licensed under the [MIT License](LICENSE).

0 commit comments

Comments
 (0)