Skip to content

Commit 2d922d1

Browse files
ioncakephperioncakephper
committed
update: update 6 files
1 parent 5243938 commit 2d922d1

File tree

3 files changed

+434
-199
lines changed

3 files changed

+434
-199
lines changed

‎README.md‎

Lines changed: 77 additions & 156 deletions
Original file line numberDiff line numberDiff line change
@@ -1,201 +1,122 @@
1-
# {{PROJECT_NAME}}
1+
# 🚀 JS Quality Starter
22

3-
[![CI](https://github.com/your-username/your-new-repo/actions/workflows/ci.yml/badge.svg)](https://github.com/your-username/your-new-repo/actions/workflows/ci.yml)
4-
[![codecov](https://codecov.io/gh/your-username/your-new-repo/graph/badge.svg?token=YOUR_CODECOV_TOKEN)](https://codecov.io/gh/your-username/your-new-repo)
5-
[![Code style: Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
6-
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
3+
`js-quality-starter` is a comprehensive template for jumpstarting new JavaScript projects with a strong emphasis on code quality, maintainability, and modern development practices. It comes pre-configured with essential tools and a handy setup script to personalize your new repository in minutes.
74

8-
A template repository for modern JavaScript projects with pre-configured linting, formatting, testing, and CI/CD using GitHub Actions.
9-
10-
This template provides a solid foundation for any new JavaScript project, ensuring code quality and consistency from the start.
5+
---
116

127
## Table of Contents
138

149
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
1510
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
1611

17-
- [Quick Start](#quick-start)
18-
- [Getting Started with Your New Project](#getting-started-with-your-new-project)
19-
- [Why Choose `js-quality-started`?](#why-choose-js-quality-started)
20-
- [What's Inside?](#whats-inside)
12+
- [Features](#features)
2113
- [Getting Started](#getting-started)
22-
- [Using as a Template](#using-as-a-template)
23-
- [Manual Setup](#manual-setup)
24-
- [Post-Template Setup](#post-template-setup)
25-
- [Available Scripts](#available-scripts)
14+
- [Using This Template](#using-this-template)
15+
- [Project Personalization](#project-personalization)
16+
- [Included Tools & Configurations](#included-tools--configurations)
17+
- [Testing](#testing)
18+
- [Linting & Formatting](#linting--formatting)
19+
- [Git Hooks](#git-hooks)
20+
- [Continuous Integration](#continuous-integration)
21+
- [License](#license)
22+
- [Contact](#contact)
2623

2724
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
2825

29-
## Quick Start
30-
31-
```bash
32-
git clone https://github.com/{{GITHUB_USERNAME}}/{{PROJECT_NAME}}.git
33-
cd {{PROJECT_NAME}}
34-
npm install
35-
npm run setup # Clearly state to run your setup script!
36-
# Start building!
37-
```
38-
39-
## Getting Started with Your New Project
40-
41-
After creating a new repository from this template and cloning it to your local machine, run the setup script to personalize your project:
42-
43-
```bash
44-
npm install # if you haven't already
45-
npm run setup
46-
```
47-
48-
This script will guide you through updating the project name, author, and other details.
49-
50-
## Why Choose `js-quality-started`?
51-
52-
Tired of repetitive setup, inconsistent code, and integration headaches? See how `js-quality-started` provides a superior foundation compared to starting from scratch or using basic boilerplates.
53-
54-
| Criteria | Minimal/Empty Repository | Basic Boilerplate | `js-quality-started` Template |
55-
| :--------------------------------- | :----------------------- | :------------------------------- | :----------------------------------------------------------- |
56-
| **Core Purpose** | Blank slate | Quick start, basic structure | Quality, consistency, efficiency |
57-
| **Linting (e.g., ESLint)** | ❌ No | ⚙️ Manual setup required / Basic | ✅ Pre-configured, opinionated |
58-
| **Formatting (e.g., Prettier)** | ❌ No | ⚙️ Manual setup required | ✅ Pre-configured |
59-
| **Testing Framework (e.g., Jest)** | ❌ No | ⚙️ Manual setup required | ✅ Pre-configured with coverage |
60-
| **Test Coverage Reporting** | ❌ No | ❌ No | ✅ Included |
61-
| **Build/Bundling Tool** | ❌ No | ⚙️ Manual setup required / Basic | ✅ Pre-configured (e.g., Babel) |
62-
| **Language Support** | JS Only | JS Only | JS (easily extensible to TS) |
63-
| **Documentation Gen. Tools** | ❌ No | ❌ No | ⚙️ Manual add/Configuring |
64-
| **CI/CD Configuration** | ❌ No | ⚙️ Manual setup required / Basic | ✅ Pre-configured GitHub Actions |
65-
| **Community Health Files** | ❌ No | ⚙️ Basic `README.md` | ✅ Comprehensive (`README`, `CONTRIBUTING`, `LICENSE`, etc.) |
66-
| **Opinionation Level** | None | Low | High (for quality tools) |
67-
| **Initial Setup Time** | Very High | High | Very Low |
68-
| **Code Quality Assurance** | Manual | Limited / Manual | Automated & Proactive |
69-
| **Team Collaboration Aid** | Low | Moderate | High |
70-
71-
## What's Inside?
72-
73-
This template comes pre-configured with a suite of modern, industry-standard tools to ensure your project maintains high code quality.
74-
75-
| Tool | Purpose |
76-
| :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
77-
| **ESLint** | Statically analyzes your code to quickly find and fix problems. It's configured with recommended rules to enforce best practices. |
78-
| **Prettier** | An opinionated code formatter that enforces a consistent style across your entire codebase, eliminating arguments over code style. |
79-
| **Jest** | A delightful JavaScript Testing Framework with a focus on simplicity. It's set up and ready for you to write unit and integration tests. |
80-
| **markdownlint** | A linter for Markdown files to enforce consistent style and catch common errors in documentation. |
81-
| **Husky** | Manages Git hooks to make it easy to run scripts at specific stages, like before a commit. |
82-
| **lint-staged** | Works with Husky to run linters and formatters on your staged files _before_ they are committed, ensuring no bad code gets in. |
83-
| **GitHub Actions** | Automates your workflow with two pre-configured CI pipelines for validating code on `main` and all other feature branches. |
26+
---
8427

85-
## Getting Started
28+
## Features
8629

87-
### Using as a Template
30+
- **Node.js & npm:** Modern JavaScript development environment.
31+
- **Jest:** Powerful testing framework for unit and integration tests, with code coverage configuration.
32+
- **ESLint:** Configured with best practices for identifying and reporting on patterns in JavaScript code.
33+
- **Prettier:** Opinionated code formatter to ensure consistent code style across the project.
34+
- **Husky & lint-staged:** Pre-commit Git hooks to automatically run linting and formatting on staged files.
35+
- **EditorConfig:** Helps maintain consistent coding styles across different editors and IDEs.
36+
- **GitHub Actions:** Basic CI/CD workflow for automated linting, testing, and optional code coverage reporting (e.g., to Codecov).
37+
- **Dynamic Setup Script (`setup.js`):** A command-line utility to quickly personalize your new project based on this template, updating `package.json`, `README.md`, `LICENSE`, and other essential files.
8838

89-
1. Click the **"Use this template"** button on the GitHub repository page.
90-
2. Select **"Create a new repository"**.
91-
3. Give your new repository a name and description.
92-
4. Clone your new repository to your local machine.
39+
---
9340

94-
### Manual Setup
41+
## Getting Started
9542

96-
1. Clone the repository:
43+
### Using This Template
9744

98-
```bash
99-
git clone https://github.com/{{GITHUB_USERNAME}}/{{PROJECT_NAME}}.git # Replace with your actual repository URL
100-
cd {{PROJECT_NAME}}
101-
```
45+
To create a new project based on `js-quality-starter`, you can clone this repository or use it as a template directly on GitHub:
10246

103-
2. Install dependencies:
47+
1. **Create a new repository from this template:**
48+
- Click the "Use this template" button on the GitHub page.
49+
- Alternatively, clone this repository and remove the `.git` directory:
50+
51+
```bash
52+
git clone [https://github.com/your-username/js-quality-starter.git](https://github.com/your-username/js-quality-starter.git) my-new-project
53+
cd my-new-project
54+
rm -rf .git # On Windows, use `rmdir /s /q .git`
55+
```
56+
57+
2. **Install dependencies:**
10458

10559
```bash
10660
npm install
10761
```
10862

109-
This will install all dependencies and also run the `prepare` script, which sets up the Husky pre-commit hooks automatically.
110-
111-
3. Start coding!
112-
113-
### Post-Template Setup
114-
115-
After creating your repository from this template and cloning it locally, personalize your project by running the setup script:
63+
3. **Run the setup script:** This is the most crucial step for personalizing your new project.
11664

117-
```bash
118-
npm install # Ensure dependencies are installed, including 'inquirer'
119-
npm run setup
120-
```
121-
122-
## Available Scripts
123-
124-
In the project directory, you can run:
125-
126-
````bash
127-
- `npm test`: Runs the tests using Jest.
128-
- `npm run lint`: Lints all `.js` files in the project.
129-
- `npm run lint:fix`: Lints and automatically fixes fixable issues.
130-
- `npm run format`: Checks for formatting issues with Prettier.
131-
- `npm run format:fix`: Formats all supported files with Prettier.
132-
- `npm run lint:md`: Lints all Markdown files.
133-
- `npm run lint:md:fix`: Lints and automatically fixes fixable issues in Markdown files.
134-
- `npm run format:md`: Checks for formatting issues with Prettier for Markdown files.
135-
- `npm run format:md:fix`: Formats all Markdown files with Prettier.
136-
- `npm run toc`: Generates a Table of Contents for the `README.md` file.
137-
- `npm run fix:all`: Runs all fixable scripts in one command.
138-
139-
## How It Works
140-
141-
### Pre-commit Hooks
65+
```bash
66+
node setup.js
67+
# OR if you've added an npm script for it (recommended):
68+
# npm run setup
69+
```
14270

143-
This project uses `Husky` and `lint-staged` to run `eslint --fix`, `prettier --write` (for both code and Markdown), and `markdownlint --fix` on staged files every time you make a commit. This automated quality gate ensures that no code or documentation that violates the style guide ever gets into the codebase.
71+
### Project Personalization
14472

145-
If a file has linting or formatting errors, the tools will attempt to fix them automatically. If they can, the fixed code is what gets committed. If they can't, the commit is aborted so you can fix the issues manually.
73+
The `setup.js` script will guide you through a few questions to customize your new project:
14674

147-
### CI/CD Pipelines
75+
- **Project Name & Description:** Sets these in `package.json` and `README.md`.
76+
- **Author & Contact Info:** Populates author details in `package.json`, `README.md`, `LICENSE`, and other documentation.
77+
- **License Type:** Lets you choose a standard license (e.g., MIT, Apache-2.0, GPL-3.0) which is then set in `package.json` and used to update the `LICENSE` file.
78+
- **Code Coverage:** Optionally configures Jest for coverage and integrates with Codecov (including badge in `README.md` and CI setup details).
79+
- **GitHub Username:** Used for repository links in `README.md`.
14880

149-
This template includes one GitHub Action workflow located in the `.github/workflows` directory:
81+
After running `setup.js`, your project will be ready with a personalized `package.json`, `README.md`, `LICENSE` file, and more, tailored to your new project's details. You can then remove `setup.js` and `README.template.md` (or move them to a `tools/` directory) as they are no longer needed.
15082
151-
- **`ci.yml`**: This workflow runs on every push and pull request to the `main` branch. It acts as a final validation gate, ensuring that all tests, linting, and formatting checks pass before code is merged.
83+
---
15284
153-
The workflow performs the following steps across multiple Node.js versions (18.x, 20.x):
85+
## Included Tools & Configurations
15486
155-
1. **Install dependencies** using `npm ci` for fast, reliable installs.
156-
2. **Lint code** with `npm run lint`.
157-
3. **Lint Markdown files** with `npm run lint:md`.
158-
4. **Check code formatting** with `npm run format`.
159-
5. **Check Markdown formatting** with `npm run format:md`.
160-
6. **Audit for vulnerabilities** with `npm audit --production`.
161-
7. **Run tests** with `npm test`.
87+
### Testing
16288
163-
## Customization
89+
- **Jest:** A delightful JavaScript testing framework with a focus on simplicity.
90+
- `npm test`: Runs all tests.
91+
- `npm test:watch`: Runs tests in interactive watch mode.
92+
- `npm test:coverage`: Runs tests and generates a code coverage report in the `coverage/` directory.
16493
165-
This template is a starting point. You can easily customize it to fit your project's needs:
94+
### Linting & Formatting
16695
167-
- **Linting Rules**: Modify the `.eslintrc.js` file to add or change ESLint rules.
168-
- **Formatting Options**: Adjust the `.prettierrc` file to change Prettier's formatting options.
169-
- **Markdown Linting**: Customize `markdownlint` rules by editing the `.markdownlint.json` file.
170-
- **Testing**: The `jest.config.js` file can be configured for more advanced testing scenarios.
171-
- **CI/CD**: Edit the workflow files in `.github/workflows` to add new steps, such as deployment or notifications.
96+
- **ESLint:** Statically analyzes your code to quickly find problems.
97+
- `npm run lint`: Runs ESLint over your codebase.
98+
- `npm run lint:fix`: Runs ESLint and attempts to fix auto-fixable issues.
99+
- **Prettier:** An opinionated code formatter that ensures consistent code style.
100+
- `npm run format`: Formats your entire codebase with Prettier.
172101
173-
## Code Coverage
102+
### Git Hooks
174103
175-
This template is configured to generate code coverage reports using Jest. The reports are output to the `coverage/` directory in various formats, including `lcov`, which is compatible with popular code coverage services.
104+
- **Husky:** Simplifies the use of Git hooks.
105+
- **lint-staged:** Runs linters on Git staged files.
106+
- These are pre-configured to run ESLint and Prettier on staged files before you commit, helping maintain a clean and consistent codebase automatically.
176107
177-
To get a dynamic code coverage badge like the one at the top of this `README.md`, you can integrate with a service like Codecov or Coveralls.
108+
### Continuous Integration
178109
179-
**Steps to set up Codecov (example):**
110+
- **.github/workflows/ci.yml:** A basic GitHub Actions workflow is included to automate linting, testing, and (optionally) code coverage upload on every push and pull request. This ensures your project always meets quality standards.
180111
181-
1. Sign up for Codecov with your GitHub account.
182-
2. Add your repository to Codecov.
183-
3. Codecov will provide you with a `CODECOV_TOKEN`. Add this token as a secret in your GitHub repository settings (e.g., `CODECOV_TOKEN`).
184-
4. Add a step to your CI workflow (`.github/workflows/ci.yml`) to upload the coverage report to Codecov. This typically involves adding a step like:
112+
---
185113
186-
```yaml
187-
- name: Upload coverage to Codecov
188-
uses: codecov/codecov-action@v4
189-
with:
190-
token: ${{ secrets.CODECOV_TOKEN }}
191-
```
192-
5. Update the badge URL in `README.md` with your specific repository details and token (if required by Codecov for public repos, though often not for public repos).
114+
## License
193115
194-
## Contributing
116+
This `js-quality-starter` template itself is open-sourced under the **MIT License**. For the license of a project created using this template, please refer to the `LICENSE` file generated by the `setup.js` script within that new project.
195117
196-
We welcome contributions! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on how to contribute, report bugs, and suggest enhancements.
118+
---
197119
198-
## License
120+
## Contact
199121
200-
This project is licensed under the [LICENSE](LICENSE) file for details.
201-
````
122+
For questions or feedback about the `js-quality-starter` template, please open an issue in this repository or contact the maintainers at [[email protected]](mailto:[email protected]).

0 commit comments

Comments
 (0)