How to Deploy & Use CodeSeven/toastr

# toastr Deployment & Usage Guide

A comprehensive guide for installing, configuring, building, and deploying the toastr JavaScript notification library.

## 1. Prerequisites

### Runtime Requirements
- **jQuery 1.9.1+** (required dependency for toastr to function)
- **Modern web browser** (IE9+ and all modern browsers supported)

### Development/Build Requirements
- **Node.js** (v4.0+ recommended)
- **npm** (comes with Node.js)
- **Gulp CLI** (`npm install -g gulp-cli`)

## 2. Installation

### Option A: CDN (Fastest for Production)
Add directly to your HTML:

```html
<!-- CSS -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/toastr.js/latest/toastr.min.css" />

<!-- JavaScript -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/toastr.js/latest/toastr.min.js"></script>

Alternative via jsDelivr:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/toastr@2.1.4/build/toastr.min.css">
<script src="https://cdn.jsdelivr.net/npm/toastr@2.1.4/build/toastr.min.js"></script>

Option B: Package Manager

npm:

npm install --save toastr

Yarn:

yarn add toastr

Bower:

bower install toastr

NuGet (Visual Studio):

Install-Package toastr

Ruby on Rails: Add to Gemfile:

gem 'toastr-rails'

Then import in application.scss:

@import "toastr";

Option C: Build from Source

git clone https://github.com/CodeSeven/toastr.git
cd toastr
npm install

3. Configuration

Basic Setup

Include files in your HTML (if not using CDN):

<link href="path/to/toastr.css" rel="stylesheet"/>
<script src="path/to/jquery.js"></script>
<script src="path/to/toastr.js"></script>

Global Options

Configure before displaying toasts:

toastr.options = {
  "closeButton": true,
  "debug": false,
  "newestOnTop": true,
  "progressBar": false,
  "positionClass": "toast-top-right",
  "preventDuplicates": false,
  "onclick": null,
  "showDuration": "300",
  "hideDuration": "1000",
  "timeOut": "5000",
  "extendedTimeOut": "1000",
  "showEasing": "swing",
  "hideEasing": "linear",
  "showMethod": "fadeIn",
  "hideMethod": "fadeOut",
  "tapToDismiss": true,
  "escapeHtml": false
};

Available Configuration Options

4. Build & Run

Development Build

From the repository root:

# Install dependencies
npm install

# Build both JS and CSS (default task)
gulp

# Or build individually:
gulp js       # Minify and build toastr.min.js
gulp css      # Compile LESS and minify toastr.min.css
gulp analyze  # Run JSHint and JSCS linting

Build Outputs

Generated files appear in ./build/:

• toastr.min.js (minified with source map)
• toastr.min.css
• toastr.js.map (source map)

Testing

Run the test suite (requires Karma):

gulp test

Or view the demo locally: Open demo.html in a browser after building, or visit the live demo.

5. Deployment

Using in Production Projects

Module Bundlers (Webpack/Rollup):

import toastr from 'toastr';
import 'toastr/build/toastr.min.css';

toastr.success('Hello World');

AMD/RequireJS:

define(['jquery', 'toastr'], function($, toastr) {
    toastr.info('Module loaded');
});

CommonJS (Node-style):

var toastr = require('toastr');
require('toastr/build/toastr.min.css');

Deploying the Demo/Documentation

The demo site is hosted on GitHub Pages from the gh-pages branch. To deploy updates:

# Ensure demo.html is updated in master
git checkout gh-pages
git merge master
git push origin gh-pages

Publishing to Package Managers

For maintainers releasing new versions:

1. Update version in toastr.js and package.json
2. Build: gulp
3. Tag release: git tag -a v2.1.5 -m "Version 2.1.5"
4. Push tags: git push origin --tags
5. Publish to npm: npm publish

6. Troubleshooting

Common Issues

Issue: toastr is not defined or jQuery is not defined

• Solution: Ensure jQuery is loaded before toastr:

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

Issue: Toasts appear without styling (transparent/ugly)

• Solution: Include the CSS file:

<link rel="stylesheet" href="toastr.css" />

Issue: Toasts don't appear at all

• Check: Verify toastr.options.target exists in DOM (defaults to body)
• Check: Look for JavaScript errors in console
• Check: Ensure timeOut is not set to 0 unless extendedTimeOut handles hover

Issue: Animations not working

• Solution: Include jQuery UI or ensure you're using standard jQuery effects (fadeIn/fadeOut/slideDown). Custom easings like easeOutBounce require jQuery Easing plugin.

Issue: Positioning incorrect on mobile

• Solution: Use responsive CSS overrides:

@media (max-width: 768px) {
    #toast-container {
        left: 10px;
        right: 10px;
        top: 10px;
    }
}

Issue: Duplicates appearing despite preventDuplicates: true

• Note: Duplicates are matched based on exact message content. Different titles or options create distinct toasts.

Issue: Close button not working

• Solution: Ensure closeHtml contains a button element and closeButton: true is set.

Build Issues:

• Gulp command not found: Run npm install -g gulp-cli
• LESS compilation errors: Check Node.js version compatibility (use v4.0+)
• Karma tests fail: Ensure all devDependencies installed: npm install

Debug Mode

Enable debug logging during development:

toastr.options.debug = true;

This logs internal operations to the console.