Skip to content

Commit ec2c87d

Browse files
bartstcbartstc
committed
chore: update README.md
1 parent 99396ff commit ec2c87d

1 file changed

Lines changed: 78 additions & 107 deletions

File tree

‎README.md‎

Lines changed: 78 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -1,148 +1,119 @@
1-
# What is SPA Vite Template
1+
# SPA Vite Template
22

3-
This project provides a basic dev setup intended for `Single Page Application` (SPA) development. It contains already configured tools and libraries providing a quick and seamless start, making the Developer Experience (DX) and scalability of your project easily manageable. It also shows a practical application of selected tools and practices in a form of a demo app.
3+
An opinionated, production-ready starter for **Single Page Application** development with React. Pre-configured tooling, libraries, and a demo app so you can skip the boilerplate and focus on building.
44

5-
# Template versions
5+
## What's included
66

7-
Bearing in mind flexibility and openness to various tools and preferences, this template allows you to adjust your workflow to your needs, assuring best practices and following opinionated frontend/React trends at the same time.
7+
### Developer experience
88

9-
Thus, the template provides two different versions, differing in complexity and spectrum of solved problems.
9+
- [Vite](https://vitejs.dev/) — fast dev server and build tooling
10+
- [TypeScript](https://www.typescriptlang.org/) — strict type safety
11+
- [ESLint](https://eslint.org/) + [Prettier](https://prettier.io/) + [Husky](https://typicode.github.io/husky/) — consistent code style
12+
- [PNPM](https://pnpm.io/) — fast, disk-efficient package manager
13+
- [Devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) — reproducible VS Code dev environment
14+
- [GitHub Actions](https://docs.github.com/en/actions) CI — tests, build, coverage reports, deploy draft
15+
- [GitHub Copilot](https://github.com/features/copilot) — instructions, skills, and custom prompts (`.github/instructions/`, `.github/skills/`, `.github/prompts/`)
16+
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) — project rules (`CLAUDE.md`), skills, subagents, and custom commands (`.claude/`)
1017

11-
## Basic version - `basic`
18+
### Testing
1219

13-
The most basic config of the dev environment. It provides seamless DX and assures a legible and consistent codebase.
20+
- [Vitest](https://vitest.dev/) — unit and integration tests
21+
- [Storybook](https://storybook.js.org/) — component tests in a real browser
22+
- [Playwright](https://playwright.dev/) — E2E tests across Chromium, Firefox, and WebKit
1423

15-
### When to use
24+
### Libraries
1625

17-
This version is free of any libraries. If the `core` version doesn't match your preferences and expectations, the `basic` version will be perfect as a basis for your personalized project setup.
26+
- [Chakra UI](https://chakra-ui.com/) — accessible, modular component library
27+
- [React Router 7](https://reactrouter.com/home) — routing with strong path typing
28+
- [React Query](https://tanstack.com/query/v4/) — data fetching and server state synchronization
29+
- [Zustand](https://docs.pmnd.rs/zustand/getting-started/introduction) — lightweight state management
30+
- [i18next](https://www.i18next.com/) — internationalization
31+
- [XState](https://stately.ai/docs/xstate) — state orchestration (example usage)
32+
- [MSW 2](https://mswjs.io/) — API mocking for development and tests
1833

19-
### Key features
34+
### Architecture
2035

21-
- Dev environment based on [Vite](https://vitejs.dev/) toolkit.
22-
- Unit, integration, and component testing with [Vitest](https://vitest.dev/) and [Storybook](https://storybook.js.org/).
23-
- End-to-end testing with [Playwright](https://playwright.dev/).
24-
- Static code analysis: eslint, prettier, husky.
25-
- TypeScript support.
26-
- [Devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) config for VS Code.
27-
- [PNPM](https://pnpm.io/) as a package manager.
28-
- CI setup (tests, build, tests coverage report, deploy draft) with [GitHub Actions](https://docs.github.com/en/actions).
29-
- [Github Copilot](https://github.com/features/copilot) configuration (instructions).
30-
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) configuration (`CLAUDE.md` file, `.claude` directory with settings and commands, and remote development setup).
36+
- Feature slice architecture with clean architecture principles
37+
- Centralized API layer with endpoint-based organization and type consolidation
38+
- Formatting utilities for numbers, monetary values, and dates
39+
- A demo app with authentication showcasing the project structure and tooling in action (powered by [Fake Store API](https://fakestoreapi.com/docs))
3140

32-
## Extended version - `core`
41+
## Getting started
3342

34-
The extension of the `basic` version. It contains already configured tools and libraries that aim to solve the most basic and typical problems existing in a modern frontend application (SPA).
35-
36-
### When to use
37-
38-
If configured tools and overall setup meet your requirements, you should definitely choose this version as the starting point for your project.
39-
40-
### Key features
41-
42-
- Everything that's included in the `basic` version.
43-
- Simple, modular, and accessible components based on [Chakra UI](https://chakra-ui.com/).
44-
- Data fetching and external state synchronization based on [React Query](https://tanstack.com/query/v4/).
45-
- Routing based on [React Router 7](https://reactrouter.com/home) with strong path typing.
46-
- Internalization with [i18next](https://www.i18next.com/).
47-
- Formatting tools for numbers, monetary values, and dates (easily extendable with any date library like [DayJS](https://day.js.org/)).
48-
- State management with [Zustand](https://docs.pmnd.rs/zustand/getting-started/introduction).
49-
- State orchestration with [XState](https://stately.ai/docs/xstate) (just an example).
50-
- API mocking with [MSW 2](https://mswjs.io/).
51-
- Centralized API architecture with endpoint-based organization and type consolidation.
52-
- A demo app with authentication presenting project structure, good practices, and used tooling in action (with a little help of [Fake Store API](https://fakestoreapi.com/docs)).
53-
54-
# Guideline
55-
56-
## How to use
57-
58-
_You may simply download a ZIP Directory and start with a clean git repository using a command_ `git init`...
59-
60-
... or clone this repo through git CLI.
61-
62-
```
63-
git clone -b basic --depth 1 --single-branch https://github.com/bartstc/spa-vite-template.git [project_name]
64-
```
65-
66-
```
67-
git clone -b core --depth 1 --single-branch https://github.com/bartstc/spa-vite-template.git [project_name]
68-
```
69-
70-
Link cloned repo with your own remote repository.
43+
Clone the repo and set up your own remote:
7144

7245
```
73-
git remote set-url origin git@github.com:username/project.git
46+
git clone --depth 1 https://github.com/bartstc/spa-vite-template.git [project_name]
47+
cd [project_name]
48+
rm -rf .git && git init
49+
git remote add origin git@github.com:username/project.git
7450
```
7551

76-
Create and push your own branch designated for development.
52+
### Dev environment
7753

78-
```
79-
git checkout -b [branch_name]
80-
```
81-
82-
```
83-
git push --set-upstream origin [branch_name]
84-
```
85-
86-
Set your newly created and pushed branch as default. You may do this in `Settings` -> `Branches` -> `Default Branch`.
87-
88-
## Starting the dev environment
89-
90-
It's recommended to run the dev server and tests in a docker container. Containerized environment assures compatibility and cohesion regarding launching and developing your project. Because of that, you don't need to worry about unexpected errors or undesired mismatches of locally installed dependencies e. g. Node or Pnpm.
54+
It's recommended to run the dev server inside a container for consistent Node/PNPM versions. If you're using VS Code, the included [devcontainer config](https://code.visualstudio.com/docs/devcontainers/containers) handles this out of the box.
9155

92-
If you are using [VS Code](https://code.visualstudio.com/) as your IDE, I personally recommend using already configured in this template [devcontainer env](https://code.visualstudio.com/docs/devcontainers/containers).
56+
## Commands
9357

94-
Learn more about using this template in practice below.
95-
96-
## Basic commands
97-
98-
| Command | Description |
99-
| ---------------------- | --------------------------------------------------------------- |
100-
| `pnpm dev` | Runs dev server with the HMR locally on port `5173` |
101-
| `pnpm lint` | Checks for lint errors |
102-
| `pnpm build` | Builds optimized app package |
103-
| `pnpm test` | Runs all tests (unit + storybook) |
104-
| `pnpm test:unit` | Runs unit tests |
105-
| `pnpm test:storybook` | Runs storybook tests |
106-
| `pnpm test:coverage` | Runs unit + storybook tests with coverage |
107-
| `pnpm test:e2e` | Runs E2E tests with Playwright (headless) |
108-
| `pnpm test:e2e:ui` | Runs E2E tests in interactive web UI mode |
109-
| `pnpm test:e2e:headed` | Runs E2E tests with visible browser windows (requires X server) |
110-
| `pnpm test:e2e:debug` | Runs E2E tests in debug mode |
111-
| `pnpm test:e2e:report` | Opens the HTML report for E2E tests from the last test run |
112-
| `pnpm storybook` | Runs a Storybook locally on port `6006` |
58+
| Command | Description |
59+
| ---------------------- | ------------------------------------------ |
60+
| `pnpm dev` | Dev server with HMR on port `5173` |
61+
| `pnpm lint` | Check for lint errors |
62+
| `pnpm build` | Production build |
63+
| `pnpm test` | Run all tests (unit + storybook) |
64+
| `pnpm test:unit` | Unit tests only |
65+
| `pnpm test:storybook` | Storybook component tests only |
66+
| `pnpm test:coverage` | Tests with coverage report |
67+
| `pnpm test:e2e` | E2E tests (headless) |
68+
| `pnpm test:e2e:ui` | E2E in interactive web UI mode |
69+
| `pnpm test:e2e:headed` | E2E with visible browser |
70+
| `pnpm test:e2e:debug` | E2E in debug mode |
71+
| `pnpm test:e2e:report` | Open the HTML report from the last E2E run |
72+
| `pnpm storybook` | Storybook on port `6006` |
11373

11474
## Testing strategy
11575

116-
This template implements a comprehensive testing strategy covering all layers of your application:
117-
11876
### Unit tests (`*.test.ts`, `*.test.tsx`)
11977

120-
- **Environment**: jsdom (fast, lightweight DOM simulation)
78+
- **Environment**: jsdom
12179
- **Location**: Co-located with source files in `src/`
122-
- **Purpose**: Test components, hooks, and utilities in isolation
12380
- **Run with**: `pnpm test:unit`
12481

12582
### Component tests (`*.stories.tsx`)
12683

12784
- **Environment**: Real browser (Chromium) via @vitest/browser-playwright
12885
- **Location**: Co-located with components in `src/`
129-
- **Purpose**: Visual testing and component interaction in Storybook
13086
- **Run with**: `pnpm test:storybook`
13187

13288
### E2E tests (`*.spec.ts`)
13389

134-
- **Environment**: @playwright/test with Chromium, Firefox, and WebKit
135-
- **Location**: `e2e/` directory
136-
- **Purpose**: Test complete user workflows and multi-page interactions
90+
- **Environment**: Chromium, Firefox, and WebKit via @playwright/test
91+
- **Location**: `e2e/`
13792
- **Run with**: `pnpm test:e2e`
13893

139-
# Contributing
94+
## Removing libraries you don't need
95+
96+
This template is opinionated — it picks libraries so you don't have to. If something doesn't fit your project, here's how to strip it out:
97+
98+
| Library | What to remove |
99+
| ------------ | -------------------------------------------------------------------------------------- |
100+
| Chakra UI | `src/lib/components/`, Chakra provider in `src/app/`, `@chakra-ui/*` deps |
101+
| React Router | `src/pages/`, route config in `src/app/`, `react-router` dep |
102+
| React Query | Query provider in `src/app/`, `src/lib/api/` query hooks, `@tanstack/react-query` deps |
103+
| i18next | `src/lib/i18n/`, i18n provider in `src/app/`, `i18next` + `react-i18next` deps |
104+
| Zustand | Store files in `src/features/*/stores/`, `zustand` dep |
105+
| XState | State machine files (example usage), `xstate` + `@xstate/react` deps |
106+
| MSW | `src/test-lib/handlers/`, `msw` dep, browser/server setup files |
107+
108+
After removing, run `pnpm install` to clean the lockfile and `pnpm lint` to catch broken imports.
109+
110+
## Contributing
140111

141-
It is publicly open for any contribution. Bugfixes, new features, and extra modules are welcome.
112+
Open for contributions — bugfixes, new features, and extra modules are welcome.
142113

143-
- To contribute to code: Fork the repo, push your changes to your fork, and submit a pull request.
144-
- To report a bug: If something does not work, please report it using [GitHub Issues](https://github.com/bartstc/spa-vite-template/issues).
114+
- **Code**: Fork the repo, push your changes, and submit a pull request.
115+
- **Bugs**: Report issues via [GitHub Issues](https://github.com/bartstc/spa-vite-template/issues).
145116

146-
# License
117+
## License
147118

148-
This project is licensed under the terms of the [MIT license](https://github.com/bartstc/vite-ts-react-template/blob/core/LICENSE).
119+
[MIT](https://github.com/bartstc/vite-ts-react-template/blob/core/LICENSE)

0 commit comments

Comments
 (0)