build/fixtures/README.md

   1 # jQuery
   2
   3 > jQuery is a fast, small, and feature-rich JavaScript library.
   4
   5 For information on how to get started and how to use jQuery, please see [jQuery's documentation](https://api.jquery.com/).
   6 For source files and issues, please visit the [jQuery repo](https://github.com/jquery/jquery).
   7
   8 If upgrading, please see the [blog post for @VERSION](@BLOG_POST_LINK). This includes notable differences from the previous version and a more readable changelog.
   9
  10 ## Including jQuery
  11
  12 Below are some of the most common ways to include jQuery.
  13
  14 ### Browser
  15
  16 #### Script tag
  17
  18 ```html
  19 <script src="https://code.jquery.com/jquery-@VERSION.min.js"></script>
  20 ```
  21
  22 or, to use the jQuery ECMAScript module:
  23
  24 ```html
  25 <script type="module">
  26         import $ from "https://code.jquery.com/jquery-@VERSION.min.js";
  27 </script>
  28 ```
  29
  30 Sometimes you don’t need AJAX, or you prefer to use one of the many standalone libraries that focus on AJAX requests. And often it is simpler to use a combination of CSS, class manipulation or the Web Animations API. Similarly, many projects opt into relying on native browser promises instead of jQuery Deferreds. Along with the regular version of jQuery that includes the `ajax`, `callbacks`, `deferred`, `effects` & `queue` modules, we’ve released a “slim” version that excludes these modules. You can load it as a regular script:
  31
  32 ```html
  33 <script src="https://code.jquery.com/jquery-@VERSION.slim.min.js"></script>
  34 ```
  35
  36 or as a module:
  37
  38 ```html
  39 <script type="module">
  40         import $ from "https://code.jquery.com/jquery-@VERSION.slim.min.js";
  41 </script>
  42 ```
  43
  44 #### Import maps
  45
  46 To avoid repeating long import paths that change on each jQuery release, you can use import maps - they are now supported in every modern browser. Put the following script tag before any `<script type="module">`:
  47
  48 ```html
  49 <script type="importmap">
  50         {
  51                 "imports": {
  52                         "jquery": "https://code.jquery.com/jquery-@VERSION.min.js",
  53                         "jquery/slim": "https://code.jquery.com/jquery-@VERSION.slim.min.js"
  54                 }
  55         }
  56 </script>
  57 ```
  58
  59 Now, the following will work to get the full version:
  60
  61 ```html
  62 <script type="module">
  63         import $ from "jquery";
  64         // Use $ here
  65 </script>
  66 ```
  67
  68 and the following to get the slim one:
  69
  70 ```html
  71 <script type="module">
  72         import $ from "jquery/slim";
  73         // Use $ here
  74 </script>
  75 ```
  76
  77 The advantage of these specific mappings is they match the ones embedded in the jQuery npm package, providing better interoperability between the environments.
  78
  79 You can also use jQuery from npm even in the browser setup. Read along for more details.
  80
  81 ### Using jQuery from npm
  82
  83 There are several ways to use jQuery from npm. One is to use a build tool like [Webpack](https://webpack.js.org/), [Browserify](http://browserify.org/) or [Babel](https://babeljs.io/). For more information on using these tools, please refer to the corresponding project's documentation.
  84
  85 Another way is to use jQuery directly in Node.js. See the [Node.js pre-requisites](#nodejs-pre-requisites) section for more details on the Node.js-specific part of this.
  86
  87 To install the jQuery npm package, invoke:
  88
  89 ```sh
  90 npm install jquery
  91 ```
  92
  93 In the script, including jQuery will usually look like this:
  94
  95 ```js
  96 import $ from "jquery";
  97 ```
  98
  99 If you need to use jQuery in a file that's not an ECMAScript module, you can use the CommonJS syntax:
 100
 101 ```js
 102 const $ = require( "jquery" );
 103 ```
 104
 105 #### Individual modules
 106
 107 jQuery is authored in ECMAScript modules; it's also possible to use them directly. They are contained in the `src/` folder; inspect the package contents to see what's there. Full file names are required, including the `.js` extension.
 108
 109 Be aware that this is an advanced & low-level interface, and we don't consider it stable, even between minor or patch releases - this is especially the case for modules in subdirectories or `src/`. If you rely on it, verify your setup before updating jQuery.
 110
 111 All top-level modules, i.e. files directly in the `src/` directory export jQuery. Importing multiple modules will all attach to the same jQuery instance.
 112
 113 Remember that some modules have other dependencies (e.g. the `event` module depends on the `selector` one) so in some cases you may get more than you expect.
 114
 115 Example usage:
 116
 117 ```js
 118 import $ from "jquery/src/css.js"; // adds the `.css()` method
 119 import "jquery/src/event.js"; // adds the `.on()` method; pulls "selector" as a dependency
 120 $( ".toggle" ).on( "click", function() {
 121         $( this ).css( "color", "red" );
 122 } );
 123 ```
 124
 125 ### AMD (Asynchronous Module Definition)
 126
 127 AMD is a module format built for the browser. For more information, we recommend [require.js' documentation](https://requirejs.org/docs/whyamd.html).
 128
 129 ```js
 130 define( [ "jquery" ], function( $ ) {
 131
 132 } );
 133 ```
 134
 135 Node.js doesn't understand AMD natively so this method is mostly used in a browser setup.
 136
 137 ### Node.js pre-requisites
 138
 139 For jQuery to work in Node, a window with a document is required. Since no such window exists natively in Node, one can be mocked by tools such as [jsdom](https://github.com/jsdom/jsdom). This can be useful for testing purposes.
 140
 141 jQuery checks for a `window` global with a `document` property and - if one is not present, as is the default in Node.js - it returns a factory accepting a `window` as a parameter instead.
 142
 143 To `import` jQuery using this factory, use the following:
 144
 145 ```js
 146 import { JSDOM } from "jsdom";
 147 const { window } = new JSDOM( "" );
 148 import jQueryFactory from "jquery";
 149 const $ = jQueryFactory( window );
 150 ```
 151
 152 or, if you use `require`:
 153
 154 ```js
 155 const { JSDOM } = require( "jsdom" );
 156 const { window } = new JSDOM( "" );
 157 const $ = require( "jquery" )( window );
 158 ```
 159
 160 If the `window` global is present at the moment of the `import` or `require` of `"jquery"`, it will resolve to a jQuery instance, as in the browser. You can set such a global manually to simulate the behavior; with `import`:
 161
 162 ```js
 163 import { JSDOM } from "jsdom";
 164 const { window } = new JSDOM( "" );
 165 globalThis.window = window;
 166 const { default: $ } = await import( "jquery" );
 167 ```
 168
 169 or with `require`:
 170
 171 ```js
 172 const { JSDOM } = require( "jsdom" );
 173 const { window } = new JSDOM( "" );
 174 globalThis.window = window;
 175 const $ = require( "jquery" );
 176 ```
 177
 178 #### Slim build in Node.js
 179
 180 To use the slim build of jQuery in Node.js, use `"jquery/slim"` instead of `"jquery"` in both `require` or `import` calls above.