its5oclock

A small, opinionated Vue 3 + Vite + TypeScript application and UI scaffold: internationalized, theme-aware, and built for fast development and testing.

This README documents how to install, run, test, lint, format, and contribute to the project. It also collects a few common troubleshooting tips (especially for ESLint plugin registration) discovered while maintaining the repo.

---

Table of contents

• About
• Features
• Tech stack
• Prerequisites
• Quick start
• Useful npm scripts
• Project layout
• Local development notes
• Internationalization (i18n)
• Theme (dark/light)
• Testing (unit & e2e)
• Linting & formatting
• Continuous Integration (GitHub Actions)
• Creating a production build
• Contributing

---

About

its5oclock is a compact Vue 3 application scaffolded with Vite and TypeScript. It demonstrates a clean component structure (atomic/molecular/organism/template), Tailwind CSS for styling, runtime locale loading, and a small test setup (Vitest + Playwright). Use it as a learning project, a starting template, or a lightweight app skeleton.

Features

• Vue 3 + Composition API + TypeScript
• Vite for dev server and fast builds
• Tailwind CSS for utility-first styling
• Internationalization via vue-i18n with JSON locale files under src/locales/
• Theme toggle (dark / light) with persistence via sessionStorage
• Unit tests with Vitest, E2E tests with Playwright
• ESLint flat config with TypeScript/Vue/Prettier integration
• Prettier for formatting

Tech stack

• Vue 3
• Vite
• TypeScript
• Tailwind CSS
• vue-i18n
• Vitest (unit)
• Playwright (E2E)
• ESLint + Prettier

Prerequisites

• Node.js (see engines in package.json; this repo targets modern Node — use Node 20+ or node to pick latest)
• npm (or an equivalent package manager)
• Recommended editor: VS Code + Volar (disable Vetur)

Quick start

Clone, install, run dev server:

git clone <repo-url> its5oclock
cd its5oclock
npm install
npm run dev

Open http://localhost:5173 (or the port Vite reports) to view the app.

Useful npm scripts

These are the main scripts from package.json. Run them from the repo root.

• Start dev server

npm run dev

• Build for production

npm run build

• Preview a production build locally

npm run preview

• Type-check (uses vue-tsc)

npm run type-check

• Unit tests (Vitest)

npm run test:unit

• End-to-end tests (Playwright)

npm run test:e2e

• Lint (ESLint) — CI prevents warnings via --max-warnings=0

npm run test:lint

• Format check (Prettier)

npm run test:format

• Autofix lint and format issues

npm run lint:fix
npm run format:fix

Project layout (high level)

src/
  assets/           # CSS, images, etc (Tailwind entry)
  components/       # atoms, molecules, organisms, pages, templates
  i18n.ts           # vue-i18n bootstrap and runtime message loader
  main.ts           # app entry
locales/            # JSON locale files (en.json, fr.json, de.json)
.eslint.config.ts   # project ESLint flat config (this repo uses eslint.config.ts)
package.json
vite.config.ts
README.md

Local development notes

• TypeScript support for .vue files is handled by vue-tsc. Install and use Volar in VS Code for a smooth DX.
• Tailwind is already configured; if you edit Tailwind config or add classes, restart the dev server to pickup changes.

Internationalization (i18n)

• Translations are in src/locales/*.json. The runtime loader uses import.meta.glob to eagerly load locale JSON files and builds a messages object.
• Default/fallback locale is en (see src/i18n.ts).

Theme (dark/light)

• The theme toggle is implemented in the navigation bar and persists a color-mode key in sessionStorage.
• On first visit the app respects the user's OS prefers-color-scheme.

Testing

Unit tests (Vitest)

• Run npm run test:unit to run unit tests. You can pass flags documented by Vitest.

End-to-end tests (Playwright)

• Install Playwright browsers once locally (required to run E2E):

npx playwright install

• On CI, make sure the project is built before running Playwright tests (the CI workflow included in this project runs npm run build before E2E where needed).

• Run E2E tests:

npm run test:e2e

Linting & formatting

• Lint:

npm run test:lint

This repo's test:lint script runs eslint . --max-warnings=0 and will fail if any warnings or errors are present (useful for CI).

• Format check:

npm run test:format

• Autofix:

npm run lint:fix
npm run format:fix

Continuous Integration (GitHub Actions)

• The repo includes .github/workflows/ci.yml which checks out the code, installs dependencies, runs unit tests, lint and format checks. The workflow uses actions/setup-node with node-version: 'node' so it uses the latest stable Node runtime.

Creating a production build

1. Commit your changes: Make sure all desired changes are committed to your main branch.
2. Create a tag locally: In your terminal, run: git tag v1.0.0 (Replace v1.0.0 with your desired version.)
3. Push the tag to GitHub: Run: git push origin v1.0.0
4. Draft a new release on GitHub:
   • Go to your repository on GitHub.
   • Click Releases in the sidebar.
   • Click Draft a new release.
   • Select the tag you just pushed.
   • Add a title and description.
   • Click Publish release.
5. Workflow runs automatically: Your GitHub Actions workflow (.github/workflows/deploy-on-release.yml) will trigger, build your project, and deploy the latest build to the gh-pages branch.

Contributing

• Please open issues or PRs against main.
• Run the linters, formatters and type-checker before submitting:

npm run lint:fix
npm run format:fix
npm run type-check