Skip to content

Commit b0090af

Browse files
CC11001100CC11001100
committed
Create README_en.md
1 parent 2ff44d2 commit b0090af

File tree

1 file changed

+177
-0
lines changed

1 file changed

+177
-0
lines changed

‎README_en.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# UserScript Template
2+
3+
# 1. What is this?
4+
5+
A plan for using `Node.js` + `Webpack` for modular development of Tampermonkey scripts, aimed at improving the development experience of Tampermonkey, reducing the mental burden during development, and allowing Tampermonkey scripts to be developed like a regular modular front-end project. Otherwise, a `JavaScript` file with thousands of lines to be modified back and forth is really too much to handle...
6+
7+
# 2. Advantages
8+
9+
- Modular development of Tampermonkey projects can greatly enhance both the development experience and efficiency. You no longer have to worry about how to organize code within a single `JavaScript` file (Tampermonkey scripts uploaded to the Tampermonkey store must be single files without obfuscation or compression, and the JS files produced by modular development and packaging also meet the requirements for uploading).
10+
- Hot module replacement (HMR) during development increases efficiency. By adopting the recommended development mode, Tampermonkey points to the local file address of the packaged results. When there are changes in the `JavaScript` code, it automatically compiles and packages the load, making it more efficient to modify and test code during development (those who have written Tampermonkey scripts should have experienced the frustration of spending a lot of time modifying and testing code back and forth, which is really exhausting).
11+
- When publishing, the packaged result is a single `JavaScript` file with high readability, which complies with the Tampermonkey store's policy for listing scripts. The packaged file is ready for listing without the need for any manual processing work, making it simple, convenient, and hassle-free.
12+
13+
# 3. Quick Start
14+
15+
To quickly get started with the project template, follow these steps:
16+
17+
1. Go to the repository at [https://github.com/JSREI/userscript-template](https://github.com/JSREI/userscript-template).
18+
2. Click on the "Use this template" button.
19+
3. Then, select "Create a new repository" to create a new repository from this template.
20+
21+
This process will set up a new repository for your project, using the structure and files provided by the template. If you encounter any issues with the link or the process, ensure that the link is correct and that you have a stable internet connection. If the problem persists, you may need to check for any updates or changes to the repository or try again later.
22+
23+
![image-20230816233501101](README.assets/image-20230816233501101.png)
24+
25+
Choose the location for the new repository and set the repository name, among other settings. Typically, it's convenient to place the new repository under your own account:
26+
27+
1. After clicking "Create a new repository," you'll be prompted to choose the owner of the repository. It's common to select your own GitHub account.
28+
2. Enter a name for your new repository that reflects its purpose or content.
29+
3. Optionally, you can add a short description of the repository.
30+
4. Choose whether the repository should be public or private.
31+
5. Decide if you want to include a README file, .gitignore, and a license.
32+
6. Click the "Create repository" button to finalize the creation process.
33+
34+
This will create a new repository with the specified settings, ready for you to start your project development.
35+
36+
![image-20230816235634094](README.assets/image-20230816235634094.png)
37+
38+
The new repository has been created and cloned to your local machine. Then, in the root directory of the cloned project, execute the command to install the project's required dependencies:
39+
40+
```bash
41+
npm install
42+
```
43+
44+
The installation of dependencies may take some time; please be patient and wait a moment.
45+
46+
![image-20230817003339266](README.assets/image-20230817003339266.png)
47+
48+
If the installation of dependencies is too slow or the downloads are not coming through, you can configure a domestic mirror source for `npm` or use `cnpm` (search for it on Google yourself).
49+
50+
Then, modify the `package.json` file, replacing the relevant fields with your own, such as the name, author, repository address, and so on:
51+
52+
```js
53+
{
54+
"name": "userscript-foo",
55+
"version": "0.0.1",
56+
"main": "index.js",
57+
"repository": "https://github.com/JSREI/userscript-template.git",
58+
"scripts": {
59+
// ...
60+
},
61+
"author": "CC11001100 <[email protected]>",
62+
"license": "MIT",
63+
"devDependencies": {
64+
//...
65+
}
66+
}
67+
```
68+
69+
In the `userscript-headers.js` file located in the project's root directory, the default Tampermonkey headers are stored. During the `webpack` compilation, this file is placed at the beginning of the compiled file as the Tampermonkey plugin declaration:
70+
71+
```js
72+
// ==UserScript==
73+
// @name ${name}
74+
// @namespace ${repository}
75+
// @version ${version}
76+
// @description ${description}
77+
// @document ${document}
78+
// @author ${author}
79+
// @match *://*/*
80+
// @run-at document-start
81+
// ==/UserScript==
82+
```
83+
84+
`${name}`, `${version}`, and similar are some of the variables supported by this Tampermonkey scaffold. The principle is that during compilation, the corresponding values are obtained from `package.json` and the variables are replaced (this is called variable rendering). This way, for content that might be repeated or constantly changing, we can use a single source reference without having to set or repeatedly modify it. If the default configuration does not meet your requirements, you can directly modify this header file, for example, to add permissions:
85+
86+
```js
87+
// ==UserScript==
88+
// @name ${name}
89+
// @namespace ${repository}
90+
// @version ${version}
91+
// @description ${description}
92+
// @document ${document}
93+
// @author ${author}
94+
// @match *://*/*
95+
// @run-at document-start
96+
// @grant GM_getValue
97+
// @grant GM_setValue
98+
// @grant GM_registerMenuCommand
99+
// @grant GM.getValue
100+
// @grant GM.setValuex
101+
// @grant GM.registerMenuCommand
102+
// ==/UserScript==
103+
```
104+
105+
In addition to variable substitution, all other content will be preserved as is, this is what the compiled version looks like:
106+
107+
![image-20230817004653299](README.assets/image-20230817004653299.png)
108+
109+
Then you can happily start coding. While writing code, you can use the `npm` command to add dependencies to your project. For a slightly more complex script, it is very likely to reference external dependencies:
110+
111+
```bash
112+
npm add xxx
113+
```
114+
115+
However, it is important to note that these dependencies will ultimately be packed into `./dist/index.js`, and this file should not be too large, so try to avoid referencing too many third-party libraries.
116+
117+
At the same time, you can now organize your code in a modular way under the `src` directory, instead of struggling with a single `JavaScript` file that is thousands of lines long as before (single-file development is simply a form of mental torture...):
118+
119+
![image-20230817003923075](README.assets/image-20230817003923075.png)
120+
121+
When you need to test, execute:
122+
123+
```bash
124+
npm run watch
125+
```
126+
127+
Then copy the file header from `./dist/index.js` to your Tampermonkey extension:
128+
129+
![image-20230817000716664](README.assets/image-20230817000716664.png)
130+
131+
And at the end, add a line to import the compiled file, noting that the `file://` followed by the address points to the absolute path of your compiled `./dist/index.js`:
132+
133+
```js
134+
// @require file://D:/workspace/userscript-template/dist/index.js
135+
```
136+
137+
For example, here is an actual example of a Tampermonkey script used during development. The Tampermonkey script does not contain actual code but uses `require` to point to our `build` files. This way, when the code is modified and `webpack` automatically hot compiles, the `./dist/index.js` referenced in the browser is also the latest:
138+
139+
```js
140+
// ==UserScript==
141+
// @name userscript-foo
142+
// @namespace https://github.com/JSREI/userscript-template.git
143+
// @version 0.0.1
144+
// @description
145+
// @document
146+
// @author CC11001100 <[email protected]>
147+
// @match *://*/*
148+
// @run-at document-start
149+
// @require file://D:/workspace/userscript-template/dist/index.js
150+
// ==/UserScript==
151+
(() => {})();
152+
```
153+
154+
Please note that when you debug using the method `// @require file://D:/workspace/userscript-template/dist/index.js`, your Tampermonkey extension should be configured to allow access to file URLs (by default, it is not allowed). Right-click on the browser plugin icon and select "Manage Extensions":
155+
156+
![image-20240723005213833](./README.assets/image-20240723005213833.png)
157+
158+
Make sure that the "Allow access to file URLs" switch is turned on; otherwise, `@require` will not be able to reference local files:
159+
160+
![image-20240723005321887](./README.assets/image-20240723005321887.png)
161+
162+
You might notice that when you run `npm run watch`, the command does not exit after compiling the code but instead enters a waiting state. Yes, just as its name suggests, it activates a `watch` mode. When you modify the source code files, `webpack` will recompile your code for you. All you need to do is directly modify your source code files, make the changes, then switch to the browser and refresh the page for the changes to take effect! (There is no automatic browser refresh introduced here. Is it necessary? To be honest, it is necessary, but I don't really know how to set it up, so let's just make do with what we have....)
163+
164+
When you need to publish:
165+
166+
```bash
167+
npm run build
168+
```
169+
170+
Then simply take the `./dist/index.js` file and publish it.
171+
172+
173+
174+
175+
176+
177+

0 commit comments

Comments
 (0)