Skip to content

Commit 3796b08

Browse files
simonkovtyksimonkovtyk
committed
feat: added linter and proper docs
1 parent 5399278 commit 3796b08

File tree

12 files changed

+379
-116
lines changed

12 files changed

+379
-116
lines changed

‎.github/workflows/pull-request.yml

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Pull request checks
2+
on:
3+
pull_request:
4+
types:
5+
- opened
6+
- reopened
7+
branches:
8+
- main
9+
10+
jobs:
11+
pull_request:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Checkout
15+
uses: actions/checkout@v4
16+
17+
- name: Install
18+
uses: pnpm/action-setup@v4
19+
with:
20+
version: latest
21+
run_install: true
22+
23+
- name: TypeScript Compiler
24+
run: tsc --noEmit
25+
26+
- name: Lint
27+
run: pnpx eslint .

‎.husky/pre-commit

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
pnpx eslint .
2+
tsc --noEmit

‎README.md

+89-45
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,128 @@
1-
# esbuild plugin typescript
1+
<div align="center">
22

3-
![NPM Downloads](https://img.shields.io/npm/dw/esbuild-plugin-typescript) ![NPM License](https://img.shields.io/npm/l/esbuild-plugin-typescript)
3+
<img width="196" src="https://raw.githubusercontent.com/simonkovtyk/esbuild-plugin-package-json/d7d77d5766ef9ef97f157c2d221d61a7d3cef51c/docs/esbuild-favicon.svg" />
44

5-
The plugin enhances the build process by seamlessly integrating TypeScript, offering powerful features like type checking, automatic generation of .d.ts files, and ensuring robust type safety
6-
throughout.
5+
<h1>TypeScript Plugin</h1>
76

8-
* Supports newest esbuild and typescript version
9-
* Uses esbuild config to determine the out folder
10-
* Can do everything that TypeScript offers
11-
* Type declarations (d.ts) included
7+
<p>The plugin enhances the build process by seamlessly integrating TypeScript, offering powerful features like type checking, automatic generation of .d.ts files, and ensuring robust type safety throughout.</p>
128

13-
## How It Works
9+
![NPM Downloads](https://img.shields.io/npm/dw/esbuild-plugin-typescript)
10+
![NPM License](https://img.shields.io/npm/l/esbuild-plugin-typescript)
11+
![GitHub package.json version](https://img.shields.io/npm/v/esbuild-plugin-typescript)
12+
![TypeScript types](https://img.shields.io/badge/TypeScript_types-included-blue)
1413

15-
1. esbuild calls this package in the onStart lifecycle.
16-
2. Gets the configuration from esbuild or user-defined configuration.
17-
3. Evaluate the out folder, that should be deleted, based on the given input.
18-
4. Runs the official TypeScript-Compiler by its API and\
19-
generates output based on the given tsconfig.
14+
<br />
2015

21-
## Options
16+
Add a ⭐ to this repository — *it motivates me a lot!*
2217

23-
### Overriding the out-folder
18+
</div>
2419

25-
This package will search for a tsconfig by TypeScript itself.
26-
It can be helpful sometimes to override the path to the tsconfig:
27-
```typescript
28-
typescriptPlugin(
29-
overrideConfigPath?: string | undefined
30-
);
31-
```
20+
## ⚡️ Getting started
3221

33-
After using this override, this package will start to resolve your tsconfig. If your override is not valid, because the tsconfig does not exists, this package will discover the nearest tsconfing.
22+
Simply install this package with your package manager.
23+
24+
````shell
25+
npm install -D esbuild-plugin-typescript
26+
````
3427

35-
## Usage
28+
<details>
29+
<summary>📦 other package manager</summary>
3630

37-
### Installation
31+
Here are examples for installing the package with other package manager.
3832

39-
The plugin can be installed by any package manager.
33+
> 💾 **yarn**
34+
> ````shell
35+
> yarn add -D esbuild-plugin-typescript
36+
> ````
4037
41-
<details><summary><b>Show instructions</b></summary>
38+
> 💾 **pnpm**
39+
> ````shell
40+
> pnpm install -D esbuild-plugin-typescript
41+
> ````
4242
43-
> npm \
44-
> ``npm install esbuild-plugin-typescript``
43+
</details>
4544
46-
> yarn \
47-
> ``yarn install esbuild-plugin-typescript``
45+
Looks good so far 🔥 — now you have installed the latest version!
4846
49-
> pnpm \
50-
> ``pnpm install esbuild-plugin-typescript``
47+
## 💡 Introduction
5148
52-
</details>
49+
This esbuild plugin integrates TypeScript, generating .d.ts files and performing type checks based on the user's tsconfig.json. It uses the TypeScript compiler API to ensure strict type checks that
50+
esbuild alone can't provide.
5351
54-
### Integration
52+
During the build, TypeScript is compiled to JavaScript while .d.ts files are created simultaneously. The plugin runs tsc in a subprocess to handle type checking
53+
independently from esbuild’s fast bundling. This ensures type safety without sacrificing performance. It respects the user's configuration, ensuring compatibility with various project setups.
5554
56-
The easy way to integrate this plugin in esbuild.
55+
## 🔧 Usage
5756
58-
<details><summary><b>Show instructions</b></summary>
57+
```typescript
58+
typescriptPlugin(options);
59+
```
60+
61+
This function needs to be called inside the esbuild configuration in order to use this plugin. It will provide the plugin inside the build process of esbuild.
62+
63+
<details>
64+
<summary>Show an example of the integration</summary>
5965
6066
````typescript
61-
await esbuild.build({
67+
esbuild.build({
68+
// some configuration...
6269
plugins: [
63-
typescriptPlugin(...)
70+
typescriptPlugin();
71+
// more plugins here...
6472
]
6573
})
6674
````
6775
68-
[See here for more about the esbuild plugin integration.](https://esbuild.github.io/plugins/#using-plugins)
76+
</details>
77+
78+
<details>
79+
<summary>Show an example of the configuration</summary>
80+
81+
````typescript
82+
typescriptPlugin({
83+
// configure here
84+
});
85+
````
6986
7087
</details>
7188
89+
### Properties
90+
91+
#### ``overridePathToTsconfig``
92+
93+
> Default: ``undefined`` (esbuild's tsconfig file)
94+
95+
A ``string`` that determines the path to the tsconfig.
96+
97+
<details>
98+
<summary>Show an example</summary>
99+
100+
````typescript
101+
typescriptPlugin({
102+
overridePathToTsconfig: "libs/my-lib/tsconfig.json" // any path allowed
103+
});
104+
````
105+
106+
</details>
107+
108+
### Returns
109+
110+
Type: ``Plugin``
111+
112+
An instance of this plugin, that will be used by esbuild automatically.
113+
72114
## License
73115
74-
The MIT License (MIT) - Please have a look at the LICENSE file for more details.
116+
The MIT License (MIT) - Please have a look at the [License](https://github.com/simonkovtyk/esbuild-plugin-typescript/blob/main/LICENSE) file for more details.
75117
76118
## Contributing
77119
78-
Feel free to contribute to this project.\
79-
You can fork this project and create a new pull request for contributing.
120+
Want to contribute to an open-source project on GitHub but unsure where to start? Check out this comprehensive step-by-step guide on how to contribute effectively!
121+
122+
From forking the repository to creating pull requests, this guide walks you through every stage of the process, helping you make a successful contribution to this GitHub project. Start collaborating,
123+
learn new skills, and make an impact on this project!
80124
81-
[Get to the repository at GitHub.](https://github.com/simonkovtyk/esbuild-plugin-typescript)
125+
[See here](https://github.com/simonkovtyk/esbuild-plugin-typescript/blob/main/docs/guides/HOW_TO_CONTRIBUTE.md) for the contribute guide at GitHub.
82126
83127
<hr>
84128

‎docs/esbuild-favicon.svg

+7
Loading

‎docs/guides/HOW_TO_CONTRIBUTE.md

+150
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# ⚙️ How to contribute
2+
3+
How to Contribute to a GitHub Repository: A Step-by-Step Guide
4+
Contributing to open-source projects on GitHub is a great way to collaborate with others, learn new skills, and improve software. Here's a step-by-step guide on how to contribute to this GitHub
5+
repository.
6+
7+
## 1. Fork the Repository
8+
9+
Before making any changes, you'll need to fork the repository to your own GitHub account.
10+
11+
1. Go to the [repository page](https://github.com/simonkovtyk/esbuild-plugin-typescript/).
12+
2. Click on the "Fork" button in the top-right corner.
13+
3. GitHub will create a copy of the repository in your account.
14+
15+
## 2. Clone Your Fork Locally
16+
17+
Next, you need to clone your forked repository to your local machine.
18+
19+
Open a terminal on your computer.
20+
21+
Use the following command to clone the repository:
22+
23+
````shell
24+
git clone https://github.com/YOUR-USERNAME/esbuild-plugin-typescript.git
25+
````
26+
27+
Replace YOUR-USERNAME with your GitHub username.
28+
29+
Navigate into the project directory:
30+
31+
````shell
32+
cd esbuild-plugin-typescript
33+
````
34+
35+
## 3. Set Up the Upstream Remote
36+
37+
To ensure you can pull in updates from the original repository, add an "upstream" remote.
38+
39+
In the terminal, run:
40+
41+
````shell
42+
git remote add upstream https://github.com/simonkovtyk/esbuild-plugin-typescript.git
43+
````
44+
45+
Confirm the upstream remote has been added:
46+
47+
````shell
48+
git remote -v
49+
````
50+
51+
## 4. Create a New Branch
52+
53+
To keep your changes organized and separate from the main codebase, create a new branch.
54+
55+
Make sure you're in the main branch:
56+
57+
````shell
58+
git checkout main
59+
````
60+
61+
Create and switch to a new branch:
62+
63+
````shell
64+
git checkout -b branch-name
65+
````
66+
67+
Replace branch-name with a descriptive name for your branch (e.g., fix-bug, add-feature).
68+
69+
## 5. Make Your Changes
70+
71+
Now you're ready to make changes to the codebase. Open the project in your favorite code editor, modify the code, and save your changes.
72+
73+
## 6. Commit Your Changes
74+
75+
After making your changes, commit them to your branch.
76+
77+
Check which files have changed:
78+
79+
````shell
80+
git status
81+
````
82+
83+
Stage your changes:
84+
85+
````shell
86+
git add .
87+
````
88+
89+
Commit your changes with a descriptive message:
90+
91+
````shell
92+
git commit -m "Brief description of the changes"
93+
````
94+
95+
## 7. Push Your Branch to GitHub
96+
97+
Push your changes to your fork on GitHub.
98+
99+
````shell
100+
git push origin branch-name
101+
````
102+
103+
## 8. Open a Pull Request
104+
105+
Now that your changes are pushed to your fork, it's time to open a pull request (PR) to the original repository.
106+
107+
1. Go to the [original repository](https://github.com/simonkovtyk/esbuild-plugin-typescript/) on GitHub.
108+
2. Click the "Compare & pull request" button.
109+
3. Review your changes and ensure they are correct.
110+
4. Add a descriptive title and description for your PR.
111+
5. Click "Create pull request."
112+
113+
## 9. Respond to Review Feedback
114+
115+
After opening your pull request, a code style check will run automatically and the maintainers of the repository might review your code and suggest changes.
116+
117+
If changes are requested, update your branch locally, commit the new changes, and push them to your fork.
118+
The PR will automatically update with your latest changes.
119+
120+
## 10. Keep Your Fork Up-to-Date
121+
122+
To ensure your fork remains up-to-date with the original repository, regularly sync it with the upstream repository.
123+
124+
Fetch the latest updates from upstream:
125+
126+
````shell
127+
git fetch upstream
128+
````
129+
130+
Merge the upstream changes into your local main branch:
131+
132+
````shell
133+
git checkout main
134+
````
135+
136+
````shell
137+
git merge upstream/main
138+
````
139+
140+
Push the updated main branch to your fork:
141+
142+
````shell
143+
git push origin main
144+
````
145+
146+
## 11. Celebrate Your Contribution!
147+
148+
Once your pull request is merged, you've officially contributed to an open-source project!
149+
150+
**🚀 Congratulations!**

‎eslint.config.mjs

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
import eslint from "@eslint/js";
2+
import tseslint from "typescript-eslint";
3+
import stylistic from "@stylistic/eslint-plugin";
4+
5+
export default tseslint.config(
6+
{
7+
ignores: [
8+
".github",
9+
".idea",
10+
"dist",
11+
"docs",
12+
"node_modules"
13+
]
14+
},
15+
eslint.configs.recommended,
16+
...tseslint.configs.strict,
17+
...tseslint.configs.stylistic,
18+
stylistic.configs.customize({
19+
indent: 2,
20+
quotes: "double",
21+
semi: true,
22+
commaDangle: "never",
23+
jsx: false
24+
})
25+
);

0 commit comments

Comments
 (0)