Kuromoji.js

Common errors

• Uncaught ReferenceError: kuromoji is not defined

  cause The `kuromoji.js` script was not loaded in the HTML before attempting to use the `kuromoji` global object in the browser, or the CommonJS `require` statement was not executed in Node.js.
  fix In a browser, ensure `<script src="url/to/kuromoji.js"></script>` appears before your script that uses `kuromoji`. In Node.js, ensure `var kuromoji = require('kuromoji');` is at the top of your module.

• Error: ENOENT: no such file or directory, open 'path/to/dictionary/dir/base.dat.gz'

  cause The `dicPath` provided to `kuromoji.builder()` does not correctly point to the directory containing the Kuromoji dictionary files.
  fix Verify that `dicPath` is an absolute or correct relative path to where the `dict` folder (containing `base.dat.gz`, `tid.dat.gz`, etc.) is located. For npm installations, this is often `path.resolve(__dirname, 'node_modules/kuromoji/dict')` in Node.js.

Warnings

• gotcha The original `kuromoji` package (takuyaa/kuromoji.js) is unmaintained since its last update approximately 8 years ago. It lacks modern features like ES Modules (ESM), TypeScript typings, and Promise-based APIs, relying solely on CommonJS and callbacks.
  Fix: For new projects or modern environments, consider using actively maintained forks such as `@patdx/kuromoji` or `code4fukui-es`, which offer ESM, Promises, and TypeScript support.
• gotcha Incorrect `dicPath` configuration is a common source of errors, leading to `ENOENT` (file not found) or similar I/O issues during tokenizer initialization. The dictionary files are essential and must be accessible.
  Fix: Ensure `dicPath` points to the *exact* directory containing the gzipped dictionary files (e.g., `node_modules/kuromoji/dict` for npm installations in Node.js, or a correct CDN path for browsers). Use `path.resolve` in Node.js for robust path handling.
• deprecated The README suggests installing `kuromoji` via Bower for browser usage. Bower is a deprecated package manager and should no longer be used.
  Fix: For browser usage, either serve the `build/kuromoji.js` and `dict/*.dat.gz` files from your application or a CDN, or consider using a modern fork which typically provides better browser integration and bundling support via npm.

Install

• npm install kuromoji npm
• yarn add kuromoji yarn
• pnpm add kuromoji pnpm

Imports

• kuromoji
  wrong:

  import kuromoji from 'kuromoji';

  correct:

  var kuromoji = require('kuromoji');

  The original `kuromoji` package uses CommonJS `require` syntax. It does not natively support ES Modules (`import`).
• kuromoji.builder
  wrong:

  import { builder } from 'kuromoji';

  correct:

  var builder = require('kuromoji').builder;

  The `builder` function is the primary entry point to initialize the morphological analyzer. It is accessed via the `kuromoji` CommonJS export.
• kuromoji (global)
  wrong:

  const kuromoji = window.kuromoji;

  correct:

  <!-- In HTML --> <script src="url/to/kuromoji.js"></script>
  // In JavaScript
  kuromoji.builder(...)

  In browser environments, `kuromoji.js` exposes a global `kuromoji` object after being loaded via a `<script>` tag. There's no need to manually assign it from `window`.

Quickstart

This example demonstrates how to initialize the Kuromoji.js tokenizer in Node.js, specifying the dictionary path, and then tokenize a Japanese sentence.

const path = require('path');
const kuromoji = require('kuromoji');

const dicPath = path.resolve(__dirname, 'node_modules/kuromoji/dict');

kuromoji.builder({ dicPath: dicPath }).build(function (err, tokenizer) {
    if (err) {
        console.error('Error building tokenizer:', err);
        return;
    }
    const sentence = "すもももももももものうち";
    const tokens = tokenizer.tokenize(sentence);
    console.log(`Tokens for "${sentence}":`);
    tokens.forEach(token => {
        console.log(`  - Surface: ${token.surface_form}, POS: ${token.pos}, Reading: ${token.reading}`);
    });
});