Mailcheck.js Deployment & Usage Guide

1. Prerequisites

• Runtime: A modern web browser (client-side library) or Node.js (for server-side/Node usage).
• Package Managers (Optional):
  • npm (Node Package Manager) - for Node.js/Browserify workflows.
  • Bower - for front-end package management.
• jQuery (Optional): Only required if you intend to use the jQuery plugin wrapper ($(element).mailcheck()). The core library works standalone.

2. Installation

Choose one of the following methods to add Mailcheck to your project.

Via npm (Browserify/Node.js)

npm install --save mailcheck

Via Bower

bower install --save mailcheck

Manual Download

Download the minified or unminified source directly:

• Minified: https://raw.githubusercontent.com/mailcheck/mailcheck/master/src/mailcheck.min.js
• Unminified: https://raw.githubusercontent.com/mailcheck/mailcheck/master/src/mailcheck.js

Place the downloaded file in your project's JavaScript directory (e.g., public/js/ or assets/).

3. Configuration

Mailcheck is configured via an options object passed to its run method or the jQuery plugin. No external configuration files are needed.

Core Options

The suggestion Object

When suggested is called, it receives an object with:

{
  address: 'user',       // Local part (before @)
  domain: 'gmail.com',   // Suggested full domain
  full: 'user@gmail.com' // Complete suggested email
}

Customizing Defaults

You can permanently extend Mailcheck's global default lists:

// Add to the existing default lists
Mailcheck.defaultDomains.push('customdomain.com');
Mailcheck.defaultSecondLevelDomains.push('customsl');
Mailcheck.defaultTopLevelDomains.push('customtld');

To replace the defaults entirely, pass your custom arrays directly in the run/plugin call (as shown in the options table).

4. Build & Run

Mailcheck is a pre-built library; no build step is required for standard usage.

Local Development & Testing

A simple static file server (script/server.js) is included for testing. From the project root:

1. Start the server (default port 8888):

   node script/server.js
   

2. Open your browser to http://localhost:8888/. You can place an HTML test file in the project root to test integration.

Using the Library in Your Code

With jQuery Plugin:

<script src="path/to/jquery.min.js"></script>
<script src="path/to/mailcheck.min.js"></script>
<script>
  $('#email').on('blur', function() {
    $(this).mailcheck({
      domains: ['gmail.com', 'yahoo.com'],
      suggested: function(element, suggestion) {
        // Display suggestion to user, e.g.:
        // $('#suggestion').text('Did you mean ' + suggestion.full + '?').show();
      },
      empty: function(element) {
        // Clear any existing suggestion UI
        // $('#suggestion').hide();
      }
    });
  });
</script>

Standalone (No jQuery):

<script src="path/to/mailcheck.min.js"></script>
<script>
  var emailInput = document.getElementById('email');
  emailInput.addEventListener('blur', function() {
    Mailcheck.run({
      email: this.value,
      domains: ['gmail.com', 'aol.com'],
      suggested: function(suggestion) {
        console.log('Did you mean:', suggestion.full);
      },
      empty: function() {
        console.log('No suggestions.');
      }
    });
  });
</script>

In Node.js:

var mailcheck = require('mailcheck');

mailcheck.run({
  email: 'user@gmil.com',
  domains: ['gmail.com', 'hotmail.com'],
  suggested: function(suggestion) {
    console.log('Suggested:', suggestion.full);
  }
});

5. Deployment

As a client-side library, deployment involves serving the .js file with your web application.

1. Include the file: Place mailcheck.min.js in your project's public assets directory.
2. Reference it: Add a <script> tag pointing to the file in your HTML, after jQuery if using the plugin.

   <script src="/assets/js/mailcheck.min.js"></script>
   

3. Deploy your application: Use your standard deployment process (e.g., push to a hosting provider like Netlify, Vercel, AWS S3, or a traditional server). Mailcheck itself does not require a separate server process.

Alternative (CDN): While not officially hosted by the project, you can upload the minified file to a CDN of your choice (e.g., jsDelivr, unpkg) and reference it via URL.

6. Troubleshooting

Note on String Distance: The default algorithm is Sift4. If you need different behavior (e.g., for non-Latin alphabets), implement and pass a function that returns a numeric distance between two strings via the distanceFunction option.