pjax Deployment and Usage Guide

Prerequisites

• jQuery 1.8 or higher - pjax depends on jQuery to function
• Modern web browser - Supports HTML5 pushState API for proper pjax functionality
• Web server - To serve your application and handle pjax requests

Installation

npm Installation

npm install jquery-pjax

Standalone Script Installation

Download the pjax script directly:

curl -LO https://raw.github.com/defunkt/jquery-pjax/master/jquery.pjax.js

Then include it in your HTML after jQuery:

<script src="jquery.js"></script>
<script src="jquery.pjax.js"></script>

Configuration

Basic Setup

The simplest configuration targets all links and a specific container:

$(document).pjax('a', '#pjax-container')

Selective Pjax Links

For existing sites, use data-pjax attributes to selectively enable pjax:

$(document).pjax('[data-pjax] a, a[data-pjax]', '#pjax-container')

Global Options

Configure default pjax behavior:

$.pjax.defaults.timeout = 1200
$.pjax.defaults.scrollTo = false

Server-Side Configuration

Configure your server to detect pjax requests via the X-PJAX header. Example for Ruby on Rails:

def index
  if request.headers['X-PJAX']
    render :layout => false
  end
end

Build & Run

Development

1. Include jQuery and pjax in your HTML:

<script src="jquery.js"></script>
<script src="jquery.pjax.js"></script>
<script>
  $(document).pjax('a', '#pjax-container')
</script>

2. Set up your server to handle pjax requests (see server configuration above)

Production

1. Minify your JavaScript (including pjax)
2. Configure server caching for pjax responses
3. Test pjax functionality thoroughly

Deployment

Static Site Hosting (Vercel, Netlify, GitHub Pages)

• Deploy your static HTML/CSS/JS files
• Configure server-side redirects if needed
• Ensure your server can handle the X-PJAX header

Traditional Web Hosting

• Upload your application files
• Configure your web server (Apache, Nginx) to handle pjax requests
• Set up proper caching headers

Framework-Specific Deployment

• Rails: Use the asset pipeline and configure pjax in your controllers
• Django: Use middleware to detect pjax requests
• Express: Add pjax detection middleware

Troubleshooting

Common Issues

1. Pjax not working on some links

Solution: Check if links have proper href attributes and are not filtered by your selector. Use browser dev tools to verify click events are firing.

2. Page flashes or flickers during navigation

Solution: Increase the timeout value:

$.pjax.defaults.timeout = 1500

3. Browser back button doesn't work

Solution: Ensure your server properly handles the X-PJAX header and returns appropriate content. Verify pushState is supported in the browser.

4. Content not loading in container

Solution: Check that your container selector is correct and unique. Verify the server is returning valid HTML.

5. Scripts/styles not applying after pjax navigation

Solution: Reinitialize any JavaScript that needs to run on page load after pjax events:

$(document).on('pjax:success', function() {
  // Reinitialize components
})

6. Cross-origin links opening in new tabs

Solution: This is expected behavior. pjax ignores cross-origin links to prevent security issues.

Debugging

Enable pjax event logging:

$(document).on('pjax:click', function(e) { console.log('pjax:click', e) })
$(document).on('pjax:beforeSend', function(e) { console.log('pjax:beforeSend', e) })
$(document).on('pjax:success', function(e) { console.log('pjax:success', e) })

Check browser console for JavaScript errors and network tab for failed requests.