Codakey
Play
← Back to nlp-compromise/compromise

How to Deploy & Use nlp-compromise/compromise

# Compromise NLP - Deployment & Usage Guide

A practical guide for deploying and using the `compromise` natural language processing library in JavaScript environments.

## 1. Prerequisites

- **Node.js**: Version 14.x or higher (ES6 modules support required)
- **Package Manager**: npm (v6+) or yarn (v1.22+)
- **Build Tool** (for browser deployment): Webpack, Rollup, Vite, or Parcel
- **Modern Browser** (if client-side): Chrome 60+, Firefox 55+, Safari 12+, Edge 79+

## 2. Installation

### NPM Installation

```bash
npm install compromise

Language-Specific Variants (Optional)

For non-English text processing:

npm install fr-compromise    # French
npm install de-compromise    # German
npm install es-compromise    # Spanish
npm install it-compromise    # Italian

Browser CDN (Direct Usage)

<script src="https://unpkg.com/compromise"></script>
<script>
  const doc = window.nlp('your text here');
</script>

Development Setup (Contributing)

git clone https://github.com/spencermountain/compromise.git
cd compromise
npm install
npm run build
npm test

3. Configuration

Basic Setup (No Config Required)

Compromise works out-of-the-box with zero configuration:

import nlp from 'compromise';

const doc = nlp('she sells seashells by the seashore.');
doc.verbs().toPastTense();
console.log(doc.text()); // 'she sold seashells by the seashore.'

Plugin Configuration

Extend functionality with official plugins:

import nlp from 'compromise';
import speechPlugin from 'compromise-speech';
import datesPlugin from 'compromise-dates';

// Register plugins
nlp.extend(speechPlugin);
nlp.extend(datesPlugin);

// Use extended features
const doc = nlp('Milwaukee has certainly had its share of visitors..');
doc.compute('syllables');
const data = doc.places().json();

Custom Lexicons (Optional)

Add domain-specific vocabulary:

const doc = nlp('TensorFlow is a framework.', {
  framework: 'Noun',
  tensorflow: 'Framework'
});

Environment Variables (Server-Side)

For server deployments, optional tuning:

# .env
COMPROMISE_CACHE_SIZE=1000    # Limit internal cache (MB)
NODE_OPTIONS="--max-old-space-size=4096"  # For large text processing

4. Build & Run

Node.js Application

Basic usage:

// index.js
import nlp from 'compromise';

const analyzeText = (text) => {
  const doc = nlp(text);
  
  // Pattern matching
  if (doc.has('simon says #Verb')) {
    return { command: true };
  }
  
  // Data extraction
  return doc.places().json();
};

const result = analyzeText('Milwaukee has visitors');
console.log(result);

Run:

node index.js

Browser Application (Bundler)

Installation with build tool:

npm install compromise

Usage in React/Vue/Angular:

import nlp from 'compromise';

function TextAnalyzer({ text }) {
  const doc = nlp(text);
  const verbs = doc.verbs().json();
  
  return (
    <div>
      {verbs.map(v => <span key={v.text}>{v.text}</span>)}
    </div>
  );
}

Tree-shaking optimization:

// Import specific methods if available in your version
import nlp from 'compromise';

Serverless/Edge Functions

Vercel Function:

// api/analyze.js
import nlp from 'compromise';

export default function handler(req, res) {
  const { text } = req.body;
  const doc = nlp(text);
  
  res.status(200).json({
    places: doc.places().json(),
    verbs: doc.verbs().json()
  });
}

Cloudflare Worker:

import nlp from 'compromise';

export default {
  async fetch(request) {
    const { text } = await request.json();
    const doc = nlp(text);
    
    return new Response(JSON.stringify({
      text: doc.match('the #Adjective of times').text()
    }), {
      headers: { 'Content-Type': 'application/json' }
    });
  }
};

Production Build

Webpack/Rollup configuration:

// Ensure proper handling of ES modules
module.exports = {
  resolve: {
    mainFields: ['module', 'main']
  },
  // Compromise is ~200kb minified, consider code-splitting
  optimization: {
    splitChunks: {
      chunks: 'all'
    }
  }
};

5. Deployment

Static Site (JAMstack)

Deploy to Netlify/Vercel with client-side processing:

<!-- index.html -->
<script type="module">
  import nlp from 'https://unpkg.com/compromise@14.0.0/builds/compromise.mjs';
  
  const input = document.getElementById('input');
  input.addEventListener('input', (e) => {
    const doc = nlp(e.target.value);
    console.log(doc.json());
  });
</script>

Node.js Server (Docker)

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install compromise
COPY . .
CMD ["node", "server.js"]

Serverless Platforms

AWS Lambda:

  • Package size: ~800KB (including compromise)
  • Memory: 256MB minimum recommended
  • Timeout: 10s for texts < 10,000 words

Vercel/Netlify Functions:

  • Cold start: ~150ms
  • Optimal for texts under 5MB

Browser Extension/Electron

// preload.js (Electron)
const nlp = require('compromise');

window.analyzeText = (text) => {
  return nlp(text).contractions().expand().text();
};

6. Troubleshooting

Common Issues

"Cannot find module 'compromise'"

  • Ensure type: "module" in package.json for ES6 imports
  • Or use const nlp = require('compromise'); for CommonJS

Large Bundle Size

  • Compromise is ~200KB minified + gzipped
  • Use dynamic imports for non-critical paths:
const nlp = await import('compromise');

Memory Errors on Large Texts

  • Process in chunks:
const chunks = text.match(/[^.!?]+[.!?]+/g) || [];
const results = chunks.map(chunk => nlp(chunk).json());

Plugin Not Working

  • Ensure plugins are loaded before processing:
import nlp from 'compromise';
import plugin from 'compromise-plugin';

nlp.extend(plugin); // Must happen before nlp(text)
const doc = nlp('text');

Performance Degradation

  • Avoid creating new instances in loops
  • Reuse documents when possible:
const doc = nlp(largeText);
// Chain operations instead of re-parsing
doc.match('#Verb').verbs().toPastTense();

Contractions Not Matching

  • Use implicit matching or expand first:
doc.has('gonna'); // true
doc.has('going to'); // true (implicit)

// Or expand explicitly
doc.contractions().expand();

Debugging

Enable verbose logging:

const doc = nlp('text');
console.log(doc.debug()); // Shows internal tagging

Language Support Issues

For non-English text, ensure you're using the correct language pack:

// Wrong
import nlp from 'compromise';
nlp('bonjour').json(); // Limited French support

// Correct
import nlp from 'fr-compromise';
nlp('bonjour').json(); // Full French support

Browser Compatibility

For older browsers, use the legacy build:

<script src="https://unpkg.com/compromise@14/builds/compromise.min.js"></script>
← Project overviewView alternatives to nlp-compromise/compromise →