jQuery Mobile Framework - Deploy & Usage Guide

Prerequisites

Before getting started, ensure you have the following installed:

• Node.js - Required for building and development
• Grunt CLI - Task runner for building the project
• Apache with PHP 5+ - Required for development and testing (optional for production use)
• Apache modules: Rewrite (mod_rewrite.so), Expire (mod_expires.so), Header (mod_headers.so)

Installation

1. Clone the repository:

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

2. Install dependencies:

   npm install
   

3. Install Grunt CLI globally (if not already installed):

   npm install -g grunt-cli
   

Configuration

jQuery Mobile doesn't require specific environment variables or API keys for basic usage. However, for development:

• Web Server Setup: Point your Apache server to the project directory
• PHP: Ensure PHP 5+ is configured and accessible by Apache
• Virtual Machine: If using Vagrant, add the remote/branch https://github.com/johnbender/jquery-mobile/tree/vagrant and run vagrant up

Build & Run

Development Build

Run the default build target to compile JavaScript and CSS:

grunt

This will:

• Resolve dependencies
• Build, concat, and minify JavaScript
• Build, concat, and minify CSS files
• Prepare documentation for static consumption

Custom Build Targets

Available build targets:

• JavaScript only: grunt build:js
• CSS only: grunt build:css
• Demos: grunt build:demos
• Linting: grunt lint

Running Locally

For development, start your Apache server and navigate to the project directory in your browser. The documentation and demos are accessible through the web interface.

Production Usage

For production, include the pre-built files from the dist directory:

• CSS: dist/jquery.mobile.css
• JavaScript: dist/jquery.mobile.js

Deployment

jQuery Mobile is a client-side framework that can be deployed on any static hosting platform:

Recommended Platforms

1. Static Hosting Services:

   • Netlify
   • Vercel
   • GitHub Pages
   • AWS S3 + CloudFront
   • Firebase Hosting

2. Traditional Web Hosting:

   • Apache/Nginx servers
   • cPanel-based hosting

Deployment Steps

1. Build the project for production:

   grunt build
   

2. Copy the contents of the dist directory to your hosting server

3. Ensure jQuery Core (version 1.8.3 to 1.11.1 / 2.1.1) is available on your pages

4. Include the CSS and JavaScript files in your HTML:

   <link rel="stylesheet" href="jquery.mobile.css">
   <script src="jquery.js"></script>
   <script src="jquery.mobile.js"></script>
   

Troubleshooting

Common Issues and Solutions

Build Failures

• Issue: grunt command not found

  • Solution: Ensure Grunt CLI is installed globally with npm install -g grunt-cli

• Issue: Build errors related to dependencies

  • Solution: Run npm install to ensure all dependencies are installed

Development Server Issues

• Issue: Documentation pages not loading

  • Solution: Verify Apache is running and PHP 5+ is properly configured

• Issue: Test suite not running

  • Solution: Ensure Apache modules (Rewrite, Expire, Header) are enabled

Browser Compatibility

• Issue: jQuery Mobile not working in older browsers
  • Solution: jQuery Mobile 1.4.x requires jQuery Core 1.8.3 to 1.11.1 / 2.1.1. Ensure you're using a compatible version

Custom Builds

• Issue: Custom theme not appearing
  • Solution: After creating a custom theme, run THEME=my-theme grunt build:css to generate the themed files

Testing

• Issue: Tests not running completely
  • Solution: Use grunt test to run all tests, or grunt test --suites=table,slider to run specific test suites

Deprecated Features

• Note: jQuery Mobile is no longer maintained. Consider migrating to modern alternatives for new projects.