@@ -22,18 +22,24 @@ Table of Contents:
2222
2323Ensure that the following software is installed on your computer:
2424
25- - [ Node.js] [ nodejs ] (we recommend using the latest LTS version)
26- - [ Yarn] [ yarn ]
27- - [ Git] [ git ]
25+ - [ Node.js] [ nodejs ] : v22 (you can install multiple versions using [ nvm] [ nvm ] )
26+ - [ pnpm] [ pnpm ] : v10
2827- [ VSCode] [ vscode ]
28+ - [ Git] [ git ]
29+
30+ [ git ] : https://git-scm.com/
31+ [ nodejs ] : https://nodejs.org/en/download
32+ [ nvm ] : https://github.com/nvm-sh/nvm
33+ [ pnpm ] : https://pnpm.io/installation
2934
3035## Initial setup
3136
3237After cloning the repository, follow these steps to initialize the project:
3338
34- 1 . Install dependencies by calling ` yarn ` . This will also install client and server dependencies via ` postinstall `
35- scripts. After installation, it will initialize [ Husky Git hooks] [ husky ] through the ` prepare ` script.
36- 1 . Install recommended VSCode extensions (refer to the [ ` .vscode/extensions.json ` ] [ vscode-extensions-file ] file).
39+ 1 . Install dependencies by calling ` pnpm install ` .
40+ This will also install client and server dependencies via ` postinstall ` scripts.
41+ After installation, it will initialize [ Husky Git hooks] [ husky ] through the ` prepare ` script.
42+ 2 . Install recommended VSCode extensions (refer to the [ ` .vscode/extensions.json ` ] [ vscode-extensions-file ] file).
3743 ** These extensions are REQUIRED for the development process.**
3844
3945## Project structure
@@ -76,7 +82,7 @@ If you've made changes to the extension code and want to test them, follow these
7682
7783To create a production build of the extension:
7884
79- 1 . Run ` yarn build:prod` command. This generates a production build and a ` .vsix ` file in the ` out ` folder.
85+ 1 . Run ` pnpm build:prod` command. This generates a production build and a ` .vsix ` file in the ` out ` folder.
80861 . To ensure the build is correct, install the generated ` .vsix ` file in VSCode. Open the command palette
8187 (` Ctrl + Shift + P ` ), select "Extensions: Install from VSIX...", and choose the ` vscode-adblock.vsix ` file.
8288
@@ -101,7 +107,7 @@ To create a production build of the extension:
1011071 . Update the TM grammar in the ` syntaxes/adblock.yaml-tmLanguage ` file.
1021081 . Create/modify example rules in the ` test/static/rules ` folder. Add link for GitHub issues to rules if related to some
103109 issue.
104- 1 . Create/modify unit tests in ` test/grammar ` . Ensure tests pass by running ` yarn test` .
110+ 1 . Create/modify unit tests in ` test/grammar ` . Ensure tests pass by running ` pnpm test` .
105111
106112> [ !TIP]
107113> Open the ` test/static ` folder in the "Extension Development Host" window and you can check the syntax highlighting
@@ -114,39 +120,39 @@ To create a production build of the extension:
114120
115121During development, you can use the following commands (listed in ` package.json ` ).
116122
117- - ` yarn build:grammar` - Compiles the TextMate (TM) grammar into a PList format, since VSCode does not natively support
123+ - ` pnpm build:grammar` - Compiles the TextMate (TM) grammar into a PList format, since VSCode does not natively support
118124 YAML grammars.
119- - ` yarn build:prod` - Generates a production build of the extension, including a ` .vsix ` file in the ` out ` directory for
125+ - ` pnpm build:prod` - Generates a production build of the extension, including a ` .vsix ` file in the ` out ` directory for
120126 VSCode installation.
121- - ` yarn build:txt` - Creates a ` build.txt ` file in the out directory containing the current version number, primarily
127+ - ` pnpm build:txt` - Creates a ` build.txt ` file in the out directory containing the current version number, primarily
122128 for Continuous Integration (CI) purposes.
123- - ` yarn build:vsix` - Produces a ` .vsix ` file in the out directory, which is used to install the extension in VSCode.
124- - ` yarn clean` - Removes all generated files in the output directories, cleaning up the build results.
125- - ` yarn esbuild:aglint` - Base ESBuild command for building integrated AGLint with the common options.
126- - ` yarn esbuild:agtree` - Base ESBuild command for building integrated AGTree with the common options.
129+ - ` pnpm build:vsix` - Produces a ` .vsix ` file in the out directory, which is used to install the extension in VSCode.
130+ - ` pnpm clean` - Removes all generated files in the output directories, cleaning up the build results.
131+ - ` pnpm esbuild:aglint` - Base ESBuild command for building integrated AGLint with the common options.
132+ - ` pnpm esbuild:agtree` - Base ESBuild command for building integrated AGTree with the common options.
127133 Integrated AGTree comes with the integrated AGLint, this command just helps to bundle it to a separate file.
128134 This is needed because AGTree is also used by the server, and by bundling it to a separate file, we can avoid
129135 double-bundling AGTree.
130- - ` yarn esbuild:server` - Base ESBuild command for building the server with the common options.
131- - ` yarn esbuild:client` - Base ESBuild command for building the client with the common options.
132- - ` yarn extract-changelog` - Extract changes from the ` CHANGELOG.md ` for a specific version. Typically, this is used by
136+ - ` pnpm esbuild:server` - Base ESBuild command for building the server with the common options.
137+ - ` pnpm esbuild:client` - Base ESBuild command for building the client with the common options.
138+ - ` pnpm extract-changelog` - Extract changes from the ` CHANGELOG.md ` for a specific version. Typically, this is used by
133139 CI.
134- - ` yarn increment` - Increment the patch version number of the extension in the ` package.json ` file. Typically, this is
140+ - ` pnpm increment` - Increment the patch version number of the extension in the ` package.json ` file. Typically, this is
135141 used by CI.
136- - ` yarn lint:md` - Lint the markdown files with [ markdownlint] [ markdownlint ] .
137- - ` yarn lint:staged` - Run linters on staged files. Typically, this is used by Husky Git hooks.
138- - ` yarn lint:ts` - Lint the code with [ ESLint] [ eslint ] .
139- - ` yarn lint` - Run all linters.
140- - ` yarn test:compile` - Check if the code compiles with [ TypeScript] [ typescript ] .
141- - ` yarn test` - Run tests with [ Jest] [ jest ] .
142- - ` yarn watch:aglint` - Watch for changes in the AGLint code and create a development build automatically.
143- - ` yarn watch:agtree` - Watch for changes in the AGTree code and create a development build automatically.
144- - ` yarn watch:client` - Watch for changes in the client code and create a development build automatically.
145- - ` yarn watch:grammar` - Watch for changes in the TM grammar and rebuild it automatically.
146- - ` yarn watch:server` - Watch for changes in the server code and create a development build automatically.
142+ - ` pnpm lint:md` - Lint the markdown files with [ markdownlint] [ markdownlint ] .
143+ - ` pnpm lint:staged` - Run linters on staged files. Typically, this is used by Husky Git hooks.
144+ - ` pnpm lint:ts` - Lint the code with [ ESLint] [ eslint ] .
145+ - ` pnpm lint` - Run all linters.
146+ - ` pnpm test:compile` - Check if the code compiles with [ TypeScript] [ typescript ] .
147+ - ` pnpm test` - Run tests with [ Jest] [ jest ] .
148+ - ` pnpm watch:aglint` - Watch for changes in the AGLint code and create a development build automatically.
149+ - ` pnpm watch:agtree` - Watch for changes in the AGTree code and create a development build automatically.
150+ - ` pnpm watch:client` - Watch for changes in the client code and create a development build automatically.
151+ - ` pnpm watch:grammar` - Watch for changes in the TM grammar and rebuild it automatically.
152+ - ` pnpm watch:server` - Watch for changes in the server code and create a development build automatically.
147153
148154> [ !NOTE]
149- > Watch commands (e.g., ` yarn watch:client` ) are typically used by VSCode tasks (see
155+ > Watch commands (e.g., ` pnpm watch:client` ) are typically used by VSCode tasks (see
150156> [ ` .vscode/tasks.json ` ] [ vscode-tasks-file ] file and
151157> [ * Running the extension in development mode* ] ( #running-the-extension-in-development-mode ) section).
152158> In most cases, you don't need to run them manually.
@@ -168,11 +174,9 @@ Explore the following links for more information on development:
168174[ contribute ] : https://adguard.com/contribute.html
169175[ esbuild-problem-matcher-extension ] : https://marketplace.visualstudio.com/items?itemName=connor4312.esbuild-problem-matchers
170176[ eslint ] : https://eslint.org/
171- [ git ] : https://git-scm.com/
172177[ husky ] : https://typicode.github.io/husky
173178[ jest ] : https://jestjs.io/
174179[ markdownlint ] : https://github.com/DavidAnson/markdownlint
175- [ nodejs ] : https://nodejs.org/en/
176180[ nova-light-show ] : https://novalightshow.netlify.app/
177181[ server-dir ] : ./server
178182[ syntaxes-dir ] : ./syntaxes
@@ -187,4 +191,3 @@ Explore the following links for more information on development:
187191[ vscode-problem-matcher-docs ] : https://code.visualstudio.com/docs/editor/tasks#_processing-task-output-with-problem-matchers
188192[ vscode-tasks-file ] : ./.vscode/tasks.json
189193[ vscode ] : https://code.visualstudio.com/
190- [ yarn ] : https://yarnpkg.com/
0 commit comments