Skip to content

Commit f1be0e0

Browse files
author
Andrew Dmitriev
committed
Merge branch 'сreate-docs-RVCB-9'
2 parents 5c09092 + 4d4564e commit f1be0e0

2 files changed

Lines changed: 146 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,146 @@
1+
# React Vite Custom Boilerplate
12

3+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE)
4+
5+
[![Support me on Boosty](https://img.shields.io/badge/Boosty-Support%20me-%23f15f2c?style=for-the-badge)](https://boosty.to/theEvilGrinch/donate)
6+
[![Donate](https://img.shields.io/badge/Donate-%23702ff4?style=for-the-badge)](https://yoomity.ru/to/410016288289737)
7+
8+
Frontend boilerplate with pre-configured development environment. Includes ESLint and Stylelint setup, structured styles with mixins and variables, light/dark theme system, cookie handling, PWA manifest with icons, development server configuration, and removable template components for rapid project initialization.
9+
10+
## Table of Contents
11+
12+
- [Features](#features)
13+
- [Project Structure](#project-structure)
14+
- [Getting Started](#getting-started)
15+
- [Available Scripts](#available-scripts)
16+
- [Dependencies](#dependencies)
17+
- [Customizations](#customizations)
18+
- [Template Cleanup Guide](#template-cleanup-guide)
19+
- [Contributing](#contributing)
20+
- [License](#license)
21+
22+
## Features
23+
24+
- **Development Server**: Includes development server with Hot Module Replacement (`vite.config.js`).
25+
- **Code Quality Linters**: Includes pre-configured linters for JavaScript/React (`eslint.config.js`) and CSS/Sass (`.stylelintrc.json`).
26+
- **Sass Integration**: Provides structured file system for Sass preprocessor in `src/styles`.
27+
- **Theme Switching System**: Light/dark mode system that detects OS preference and persists user choice (`src/utils/theme.js`).
28+
- **PWA-Ready Setup**: Contains necessary manifest file and icon set for Progressive Web App installation (`public/manifest.webmanifest`).
29+
30+
## Project Structure
31+
32+
```
33+
.
34+
├── .dockerignore # Specifies files to ignore for Docker builds.
35+
├── .gitignore # Lists files and directories intentionally untracked by Git.
36+
├── .stylelintrc.json # Configuration file for Stylelint (CSS/Sass linter).
37+
├── README.md # Project documentation.
38+
├── eslint.config.js # Configuration file for ESLint (JavaScript/React linter).
39+
├── index.html # Root HTML file where React application is mounted.
40+
├── package.json # Defines project metadata, npm scripts, and dependency lists.
41+
├── package-lock.json # Ensures deterministic builds by locking dependency versions.
42+
├── public/ # Directory for static assets
43+
├── src/ # Directory for application source code.
44+
│ ├── App.css # Styles defining layout for App component.
45+
│ ├── App.jsx # Root React component, acting as container for page structure.
46+
│ ├── assets/ # Directory for static assets processed by build tool.
47+
│ ├── components/ # Directory for all React components.
48+
│ │ └── template-components/ # Directory with placeholder components for removal.
49+
│ │ ├── Aside.jsx # Template 'Aside' component.
50+
│ │ ├── CookieDialog.jsx # Template 'CookieDialog' component.
51+
│ │ ├── Footer.jsx # Template 'Footer' component.
52+
│ │ ├── Header.jsx # Template 'Header' component.
53+
│ │ ├── Main.jsx # Template 'Main' content component.
54+
│ │ └── TemplateStyles.scss # Stylesheet for all template components.
55+
│ ├── favicons-src/ # Source directory for favicon generation.
56+
│ │ └── favicon.svg # Source SVG file used to generate favicons.
57+
│ ├── main.jsx # Application entry point where React app is mounted to DOM.
58+
│ ├── styles/ # Directory for global styles and Sass configuration.
59+
│ │ ├── _breakpoints.scss # Sass file defining media query breakpoints.
60+
│ │ ├── _custom.scss # Empty file for adding custom user styles.
61+
│ │ ├── _fonts.scss # File for defining @font-face rules.
62+
│ │ ├── core/ # Directory for core Sass files.
63+
│ │ │ ├── _mixins.scss # Contains reusable Sass mixins.
64+
│ │ │ ├── _variables.scss # Contains Sass variable definitions (colors, fonts, etc.).
65+
│ │ │ └── index.scss # Imports all files from 'core' directory.
66+
│ │ ├── index.scss # Main Sass file that imports all other style files.
67+
│ │ └── reset.css # CSS reset file to normalize browser-default styles.
68+
│ └── utils/ # Directory for utility functions.
69+
│ ├── cookies.js # Contains logic for cookie consent dialog.
70+
│ └── theme.js # Contains logic for theme management system.
71+
└── vite.config.js # Configures Vite development server, build process, and plugins.
72+
```
73+
74+
## Getting Started
75+
76+
To get the project running locally, execute the following commands in your terminal:
77+
78+
```bash
79+
git clone https://github.com/theEvilGrinch/react-vite-custom-boilerplate.git
80+
cd react-vite-custom-boilerplate
81+
npm install
82+
npm run dev
83+
```
84+
85+
## Available Scripts
86+
87+
- `npm run dev`: Starts development server.
88+
- `npm run build`: Bundles application for production into `dist` directory.
89+
- `npm run lint`: Analyzes codebase for potential errors and style issues.
90+
- `npm run preview`: Serves production build locally for review.
91+
92+
## Dependencies
93+
94+
### Production
95+
- `react`: JavaScript library for building user interfaces.
96+
- `react-dom`: Provides DOM-specific methods for React.
97+
98+
### Development
99+
- `@eslint/js`, `eslint`, `globals`: Core packages for ESLint, static code analysis tool.
100+
- `@types/react`, `@types/react-dom`: TypeScript type definitions for React and React DOM.
101+
- `@vitejs/plugin-react-swc`: Vite plugin that enables React support via SWC compiler.
102+
- `eslint-plugin-react-hooks`, `eslint-plugin-react-refresh`: ESLint plugins for enforcing React Hooks rules and enabling Fast Refresh.
103+
- `sass`: Sass CSS preprocessor.
104+
- `stylelint`, `@stylistic/stylelint-plugin`, `postcss-scss`: Packages for Stylelint, linter for CSS/Sass.
105+
- `vite`: Build tool and development server.
106+
107+
## Customizations
108+
109+
- **Development Server**: Server configuration in `vite.config.js` specifies port (`5173`), host (`127.0.0.1`), and automatically opens browser tab on startup.
110+
111+
- **Code Quality Linters**: Project includes configurations for two linters. ESLint (`eslint.config.js`) analyzes JavaScript and React code. Stylelint (`.stylelintrc.json`), along with its stylistic plugin, manages CSS and Sass code style.
112+
113+
- **Sass Preprocessor**: Structured Sass setup is included in `src/styles`. `_mixins.scss` provides reusable functions including `flex-text` for responsive typography, `media-range`, `max-width`, and `min-width` for media query management. `_variables.scss` holds project-wide variables, and `index.scss` files act as aggregators for all partials.
114+
115+
- **Theme Management**: Logic in `src/utils/theme.js` sets initial theme based on user's OS preference (`prefers-color-scheme`). Separate function is available to toggle theme and persist choice in `localStorage`.
116+
117+
- **Cookie Consent**: Script in `src/utils/cookies.js` displays dialog if cookie named `cookieConsent` with value `accepted` is not found. Upon acceptance, it sets this cookie with `Max-Age` of 31,536,000 seconds (1 year).
118+
119+
- **PWA Configuration**: `public` directory contains `manifest.webmanifest` and complete set of icons to make application installable. For details on generating these icons, see [Favicon Generation](#favicon-generation) section.
120+
121+
- **Favicon Generation**: `src/favicons-src/` directory is prepared for use with [favicon-generator-cli](https://github.com/theEvilGrinch/favicon-generator-cli). Place source images in this directory and use generator to create optimized favicon sets for `public/` directory. Visit [favicon-generator-cli repository](https://github.com/theEvilGrinch/favicon-generator-cli) for detailed instructions and usage examples.
122+
123+
## Template Cleanup Guide
124+
125+
Before starting development, the following items should be addressed in order:
126+
127+
1. **Update Project Metadata**: Modify `name`, `version`, and other fields in `package.json`.
128+
2. **Remove Template Components**: Delete `src/components/template-components` directory.
129+
3. **Remove Utility Scripts**: Delete `src/utils` directory.
130+
4. **Update Entry Point**: Remove style import for template components and `initTheme()` and `setCookies()` calls from `src/main.jsx`.
131+
5. **Clear Root Component**: Erase placeholder content within `App.jsx`.
132+
6. **Customize Styles**: Modify variables in `src/styles/core/_variables.scss` and add project-specific styles in `src/styles/_custom.scss`.
133+
7. **Update PWA Manifest**: Edit `public/manifest.webmanifest` to reflect your application's name, theme colors, and other details.
134+
8. **Replace Favicons**: Place your own source image in `src/favicons-src` and regenerate favicon set. See [Favicon Generation](#favicon-generation) section for instructions.
135+
136+
## Contributing
137+
138+
Contributions, issues, and feature requests are welcome. Feel free to check the [issues page](https://github.com/theEvilGrinch/react-vite-custom-boilerplate/issues) if you want to contribute.
139+
140+
## License
141+
142+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
143+
144+
---
145+
146+
Maintained by [@theEvilGrinch](https://github.com/theEvilGrinch)

‎package.json‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,7 @@
77
"dev": "vite",
88
"build": "vite build",
99
"lint": "eslint vite-project",
10-
"preview": "vite preview",
11-
"rm-template-data": "rm -rf ./src/components/template-components/"
10+
"preview": "vite preview"
1211
},
1312
"dependencies": {
1413
"react": "^19.1.0",

0 commit comments

Comments
 (0)