jQuery Deployment and Usage Guide

Prerequisites

Before building jQuery from source, ensure you have the following installed:

• Node.js (latest stable version) and npm
• Git 1.7 or later

Platform-Specific Installation

Windows:

• Download and install Git and Node.js

macOS:

# Install Homebrew first, then:
brew install git
brew install node

Linux/BSD: Use your distribution's package manager (e.g., apt, yum, pacman) to install git and nodejs, or build from source.

Installation

1. Clone the jQuery repository:

git clone https://github.com/jquery/jquery.git
cd jquery

2. Install dependencies:

npm install

Configuration

jQuery requires no environment variables or configuration files for standard builds. Build customization is handled via command-line flags.

Build Options

View all available build options:

npm run build -- --help

Build & Run

Standard Build

Create the default jQuery distribution files:

npm run build

This generates:

• dist/jquery.js (development version)
• dist/jquery.min.js (minified)
• dist/jquery.min.map (source map)

Build All Variants

To build all release variants including ECMAScript modules:

npm run build:all

This creates:

• UMD builds (dist/):
  • jquery.js / jquery.min.js
  • jquery.slim.js / jquery.slim.min.js (excludes ajax/effects)
• ES Module builds (dist-module/):
  • jquery.module.js
  • jquery.slim.module.js

Custom Builds

Exclude specific modules to reduce file size (cannot exclude core):

# Exclude AJAX functionality
npm run build -- --exclude ajax

# Exclude multiple modules
npm run build -- --exclude ajax --exclude effects --exclude deprecated

# Include only specific modules (drops defaults)
npm run build -- --include core --include selector --include event

Available modules for exclusion:

• ajax - All AJAX functionality ($.ajax(), $.get(), $.post(), etc.)
• ajax/xhr - XMLHTTPRequest transport only
• ajax/script - <script> transport only
• ajax/jsonp - JSONP transport only
• css - .css() method (also removes dependent modules: effects, dimensions, offset)
• css/showHide - Non-animated .show(), .hide(), .toggle()
• deprecated - Methods marked as deprecated
• dimensions - .width(), .height() and inner/outer variants
• effects - .animate() and shorthands (.slideUp(), .hide("slow"), etc.)
• event - Event system (.on(), .off())
• event/trigger - .trigger() and .triggerHandler()
• offset - Position/offset methods
• wrap - Wrapping methods (.wrap(), .wrapAll(), .unwrap())

Note: When excluding selector, it is replaced with a wrapper around native querySelectorAll rather than removed.

Deployment

Using jQuery in Projects

Via CDN (Production):

<!-- Full version -->
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>

<!-- Slim version (no AJAX/effects) -->
<script src="https://code.jquery.com/jquery-3.7.1.slim.min.js"></script>

Via npm:

npm install jquery

Then import in your application:

// ES Modules
import $ from 'jquery';

// CommonJS
const $ = require('jquery');

Local File Inclusion: Copy built files from dist/ or dist-module/ to your project's static assets directory.

Publishing Built Versions

For maintainers distributing custom builds:

1. Test the build:

npm test

2. Create distribution package:

npm pack

3. Publish to npm registry (requires appropriate permissions):

npm publish

Version Selection

Switch to specific version branches before building:

git checkout 3.x-stable  # For stable 3.x
git checkout main        # For 4.x beta

Troubleshooting

Build Failures

Issue: npm install fails with Node version errors Solution: Upgrade to the latest Node.js LTS version:

# Check current version
node --version

# Update via official installer or nvm
nvm install node

Issue: Git errors during clone Solution: Ensure Git 1.7+ is installed:

git --version

Issue: Missing dist/ directory after build Solution: Ensure the build completed successfully. Check for errors in output and verify write permissions in the jquery directory.

Module Exclusion Errors

Issue: Build fails when excluding certain modules Solution: Some modules have dependencies. Excluding css automatically excludes effects, dimensions, and offset. Do not specify dependent modules for exclusion individually.

Issue: selector exclusion not working as expected Solution: When excluding selector, jQuery replaces it with a querySelectorAll wrapper rather than removing it entirely. This is expected behavior to maintain API compatibility.

Runtime Issues

Issue: jQuery not loading in browser Solution:

• Verify the script tag path matches the built file location
• Check browser console for 404 errors
• Ensure you're loading the UMD version (dist/jquery.js) for browser environments, not the ES module version (dist-module/)

Issue: AJAX calls failing in local file system (file:// protocol) Solution: jQuery AJAX requires a web server (http/https protocol). Use a local development server:

npx serve .
# or
python -m http.server 8000