1 [jQuery](https://jquery.

com/) — New Wave JavaScript

2 ==================================================
3
4 Meetings are currently held on the [matrix.org
platform](https://matrix.to/#/#jquery_meeting:gitter.im).
5
6 Meeting minutes can be found at
[meetings.jquery.org](https://meetings.jquery.org/category/core/).
7
8 Contribution Guides
9 --------------------------------------
10
11 In the spirit of open source software development, jQuery always encourages community
code contribution. To help you get started and before you jump into writing code, be
sure to read these important contribution guidelines thoroughly:
12
13 1. [Getting Involved](https://contribute.jquery.org/)
14 2. [Core Style Guide](https://contribute.jquery.org/style-guide/js/)
15 3. [Writing Code for jQuery Foundation Projects](https://contribute.jquery.org/code/)
16
17 ### References to issues/PRs
18
19 GitHub issues/PRs are usually referenced via `gh-NUMBER`, where `NUMBER` is the
numerical ID of the issue/PR. You can find such an issue/PR under
`https://github.com/jquery/jquery/issues/NUMBER`.
20
21 jQuery has used a different bug tracker - based on Trac - in the past, available
under [bugs.jquery.com](https://bugs.jquery.com/). It is being kept in read only mode
so that referring to past discussions is possible. When jQuery source references one
of those issues, it uses the pattern `trac-NUMBER`, where `NUMBER` is the numerical
ID of the issue. You can find such an issue under
`https://bugs.jquery.com/ticket/NUMBER`.
22
23
24 Environments in which to use jQuery
25 --------------------------------------
26
27 - [Browser support](https://jquery.com/browser-support/)
28 - jQuery also supports Node, browser extensions, and other non-browser environments.
29
30
31 What you need to build your own jQuery
32 --------------------------------------
33
34 To build jQuery, you need to have the latest Node.js/npm and git 1.7 or later.
Earlier versions might work, but are not supported.
35
36 For Windows, you have to download and install [git](https://git-scm.com/downloads)
and [Node.js](https://nodejs.org/en/download/).
37
38 macOS users should install [Homebrew](https://brew.sh/). Once Homebrew is installed,
run `brew install git` to install git,
39 and `brew install node` to install Node.js.
40
41 Linux/BSD users should use their appropriate package managers to install git and
Node.js, or build from source
42 if you swing that way. Easy-peasy.
43
44
45 How to build your own jQuery
46 ----------------------------
47
48 First, [clone the jQuery git
repo](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cl
oning-a-repository).
49
50 Then, enter the jquery directory and run the build script:
51 ```bash
52 cd jquery && npm run build
53 ```
54 The built version of jQuery will be put in the `dist/` subdirectory, along with the
minified copy and associated map file.
55
 56 If you want to create custom build or help with jQuery development, it would be
better to install [grunt command line
interface](https://github.com/gruntjs/grunt-cli) as a global package:
57
58 ```
59 npm install -g grunt-cli
60 ```
61 Make sure you have `grunt` installed by testing:
62 ```
63 grunt -V
64 ```
65
66 Now by running the `grunt` command, in the jquery directory, you can build a full
version of jQuery, just like with an `npm run build` command:
67 ```
68 grunt
69 ```
70
71 There are many other tasks available for jQuery Core:
72 ```
73 grunt -help
74 ```
75
76 ### Modules
77
78 Special builds can be created that exclude subsets of jQuery functionality.
79 This allows for smaller custom builds when the builder is certain that those parts of
jQuery are not being used.
80 For example, an app that only used JSONP for `$.ajax()` and did not need to calculate
offsets or positions of elements could exclude the offset and ajax/xhr modules.
81
82 Any module may be excluded except for `core`, and `selector`. To exclude a module,
pass its path relative to the `src` folder (without the `.js` extension).
83
84 Some example modules that can be excluded are:
85
86 - **ajax**: All AJAX functionality: `$.ajax()`, `$.get()`, `$.post()`,
`$.ajaxSetup()`, `.load()`, transports, and ajax event shorthands such as
`.ajaxStart()`.
87 - **ajax/xhr**: The XMLHTTPRequest AJAX transport only.
88 - **ajax/script**: The `<script>` AJAX transport only; used to retrieve scripts.
89 - **ajax/jsonp**: The JSONP AJAX transport only; depends on the ajax/script transport.
90 - **css**: The `.css()` method. Also removes **all** modules depending on css
(including **effects**, **dimensions**, and **offset**).
91 - **css/showHide**: Non-animated `.show()`, `.hide()` and `.toggle()`; can be
excluded if you use classes or explicit `.css()` calls to set the `display` property.
Also removes the **effects** module.
92 - **deprecated**: Methods documented as deprecated but not yet removed.
93 - **dimensions**: The `.width()` and `.height()` methods, including `inner-` and
`outer-` variations.
94 - **effects**: The `.animate()` method and its shorthands such as `.slideUp()` or
`.hide("slow")`.
95 - **event**: The `.on()` and `.off()` methods and all event functionality.
96 - **event/trigger**: The `.trigger()` and `.triggerHandler()` methods.
97 - **offset**: The `.offset()`, `.position()`, `.offsetParent()`, `.scrollLeft()`, and
`.scrollTop()` methods.
98 - **wrap**: The `.wrap()`, `.wrapAll()`, `.wrapInner()`, and `.unwrap()` methods.
99 - **core/ready**: Exclude the ready module if you place your scripts at the end of
the body. Any ready callbacks bound with `jQuery()` will simply be called
immediately. However, `jQuery(document).ready()` will not be a function and
`.on("ready", ...)` or similar will not be triggered.
100 - **deferred**: Exclude jQuery.Deferred. This also removes jQuery.Callbacks. *Note*
that modules that depend on jQuery.Deferred(AJAX, effects, core/ready) will not be
removed and will still expect jQuery.Deferred to be there. Include your own
jQuery.Deferred implementation or exclude those modules as well (`grunt
custom:-deferred,-ajax,-effects,-core/ready`).
101 - **exports/global**: Exclude the attachment of global jQuery variables ($ and
jQuery) to the window.
102 - **exports/amd**: Exclude the AMD definition.
103
104 As a special case, you may also replace the full jQuery `selector` module by using a
special flag `grunt custom:-selector`.
105
106 - **selector**: The full jQuery selector engine. When this module is excluded, it is
replaced by a rudimentary selector engine based on the browser's `querySelectorAll`
method that does not support jQuery selector extensions or enhanced semantics. See
the
[selector-native.js](https://github.com/jquery/jquery/blob/main/src/selector-native.js
) file for details.
107
108 *Note*: Excluding the full `selector` module will also exclude all jQuery selector
extensions (such as `effects/animatedSelector` and `css/hiddenVisibleSelectors`).
109
110 The build process shows a message for each dependent module it excludes or includes.
111
112 ##### AMD name
113
114 As an option, you can set the module name for jQuery's AMD definition. By default, it
is set to "jquery", which plays nicely with plugins and third-party libraries, but
there may be cases where you'd like to change this. Simply set the `"amd"` option:
115
116 ```bash
117 grunt custom --amd="custom-name"
118 ```
119
120 Or, to define anonymously, set the name to an empty string.
121
122 ```bash
123 grunt custom --amd=""
124 ```
125
126 #### Custom Build Examples
127
128 To create a custom build, first check out the version:
129
130 ```bash
131 git pull; git checkout VERSION
132 ```
133
134 Where VERSION is the version you want to customize. Then, make sure all Node
dependencies are installed:
135
136 ```bash
137 npm install
138 ```
139
140 Create the custom build using the `grunt custom` option, listing the modules to be
excluded.
141
142 Exclude all **ajax** functionality:
143
144 ```bash
145 grunt custom:-ajax
146 ```
147
148 Excluding **css** removes modules depending on CSS: **effects**, **offset**,
**dimensions**.
149
150 ```bash
151 grunt custom:-css
152 ```
153
154 Exclude a bunch of modules:
155
156 ```bash
157 grunt custom:-ajax/jsonp,-css,-deprecated,-dimensions,-effects,-offset,-wrap
158 ```
159
160 There is also a special alias to generate a build with the same configuration as the
official jQuery Slim build is generated:
161 ```bash
162 grunt custom:slim
163 ```
164
165 For questions or requests regarding custom builds, please start a thread on the
[Developing jQuery Core](https://forum.jquery.com/developing-jquery-core) section of
 the forum. Due to the combinatorics and custom nature of these builds, they are not
regularly tested in jQuery's unit test process.
166
167 Running the Unit Tests
168 --------------------------------------
169
170 Make sure you have the necessary dependencies:
171
172 ```bash
173 npm install
174 ```
175
176 Start `grunt watch` or `npm start` to auto-build jQuery as you work:
177
178 ```bash
179 grunt watch
180 ```
181
182
183 Run the unit tests with a local server that supports PHP. Ensure that you run the
site from the root directory, not the "test" directory. No database is required.
Pre-configured php local servers are available for Windows and Mac. Here are some
options:
184
185 - Windows: [WAMP download](http://www.wampserver.com/en/)
186 - Mac: [MAMP download](https://www.mamp.info/en/downloads/)
187 - Linux: [Setting up
LAMP](https://www.linux.com/training-tutorials/easy-lamp-server-installation/)
188 - [Mongoose (most platforms)](https://code.google.com/p/mongoose/)
189
190
191
192
193 Building to a different directory
194 ---------------------------------
195
196 To copy the built jQuery files from `/dist` to another directory:
197
198 ```bash
199 grunt && grunt dist:/path/to/special/location/
200 ```
201 With this example, the output files would be:
202
203 ```bash
204 /path/to/special/location/jquery.js
205 /path/to/special/location/jquery.min.js
206 ```
207
208 To add a permanent copy destination, create a file in `dist/` called
".destination.json". Inside the file, paste and customize the following:
209
210 ```json
211
212 {
213 "/Absolute/path/to/other/destination": true
214 }
215 ```
216
217 Additionally, both methods can be combined.
218
219
220
221 Essential Git
222 -------------
223
224 As the source code is handled by the Git version control system, it's useful to know
some features used.
225
226 ### Cleaning ###
227
228 If you want to purge your working directory back to the status of upstream, the
following commands can be used (remember everything you've worked on is gone after
these):
229
230 ```bash
231 git reset --hard upstream/main
232 git clean -fdx
233 ```
234
235 ### Rebasing ###
236
237 For feature/topic branches, you should always use the `--rebase` flag to `git pull`,
or if you are usually handling many temporary "to be in a github pull request"
branches, run the following to automate this:
238
239 ```bash
240 git config branch.autosetuprebase local
241 ```
242 (see `man git-config` for more information)
243
244 ### Handling merge conflicts ###
245
246 If you're getting merge conflicts when merging, instead of editing the conflicted
files manually, you can use the feature
247 `git mergetool`. Even though the default tool `xxdiff` looks awful/old, it's rather
useful.
248
249 The following are some commands that can be used there:
250
251 * `Ctrl + Alt + M` - automerge as much as possible
252 * `b` - jump to next merge conflict
253 * `s` - change the order of the conflicted lines
254 * `u` - undo a merge
255 * `left mouse button` - mark a block to be the winner
256 * `middle mouse button` - mark a line to be the winner
257 * `Ctrl + S` - save
258 * `Ctrl + Q` - quit
259
260 [QUnit](https://api.qunitjs.com) Reference
261 -----------------
262
263 ### Test methods ###
264
265 ```js
266 expect( numAssertions );
267 stop();
268 start();
269 ```
270
271
272 *Note*: QUnit's eventual addition of an argument to stop/start is ignored in this
test suite so that start and stop can be passed as callbacks without worrying about
their parameters.
273
274 ### Test assertions ###
275
276
277 ```js
278 ok( value, [message] );
279 equal( actual, expected, [message] );
280 notEqual( actual, expected, [message] );
281 deepEqual( actual, expected, [message] );
282 notDeepEqual( actual, expected, [message] );
283 strictEqual( actual, expected, [message] );
284 notStrictEqual( actual, expected, [message] );
285 throws( block, [expected], [message] );
286 ```
287
288
289 Test Suite Convenience Methods Reference (See
[test/data/testinit.js](https://github.com/jquery/jquery/blob/main/test/data/testinit.
js))
290 ------------------------------
291
292 ### Returns an array of elements with the given IDs ###
293
294 ```js
295 q( ... );
296 ```
297
298 Example:
299
300 ```js
301 q("main", "foo", "bar");
302
303 => [ div#main, span#foo, input#bar ]
304 ```
305
306 ### Asserts that a selection matches the given IDs ###
307
308 ```js
309 t( testName, selector, [ "array", "of", "ids" ] );
310 ```
311
312 Example:
313
314 ```js
315 t("Check for something", "//[a]", ["foo", "bar"]);
316 ```
317
318
319
320 ### Fires a native DOM event without going through jQuery ###
321
322 ```js
323 fireNative( node, eventType )
324 ```
325
326 Example:
327
328 ```js
329 fireNative( jQuery("#elem")[0], "click" );
330 ```
331
332 ### Add random number to url to stop caching ###
333
334 ```js
335 url( "some/url" );
336 ```
337
338 Example:
339
340 ```js
341 url("index.html");
342
343 => "data/index.html?10538358428943"
344
345
346 url("mock.php?foo=bar");
347
348 => "data/mock.php?foo=bar&10538358345554"
349 ```
350
351
352 ### Run tests in an iframe ###
353
354 Some tests may require a document other than the standard test fixture, and
355 these can be run in a separate iframe. The actual test code and assertions
356 remain in jQuery's main test files; only the minimal test fixture markup
357 and setup code should be placed in the iframe file.
358
359 ```js
360 testIframe( testName, fileName,
361 function testCallback(
362 assert, jQuery, window, document,
363 [ additional args ] ) {
364 ...
365 } );
366 ```
367
368 This loads a page, constructing a url with fileName `"./data/" + fileName`.
369 The iframed page determines when the callback occurs in the test by
370 including the "/test/data/iframeTest.js" script and calling
371 `startIframeTest( [ additional args ] )` when appropriate. Often this
372 will be after either document ready or `window.onload` fires.
373
374 The `testCallback` receives the QUnit `assert` object created by `testIframe`
375 for this test, followed by the global `jQuery`, `window`, and `document` from
376 the iframe. If the iframe code passes any arguments to `startIframeTest`,
377 they follow the `document` argument.
378
379
380 Questions?
381 ----------
382
383 If you have any questions, please feel free to ask on the
384 [Developing jQuery Core forum](https://forum.jquery.com/developing-jquery-core) or in
#jquery on [libera](https://web.libera.chat/).