SimpleWordCloud

A simple and lightweight word cloud generator for English and Chinese text, built with TypeScript.

Features

• Supports both English and Chinese text
• Customizable appearance (colors, fonts, sizes, etc.)
• Works in both Node.js and browser environments
• Built with TypeScript for type safety
• Uses simple tokenization algorithms for both English and Chinese text
• Generates SVG-based word clouds using d3-cloud

Published Package

This package is published on npm as @harryjwang/simplewordcloud.

Installation

# Using npm
npm install @harryjwang/simplewordcloud

# Using pnpm (recommended)
pnpm add @harryjwang/simplewordcloud

# Using yarn
yarn add @harryjwang/simplewordcloud

Usage

React

The package includes a React component that can be easily integrated into your React applications.

import React from 'react';
import { WordCloud } from '@harryjwang/simplewordcloud/react';

const MyComponent = () => {
  const text = 'This is a sample text for word cloud generation...';
  
  return (
    <WordCloud 
      text={text}
      language="english"
      width={800}
      height={600}
      maxWords={100}
      fontFamily="Arial, sans-serif"
      rotationAngles={[0, 0, 90]}
      rotationProbability={0.2}
    />
  );
};

export default MyComponent;

Props

The WordCloud component accepts the following props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | text | string | (required) | The text to generate the word cloud from | | language | 'english' | 'chinese' | 'english' | The language of the text | | width | number | 800 | The width of the word cloud in pixels | | height | number | 600 | The height of the word cloud in pixels | | maxWords | number | 100 | The maximum number of words to include in the word cloud | | fontFamily | string | 'Arial, sans-serif' | The font family to use for the words | | rotationAngles | number[] | [0, 0, 90] | The possible rotation angles for the words | | rotationProbability | number | 0.2 | The probability of a word being rotated |

Node.js

import { NodeSVGGenerator } from '@harryjwang/simplewordcloud';

// Generate a word cloud from English text
const englishText = 'This is a sample English text for word cloud generation...';
const svgString = NodeSVGGenerator.generateSVG(englishText, 'english', 800, 600, 100);

// Generate a word cloud from Chinese text
const chineseText = '这是一个用于生成词云的中文示例文本...';
const svgString2 = NodeSVGGenerator.generateSVG(chineseText, 'chinese', 800, 600, 100);

// Save the SVG to a file
const fs = require('fs');
fs.writeFileSync('wordcloud.svg', svgString);

Browser

<!-- Include the SimpleWordCloud library -->
<!-- Option 1: From node_modules -->
<script src="node_modules/@harryjwang/simplewordcloud/dist/browser/simplewordcloud.min.js"></script>

<!-- Option 2: From CDN (recommended for production) -->
<script src="https://cdn.jsdelivr.net/npm/@harryjwang/simplewordcloud/dist/browser/simplewordcloud.min.js"></script>

<div id="wordcloud-container"></div>

<script>
  // Generate a word cloud
  const text = 'This is a sample text for word cloud generation...';
  const container = document.getElementById('wordcloud-container');
  
  // Generate the word cloud with custom options
  SimpleWordCloud.generateWordCloud(text, 'english', container, {
    width: 800,
    height: 600,
    maxWords: 100,
    fontFamily: 'Arial, sans-serif',
    minFontSize: 10,
    maxFontSize: 60
  });
</script>

API

NodeSVGGenerator

A utility class for generating word clouds in Node.js environments.

Methods

• generateSVG(text: string, language: Language, width?: number, height?: number, maxWords?: number): string - Generate a word cloud as an SVG string

WordCloud

The main class for generating word clouds in browser environments.

Constructor

new WordCloud(options?: WordCloudOptions)

Methods

• generate(text: string, language: Language): SVGElement | string - Generate a word cloud as an SVG element (browser) or string (Node.js)
• generateSVG(text: string, language: Language): string - Generate a word cloud as an SVG string

WordCloudOptions

Options for customizing the word cloud appearance.

interface WordCloudOptions {
  width?: number;            // Width of the word cloud (default: 800)
  height?: number;           // Height of the word cloud (default: 600)
  fontFamily?: string;       // Font family (default: 'Arial, sans-serif')
  maxWords?: number;         // Maximum number of words (default: 100)
  colors?: string[];         // Color scheme (default: d3.schemeCategory10)
  padding?: number;          // Padding between words (default: 5)
  minFontSize?: number;      // Minimum font size (default: 10)
  maxFontSize?: number;      // Maximum font size (default: 60)
  rotationAngles?: number[]; // Rotation angles in degrees (default: [0, 90])
  rotationProbability?: number; // Probability of rotation (default: 0.3)
}

Language

Supported languages for tokenization.

type Language = 'english' | 'chinese';

Demo

The package includes two demos:

1. Standard Demo: A simple HTML/JavaScript demo that shows how to use the library in a browser environment.
2. React Demo: A React-based demo that demonstrates how to use the React component.

Running the Demos

To run the demos locally:

1. Clone this repository
2. Install dependencies: pnpm install
3. Build the package: pnpm run build:all
4. Start the demo server: pnpm run start:demo
5. Open http://localhost:3000/ in your browser

The server will automatically redirect you to the React demo. You can also access the demos directly:

• Standard Demo: http://localhost:3000/demo/index.html
• React Demo: http://localhost:3000/react

React Demo Features

• Input text area for entering custom text
• Language selection (English or Chinese)
• Sample texts for both languages
• Generate button to create/update the word cloud
• Customizable word cloud appearance

Alternatively, you can run the Node.js test script:

node test/node-test.js

This will generate two SVG files in the test directory: english-wordcloud.svg and chinese-wordcloud.svg.

Sample Word Clouds

Here are examples of the word clouds generated by the package:

English Word Cloud

Chinese Word Cloud

The test script uses d3-cloud with node-canvas to generate word clouds that look identical to those produced in the browser.

Browser Compatibility

The package is designed to work in modern browsers. The browser version uses a simplified tokenization approach to avoid dependencies on Node.js-specific modules.

Development

Building

# Build the Node.js version
pnpm run build

# Build the browser version
pnpm run build:browser

# Build the React version
pnpm run build:react

# Build the React demo
pnpm run build:demo

# Build all versions (Node.js, browser, and React)
pnpm run build:all

Testing

The package includes a test script that demonstrates how to use the library in a Node.js environment. The test script uses d3-cloud with node-canvas to generate word clouds that look identical to those produced in the browser.

# Install the canvas dependency for testing
pnpm add canvas --save-dev

# Run the test script
node test/node-test.js

The test script will generate two SVG files in the test directory: one for English text and one for Chinese text.

License

MIT