Parallax.js Deployment and Usage Guide

1. Prerequisites

• Runtime: Modern web browser with JavaScript enabled
• Development Tools: Node.js (for building from source)
• Package Manager: npm (included with Node.js)

2. Installation

Quick Start (CDN)

For immediate use in your project:

<script src="https://cdnjs.cloudflare.com/ajax/libs/parallax/3.1.0/parallax.min.js"></script>

Local Development

1. Clone the repository:

git clone https://github.com/wagerfield/parallax.git
cd parallax

2. Install dependencies:

npm install

3. Build the project:

npm run build

The compiled files will be available in the dist/ directory.

Using npm

For integration in your Node.js project:

npm install parallax-js

3. Configuration

HTML Structure

Create a scene container with layer elements:

<div id="scene">
  <div data-depth="0.2">Layer 1</div>
  <div data-depth="0.6">Layer 2</div>
</div>

Configuration Options

Set options either declaratively or programmatically:

Declarative (HTML attributes):

<div id="scene" data-relative-input="true">
  <div data-depth="0.2">Layer 1</div>
</div>

Programmatic (JavaScript):

var scene = document.getElementById('scene');
var parallaxInstance = new Parallax(scene, {
  relativeInput: true,
  clipRelativeInput: false,
  hoverOnly: false,
  calibrateX: false,
  calibrateY: true,
  invertX: true,
  invertY: true,
  limitX: false,
  limitY: false,
  scalarX: 10.0,
  scalarY: 8.0,
  frictionX: 0.1,
  frictionY: 0.1,
  originX: 0.5,
  originY: 0.5
});

Available Configuration Options

4. Build & Run

Development Server

To run the development server with live reload:

npm run dev

This will start a local server and open the example page in your browser.

Production Build

To create a production-ready build:

npm run build

This generates parallax.min.js in the dist/ directory with:

• Browserify bundling
• Babel transpilation (ES2015)
• Uglification
• Source maps

Running Locally

1. Include the script in your HTML:

<script src="dist/parallax.min.js"></script>

2. Initialize Parallax:

var scene = document.getElementById('scene');
var parallaxInstance = new Parallax(scene);

5. Deployment

Parallax.js is a client-side JavaScript library that can be deployed with any static hosting service:

Static Hosting Options

• GitHub Pages: Perfect for documentation sites and demos
• Netlify: Excellent for static sites with continuous deployment
• Vercel: Great for frontend applications
• AWS S3 + CloudFront: For enterprise-level static hosting
• Firebase Hosting: For web apps using Firebase ecosystem

Integration with Web Frameworks

React/Vue/Angular: Import and initialize in your component lifecycle methods:

import Parallax from 'parallax-js';

// In your component
componentDidMount() {
  this.parallax = new Parallax(this.refs.scene);
}

WordPress: Enqueue the script in your theme's functions.php:

function enqueue_parallax() {
    wp_enqueue_script('parallax', 'path/to/parallax.min.js', [], '3.1.0', true);
}
add_action('wp_enqueue_scripts', 'enqueue_parallax');

6. Troubleshooting

Common Issues and Solutions

Issue: Parallax not working on mobile devices

• Solution: Ensure your page is served over HTTPS (required for device orientation API)
• Check that the device supports gyroscope/motion detection

Issue: Layers not moving smoothly

• Solution: Adjust frictionX and frictionY values (lower values = more friction)
• Ensure your layers have appropriate data-depth values (0.0 to 1.0)

Issue: Parallax only works on hover

• Solution: Check if hoverOnly is set to true in your configuration
• For mobile, consider setting hoverOnly: false

Issue: Console errors about missing dependencies

• Solution: Ensure you're using the compiled version (parallax.min.js) in production
• If building from source, run npm install to install all dependencies

Issue: Parallax not initializing

• Solution: Make sure your DOM is fully loaded before initializing:

document.addEventListener('DOMContentLoaded', function() {
  var scene = document.getElementById('scene');
  var parallaxInstance = new Parallax(scene);
});

Issue: Performance issues with many layers

• Solution: Limit the number of layers
• Use lower depth values for layers farther from the viewer
• Consider using CSS transforms for simpler parallax effects

Debug Mode

Enable debug mode to visualize the parallax boundaries:

var parallaxInstance = new Parallax(scene, {
  relativeInput: true,
  clipRelativeInput: true,
  hoverOnly: false,
  debug: true  // Add this line
});

This will display visual indicators for the input boundaries and movement limits.