How to Deploy & Use twitter/twemoji

# Twemoji Deployment & Usage Guide

## Prerequisites

- **Web Browser**: Modern browser with JavaScript enabled (ES5+ compatible)
- **Web Server**: Local or remote server to serve HTML files (required to avoid CORS issues when testing locally)
- **Git** (optional): For cloning specific versions from the `gh-pages` branch
- **Node.js/npm** (optional): If using `npx serve` or similar for local testing

## Installation

### Method 1: CDN (Recommended)

Add the following to your HTML `<head>`:

**Latest version (auto-updating):**
```html
<script src="https://unpkg.com/twemoji@latest/dist/twemoji.min.js" crossorigin="anonymous"></script>

Specific version (v14.0.3) with integrity check:

<script src="https://unpkg.com/twemoji@14.0.3/dist/twemoji.min.js" integrity="sha384-eoGiwFCoIsUzdZGbvJ/7h/ICofqh5LolgoDnsgdbLptvnpK4+/swGDdkv3sb6bq+" crossorigin="anonymous"></script>

Method 2: Self-Hosted (Download)

Download built assets from the gh-pages branch:

# Download specific version assets
git clone --single-branch --branch gh-pages https://github.com/twitter/twemoji.git twemoji-assets

# Or download specific files via curl
curl -O https://raw.githubusercontent.com/twitter/twemoji/gh-pages/v/14.0.3/72x72/2764.png

Include the local script:

<script src="/path/to/twemoji.min.js"></script>

Configuration

Basic Setup

Initialize Twemoji after DOM load:

<script>
  // Wait for DOM to be ready
  document.addEventListener('DOMContentLoaded', function() {
    // Parse entire document body
    twemoji.parse(document.body);
    
    // Or parse specific element
    var container = document.getElementById('emoji-container');
    twemoji.parse(container);
  });
</script>

Advanced Configuration Options

Configure the parse() function with an options object:

twemoji.parse(document.body, {
  // Base URL for emoji images (REQUIRED - MaxCDN is shut down)
  base: 'https://unpkg.com/twemoji@14.0.3/assets/',
  
  // Image size: "72x72" (default), "16x16", "36x36", etc.
  size: '72x72',
  
  // File extension: ".png" (default) or ".svg"
  ext: '.png',
  
  // CSS class for generated images
  className: 'emoji',
  
  // Custom image source generator (optional)
  callback: function(icon, options) {
    return ''.concat(
      options.base,
      options.size,
      '/',
      icon,
      options.ext
    );
  },
  
  // Add custom attributes to images (optional)
  attributes: function(icon, variant) {
    return {
      title: 'Emoji: ' + icon,
      'data-emoji': icon
    };
  }
});

SVG Support

For SVG emoji instead of PNG:

twemoji.parse(document.body, {
  folder: 'svg',
  ext: '.svg',
  base: 'https://unpkg.com/twemoji@14.0.3/assets/'
});

Build & Run

Local Development Setup

Create test file (index.html):

<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/twemoji@14.0.3/dist/twemoji.min.js" crossorigin="anonymous"></script>
  <style>
    .emoji {
      height: 1em;
      width: 1em;
      margin: 0 .05em 0 .1em;
      vertical-align: -0.1em;
    }
  </style>
</head>
<body>
  <div id="content">I ❤️ emoji! 🚀</div>
  
  <script>
    document.addEventListener('DOMContentLoaded', function() {
      twemoji.parse(document.getElementById('content'));
    });
  </script>
</body>
</html>

Start local server:

# Python 3
python -m http.server 8000

# Python 2
python -m SimpleHTTPServer 8000

# Node.js (if installed)
npx serve .

# PHP
php -S localhost:8000

Open browser: Navigate to http://localhost:8000

Production Build

No build step required for the library itself. For production deployment of your application:

Vendor the assets (recommended for production):

mkdir -p static/twemoji
cd static/twemoji
curl -O https://unpkg.com/twemoji@14.0.3/dist/twemoji.min.js
# Download emoji assets if self-hosting images

Update base URL to point to your CDN or domain:

twemoji.base = 'https://your-cdn.com/twemoji/assets/';

Deployment

Option A: CDN Deployment (Easiest)

Use unpkg or jsDelivr in production:

<script src="https://unpkg.com/twemoji@14.0.3/dist/twemoji.min.js" integrity="sha384-eoGiwFCoIsUzdZGbvJ/7h/ICofqh5LolgoDnsgdbLptvnpK4+/swGDdkv3sb6bq+" crossorigin="anonymous"></script>

Option B: Self-Hosted Assets (Best for Performance/Reliability)

Download assets:

git clone --depth 1 --branch gh-pages https://github.com/twitter/twemoji.git
cp -r twemoji/v/14.0.3 /var/www/html/twemoji-assets/

Configure base path:

twemoji.parse(document.body, {
  base: '/twemoji-assets/',
  size: '72x72'
});

Platform-Specific Deployment

Static Site (GitHub Pages/Netlify/Vercel):

Include the CDN script or vendor the twemoji.min.js in your repo
If using Jekyll/Hexo/Hugo, add the script to your template header

Single Page Application (React/Vue/Angular):

// React example
import { useEffect, useRef } from 'react';

function EmojiText({ text }) {
  const ref = useRef(null);
  
  useEffect(() => {
    if (ref.current && window.twemoji) {
      twemoji.parse(ref.current, {
        base: 'https://unpkg.com/twemoji@14.0.3/assets/'
      });
    }
  }, [text]);
  
  return <div ref={ref}>{text}</div>;
}

WordPress/Drupal:

Enqueue the script in your theme:

wp_enqueue_script('twemoji', 'https://unpkg.com/twemoji@14.0.3/dist/twemoji.min.js', [], null, true);
wp_add_inline_script('twemoji', 'document.addEventListener("DOMContentLoaded", function() { twemoji.parse(document.body); });');

Troubleshooting

MaxCDN Shutdown (404 Errors)

Problem: Images fail to load referencing twemoji.maxcdn.com Solution: Update base URL to unpkg or self-hosted assets:

twemoji.base = 'https://unpkg.com/twemoji@14.0.3/assets/';

CORS Errors

Problem: Access-Control-Allow-Origin errors when loading images Solution: Ensure crossorigin="anonymous" is set on the script tag, or serve files from same origin.

Emoji Not Rendering

Problem: Unicode characters appear but don't convert to images Solution:

Ensure you're parsing after DOM is loaded (use DOMContentLoaded)
Check that text is in actual text nodes (not HTML-encoded)
Verify the emoji is in Unicode 14.0 spec (Twemoji v14.0 supports Emoji 14.0)

Security Warnings (XSS)

Problem: Using string parsing creates XSS vulnerabilities Solution: Always use DOM parsing (passing an HTMLElement), not string parsing:

// SAFE - DOM parsing
twemoji.parse(document.getElementById('content'));

// UNSAFE - String parsing (avoid)
var html = twemoji.parse(userInputString); // Never use with untrusted input

Missing SVG Support

Problem: SVG emoji not displaying Solution: Ensure correct folder configuration:

twemoji.parse(node, {
  folder: 'svg',
  ext: '.svg',
  base: 'https://unpkg.com/twemoji@14.0.3/assets/'
});

Performance Issues

Problem: Page freeze on large documents Solution: Parse specific containers rather than document.body, or use requestAnimationFrame for chunked parsing:

// Parse in chunks
const containers = document.querySelectorAll('.emoji-container');
containers.forEach((container, index) => {
  setTimeout(() => twemoji.parse(container), index * 100);
});