{"id":15455,"library":"lindera-wasm-bundler","title":"Lindera WASM for Bundler Environments","description":"lindera-wasm-bundler is a WebAssembly-based morphological analysis library designed for use in bundler environments like Webpack or Rollup. It provides Japanese text segmentation and part-of-speech tagging capabilities, leveraging WebAssembly for performance and portability. The current stable version is 3.0.5, with minor releases occurring frequently to address bugs and introduce minor enhancements, as seen in the recent v3.0.x series. Major version updates (like the v2 to v3 transition) introduce significant changes, often including refactoring and API adjustments. A key differentiator is its reliance on the OPFS (Origin Private File System) API for efficient runtime loading and management of large dictionary files, making it suitable for web applications requiring robust text processing without bundling dictionaries directly into the main application payload.","status":"active","version":"3.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/lindera/lindera","tags":["javascript","morphological","analysis","library","wasm","webassembly","typescript"],"install":[{"cmd":"npm install lindera-wasm-bundler","lang":"bash","label":"npm"},{"cmd":"yarn add lindera-wasm-bundler","lang":"bash","label":"yarn"},{"cmd":"pnpm add lindera-wasm-bundler","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the default export and initializes the WebAssembly module. It must be awaited before using other functions.","wrong":"import { __wbg_init } from 'lindera-wasm-bundler';","symbol":"__wbg_init","correct":"import __wbg_init from 'lindera-wasm-bundler';"},{"note":"CommonJS `require` is not supported for `lindera-wasm-bundler` since v3. Use named ESM imports.","wrong":"const { TokenizerBuilder } = require('lindera-wasm-bundler');","symbol":"TokenizerBuilder","correct":"import { TokenizerBuilder } from 'lindera-wasm-bundler';"},{"note":"Used to load pre-downloaded dictionary files from byte arrays.","symbol":"loadDictionaryFromBytes","correct":"import { loadDictionaryFromBytes } from 'lindera-wasm-bundler';"},{"note":"Functions related to OPFS-based dictionary management (downloading, loading files) are exposed from the 'lindera-wasm-bundler/opfs' subpath.","wrong":"import { downloadDictionary } from 'lindera-wasm-bundler';","symbol":"downloadDictionary","correct":"import { downloadDictionary, loadDictionaryFiles } from 'lindera-wasm-bundler/opfs';"}],"quickstart":{"code":"import __wbg_init, { TokenizerBuilder, loadDictionaryFromBytes } from 'lindera-wasm-bundler';\nimport { downloadDictionary, loadDictionaryFiles } from 'lindera-wasm-bundler/opfs';\n\nasync function initializeAndTokenize() {\n    // Initialize the WebAssembly module\n    await __wbg_init();\n\n    // Check if dictionary is already downloaded or download it for the first time.\n    // In a real application, you might use local storage or IndexedDB to track this.\n    console.log(\"Attempting to download dictionary (if not already present)...\");\n    try {\n        await downloadDictionary(\n            \"https://github.com/lindera/lindera/releases/download/v3.0.0/lindera-ipadic-3.0.0.zip\", \n            \"ipadic\"\n        );\n        console.log(\"Dictionary 'ipadic' ready in OPFS.\");\n    } catch (error) {\n        console.warn(\"Error downloading dictionary, might be already present or network issue:\", error);\n    }\n\n    // Load dictionary from OPFS\n    console.log(\"Loading dictionary files from OPFS...\");\n    const files = await loadDictionaryFiles(\"ipadic\");\n    const dict = loadDictionaryFromBytes(\n        files.metadata, files.dictDa, files.dictVals,\n        files.dictWordsIdx, files.dictWords, files.matrixMtx,\n        files.charDef, files.unk\n    );\n    console.log(\"Dictionary loaded into memory.\");\n\n    // Create a tokenizer instance\n    const builder = new TokenizerBuilder();\n    builder.setDictionaryInstance(dict);\n    builder.setMode(\"normal\"); // \"normal\", \"decompose\", or \"search\"\n    const tokenizer = builder.build();\n\n    // Tokenize a sentence\n    const text = \"すもももももももものうち\";\n    console.log(`Tokenizing: \"${text}\"`);\n    const tokens = tokenizer.tokenize(text);\n\n    tokens.forEach(token => {\n        console.log(`Surface: ${token.surface}, Details: ${token.details.join(\", \")}`);\n    });\n    console.log(\"Tokenization complete.\");\n}\n\ninitializeAndTokenize().catch(console.error);","lang":"typescript","description":"This quickstart demonstrates how to initialize the Lindera WASM module, download and load a dictionary using the OPFS API, and then tokenize a Japanese sentence, logging each token's surface form and morphological details."},"warnings":[{"fix":"For Node.js environments, switch to `lindera-nodejs`. For bundler environments, ensure you are importing from `lindera-wasm-bundler` and update import paths/statements as necessary. Review the v3.0.0 changelog for specific refactoring details.","message":"Version 3.0.0 introduced significant changes, including the removal of the dedicated Node.js WASM target and renaming of npm packages. Projects targeting Node.js should now use `lindera-nodejs` instead of WASM packages. Projects using WASM in bundler environments should use `lindera-wasm-bundler`.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Add `lindera-wasm-bundler` to the `optimizeDeps.exclude` array in your `vite.config.js`:\n```javascript\n// vite.config.js\nimport { defineConfig } from 'vite'\n\nexport default defineConfig({\n  optimizeDeps: {\n    exclude: [\n      \"lindera-wasm-bundler\" // Use \"lindera-wasm-web\" if using that package\n    ]\n  },\n});\n```","message":"When using `lindera-wasm-bundler` (or `lindera-wasm-web`) in a Vite project, you must explicitly exclude it from `optimizeDeps` in your `vite.config.js` to prevent issues with Vite's dependency pre-bundling.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"In `manifest.json`, ensure your CSP includes `script-src 'self' 'wasm-unsafe-eval';` for `extension_pages`. For Vite development, configure `cors` in `vite.config.js`:\n```json\n// manifest.json\n\"content_security_policy\": {\n  \"extension_pages\": \"script-src 'self' 'wasm-unsafe-eval';\"\n}\n```\n```javascript\n// vite.config.js\nimport { defineConfig } from 'vite'\n\nexport default defineConfig({\n  server: {\n    cors: {\n      origin: [\n        /chrome-extension:\\/\\//,\n      ],\n    },\n  },\n});\n```","message":"For browser extension development, a `content_security_policy` (CSP) must be configured in `manifest.json` to allow WebAssembly execution using `wasm-unsafe-eval`. Additionally, Vite's dev server might require CORS configuration for `chrome-extension://` origins.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Always `await` calls to `__wbg_init()` and any methods that return a Promise, typically those that interact with the underlying WASM or I/O, such as `downloadDictionary` and potentially `tokenizer.tokenize` in some complex scenarios. Wrap usage in an `async` function.","message":"All functions interacting with the WebAssembly module, including `__wbg_init` and methods on the `Tokenizer` instance, are asynchronous and return Promises. Forgetting to `await` them can lead to unhandled promise rejections or functions not completing before subsequent operations.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Verify that your bundler is correctly configuring the output path and serving the WebAssembly `.wasm` file. For Vite, ensure the `optimizeDeps.exclude` configuration is correctly applied to prevent issues with pre-bundling that might interfere with WASM file resolution.","cause":"This error often indicates that the browser or bundler attempted to parse an HTML document (e.g., an error page) as a WebAssembly module, usually because the WASM file could not be found at the expected path.","error":"Failed to load WASM module: CompileError: WebAssembly.instantiate(): expected magic word 00 61 73 6d, found 3c 21 44 4f"},{"fix":"Ensure `__wbg_init` is imported as the default export: `import __wbg_init from 'lindera-wasm-bundler';`","cause":"The default export for initializing the WebAssembly module, `__wbg_init`, was either not imported or was imported incorrectly (e.g., as a named import).","error":"ReferenceError: __wbg_init is not defined"},{"fix":"Ensure `downloadDictionary` has completed successfully and that the dictionary name provided to `loadDictionaryFiles` matches the name used during download. Also, verify that the browser's Origin Private File System (OPFS) is accessible and not blocked by security policies.","cause":"This error typically occurs when attempting to access properties like `metadata` from the object returned by `loadDictionaryFiles` before the dictionary files have been successfully loaded or if `loadDictionaryFiles` failed to retrieve them.","error":"TypeError: Cannot read properties of undefined (reading 'metadata')"}],"ecosystem":"npm"}