{"id":16405,"library":"jsonjsdb-builder","title":"Jsonjsdb Builder","description":"The `jsonjsdb-builder` package, currently at version 0.6.11, is a development tool that transforms structured data, primarily from Excel (.xlsx) files and Markdown documents, into two JSON-based formats. It generates a compact `.json.js` file (an array of arrays) optimized for efficient, server-less loading in web browsers (e.g., via `file://`), and a standard `.json` file (an array of objects) for general tooling and readability. This package is part of the broader `jsonjsdb` ecosystem, including a Python component. Its release cadence is driven by bug fixes and developer experience improvements, such as recent patches to prevent unnecessary database rewrites during development. A key differentiator is its tight integration with front-end build systems like Vite, offering automated data regeneration and hot-reloading, which streamlines the development of applications leveraging local, structured data.","status":"active","version":"0.6.11","language":"javascript","source_language":"en","source_url":"https://github.com/datannur/jsonjsdb","tags":["javascript","json","database","jsondb","jsonjsdb","local","file protocol","typescript"],"install":[{"cmd":"npm install jsonjsdb-builder","lang":"bash","label":"npm"},{"cmd":"yarn add jsonjsdb-builder","lang":"bash","label":"yarn"},{"cmd":"pnpm add jsonjsdb-builder","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the default export for the main builder class.","wrong":"import { JsonjsdbBuilder } from 'jsonjsdb-builder'","symbol":"JsonjsdbBuilder","correct":"import JsonjsdbBuilder from 'jsonjsdb-builder'"},{"note":"Used for integrating the builder with Vite, it's a named export.","wrong":"import initJsonjsdbBuilder from 'jsonjsdb-builder'","symbol":"initJsonjsdbBuilder","correct":"import { initJsonjsdbBuilder } from 'jsonjsdb-builder'"},{"note":"One of several low-level utility functions, all are named exports.","wrong":"const { jsonjsdbToObjects } = require('jsonjsdb-builder')","symbol":"jsonjsdbToObjects","correct":"import { jsonjsdbToObjects } from 'jsonjsdb-builder'"}],"quickstart":{"code":"import JsonjsdbBuilder from 'jsonjsdb-builder';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\nimport { dirname } from 'path';\nimport { mkdtemp, rm } from 'fs/promises';\nimport os from 'os';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\n\nasync function runQuickstart() {\n  let tempDir;\n  try {\n    tempDir = await mkdtemp(path.join(os.tmpdir(), 'jsonjsdb-builder-'));\n    const outputDbPath = path.join(tempDir, 'app_db');\n    const sourceDbPath = path.join(tempDir, 'db');\n\n    // In a real scenario, place .xlsx files in 'sourceDbPath' (e.g., path.join(sourceDbPath, 'users.xlsx'))\n    // The builder will read these files and generate JSON outputs.\n    \n    console.log(`Simulating JSONJSDB build process:`)\n    console.log(`  Output directory: ${outputDbPath}`);\n    console.log(`  Source Excel directory: ${sourceDbPath}`);\n\n    const builder = new JsonjsdbBuilder();\n    await builder.setOutputDb(outputDbPath);\n    // To actually process files, ensure 'sourceDbPath' contains .xlsx files.\n    // await builder.updateDb(sourceDbPath); \n    console.log('Builder initialized and output directory set. Call builder.updateDb() with your source Excel directory.');\n    console.log('Generated .json.js and .json files would appear in the output directory.');\n\n  } catch (error) {\n    console.error('Quickstart failed:', error);\n  } finally {\n    if (tempDir) {\n      console.log(`Cleaning up temporary directory: ${tempDir}`);\n      await rm(tempDir, { recursive: true, force: true });\n    }\n  }\n}\n\nrunQuickstart();","lang":"javascript","description":"This quickstart demonstrates how to initialize the `JsonjsdbBuilder` class, set up a temporary output directory for generated JSON files, and show where Excel source files would be specified for conversion. It illustrates the basic API usage for setting up the builder environment."},"warnings":[{"fix":"Ensure `vite-plugin-full-reload` is installed: `npm install -D vite-plugin-full-reload`.","message":"When integrating with Vite, `vite-plugin-full-reload` is a required development dependency. Forgetting to install it will lead to build failures.","severity":"gotcha","affected_versions":">=0.6.0"},{"fix":"Verify that the input directory (e.g., 'db' or 'markdown') contains the necessary source files before running builder commands.","message":"The builder methods like `updateDb()` and `updateMdDir()` implicitly expect source files (e.g., .xlsx or .md) to be present within the specified input directory. An empty directory will result in no output.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade to `jsonjsdb-builder` version 0.6.11 or newer to benefit from optimizations that prevent redundant file rewrites when source content is identical.","message":"Versions of `jsonjsdb-builder` prior to 0.6.11 might perform unnecessary table regenerations, potentially increasing build times, especially during development with a watcher.","severity":"gotcha","affected_versions":"<0.6.11"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Use the default import syntax: `import JsonjsdbBuilder from 'jsonjsdb-builder'`.","cause":"Attempted to use 'JsonjsdbBuilder' as a named import or with CommonJS 'require()' syntax.","error":"TypeError: JsonjsdbBuilder is not a constructor"},{"fix":"Use named import syntax: `import { initJsonjsdbBuilder } from 'jsonjsdb-builder'`.","cause":"Attempted to use a named export like `initJsonjsdbBuilder` without proper destructuring in the import statement.","error":"ReferenceError: initJsonjsdbBuilder is not defined"},{"fix":"Ensure all directory paths provided to builder methods either exist or are accessible for creation by the builder process.","cause":"The specified input or output directory path provided to a builder method (e.g., `setOutputDb`, `updateDb`) does not exist or is misspelled.","error":"Error: ENOENT: no such file or directory, stat '<path>'"},{"fix":"Convert your module to use ES Module syntax with `import` statements, or configure your environment to correctly handle ESM packages.","cause":"The `jsonjsdb-builder` package is published as an ES Module (ESM), but it is being imported using CommonJS `require()` syntax.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module <path> from <path> not supported."}],"ecosystem":"npm"}