{"id":13005,"library":"couchdb-compile","title":"CouchDB Document Compiler","description":"couchdb-compile is a Node.js utility designed to build CouchDB documents from various sources, including local directory trees, JSON files, or CommonJS modules. It processes a hierarchical filesystem structure, mirroring the CouchDB design document mapping, and converts it into a single JSON document suitable for direct upload to CouchDB. The current stable version is 1.11.2, with the last significant update in late 2021. Its release cadence has been infrequent in recent years, primarily focusing on bug fixes and dependency updates within the 1.x series. A key differentiator is its adherence to the Couchapp Filesystem Mapping, providing a structured way to manage CouchDB design documents and attachments outside the database, simplifying deployment and version control compared to manual JSON construction.","status":"maintenance","version":"1.11.2","language":"javascript","source_language":"en","source_url":"https://github.com/jo/couchdb-compile","tags":["javascript","couchdb","couchapp"],"install":[{"cmd":"npm install couchdb-compile","lang":"bash","label":"npm"},{"cmd":"yarn add couchdb-compile","lang":"bash","label":"yarn"},{"cmd":"pnpm add couchdb-compile","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is CommonJS-only. ES module imports are not supported.","wrong":"import { compile } from 'couchdb-compile';","symbol":"compile","correct":"const compile = require('couchdb-compile');"}],"quickstart":{"code":"const compile = require('couchdb-compile');\nconst fs = require('fs');\nconst path = require('path');\n\n// Setup a dummy CouchDB directory structure for demonstration\nconst projectPath = path.join(__dirname, 'my-couch-app-example');\nfs.mkdirSync(path.join(projectPath, 'views', 'numbers'), { recursive: true });\nfs.writeFileSync(path.join(projectPath, '_id'), '_design/my_app');\nfs.writeFileSync(path.join(projectPath, 'language'), 'javascript');\nfs.writeFileSync(path.join(projectPath, 'views', 'numbers', 'map.js'), `\n  function (doc) {\n    if (doc.type === 'number') {\n      emit(doc.value, null);\n    }\n  }\n`);\nfs.writeFileSync(path.join(projectPath, 'views', 'numbers', 'reduce.js'), `\n  function (keys, values, rereduce) {\n    return sum(values);\n  }\n`);\nfs.mkdirSync(path.join(projectPath, '_attachments'), { recursive: true });\nfs.writeFileSync(path.join(projectPath, '_attachments', 'logo.txt'), 'Hello from logo!');\n\nconsole.log('Compiling CouchDB document from directory:', projectPath);\ncompile(projectPath, function(error, doc, attachments) {\n  if (error) {\n    console.error('Error compiling:', error);\n    return;\n  }\n  console.log('Compiled CouchDB document:');\n  console.log(JSON.stringify(doc, null, 2));\n\n  if (attachments) {\n    console.log('\\nCompiled attachments:');\n    console.log(JSON.stringify(attachments.map(att => ({\n        name: att.name,\n        content_type: att.content_type,\n        data_length: att.data.length // Don't log full buffer content\n    })), null, 2));\n  }\n\n  // Cleanup the dummy directory\n  fs.rmSync(projectPath, { recursive: true, force: true });\n  console.log('Cleaned up dummy directory.');\n});\n\n// Example with an object source and function stringification\ncompile({\n  foo: function () {\n    return 42\n  },\n  bar: 'baz'\n}, (error, result) => {\n  if (error) {\n    console.error('Error compiling object:', error);\n    return;\n  }\n  console.log('\\nCompiled from object with function stringification:');\n  console.log(JSON.stringify(result, null, 2));\n});\n","lang":"javascript","description":"Demonstrates compiling a CouchDB design document from a directory structure and an object, including attachments and function stringification."},"warnings":[{"fix":"Be aware that client-side logic embedded in CouchDB design documents must be self-contained JavaScript strings. Test the stringified output for correctness.","message":"Functions defined within JavaScript objects or modules provided as source are stringified (using .toString()) and included as strings in the final CouchDB document, not executed. This is standard behavior for CouchDB design documents.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your file names accurately reflect the desired property names in the resulting JSON, excluding their extensions.","message":"File extensions are stripped when forming property names in the CouchDB document from a directory source. For example, 'validate_doc_update.js' becomes the 'validate_doc_update' property.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult the documentation for the '_attachments' directory structure and the 'multipart' option to ensure correct attachment processing for your use case.","message":"Attachments are handled specially when placed in a '_attachments' directory, converting them into base64 encoded data with computed content types. The 'multipart' option can alter how attachments are returned via the callback.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify the `source` argument points to an existing directory or file. Use an absolute path or ensure it's relative to `process.cwd()`.","cause":"The specified `source` path (directory or file) does not exist or is inaccessible.","error":"Error: ENOENT: no such file or directory, stat 'YOUR_PATH'"},{"fix":"Use CommonJS `require` syntax: `const compile = require('couchdb-compile');` as the library does not support ES module imports.","cause":"Attempting to use `compile` with ES module syntax (e.g., `import { compile } from '...'`) when the package is CommonJS-only, or incorrect destructuring.","error":"TypeError: compile is not a function"},{"fix":"Inspect the JSON source file for syntax errors, ensuring it is valid JSON.","cause":"The JSON file provided as a `source` argument is malformed or contains invalid syntax.","error":"SyntaxError: Unexpected token { in JSON at position X"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}