{"id":15721,"library":"nextcloud-node-client","title":"Nextcloud Node.js Client","description":"The `nextcloud-node-client` is a TypeScript-first library offering a comprehensive API to interact with Nextcloud servers from Node.js applications. Currently at version 1.8.1, it demonstrates an active development cadence with regular minor releases introducing new features like recursive file retrieval, user management, and improved sharing capabilities. The library differentiates itself by providing a rich, simple API that abstracts away the underlying Nextcloud communication protocols, supporting essential operations such as uploading and downloading files, managing folder structures, handling user accounts, creating and managing shares, and applying tags and comments to filesystem elements. A key feature is its flexible credential management, allowing configuration via environment variables (NEXTCLOUD_USERNAME, NEXTCLOUD_PASSWORD, NEXTCLOUD_URL) or Cloud Foundry's `VCAP_SERVICES`, and strongly recommending the use of Nextcloud's app-specific passwords for enhanced security. This client aims to streamline automation tasks for Nextcloud instances.","status":"active","version":"1.8.1","language":"javascript","source_language":"en","source_url":"https://github.com/hobigo/nextcloud-node-client","tags":["javascript","nextcloud","api","file","folder","tagging","nodejs","sharing","typescript"],"install":[{"cmd":"npm install nextcloud-node-client","lang":"bash","label":"npm"},{"cmd":"yarn add nextcloud-node-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add nextcloud-node-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The main `Client` class is typically imported as a default export.","wrong":"import { Client } from 'nextcloud-node-client';","symbol":"Client","correct":"import Client from 'nextcloud-node-client';"},{"note":"Auxiliary classes like `File`, `Folder`, `Tag`, and `Share` are named exports.","wrong":"import File from 'nextcloud-node-client/File';","symbol":"File, Folder, Tag, Share","correct":"import { File, Folder, Tag, Share } from 'nextcloud-node-client';"},{"note":"For ESM environments requiring all exports, use a namespace import. CommonJS `require` is not the idiomatic way for this TypeScript-first library in modern Node.js projects, though it might work via transpilation/bundling.","wrong":"const NextcloudClient = require('nextcloud-node-client');","symbol":"* as NextcloudClient","correct":"import * as NextcloudClient from 'nextcloud-node-client';"}],"quickstart":{"code":"import Client, { File, Folder, Share } from 'nextcloud-node-client';\n\n// Ensure these environment variables are set:\n// process.env.NEXTCLOUD_USERNAME\n// process.env.NEXTCLOUD_PASSWORD\n// process.env.NEXTCLOUD_URL (e.g., 'https://your.nextcloud.host')\n\n(async () => {\n    try {\n        // Create a new client. Credentials are automatically picked up from environment variables.\n        const client = new Client();\n\n        // Create a folder structure if it doesn't exist\n        const folder: Folder = await client.createFolder('my-test-folder/subfolder');\n        console.log(`Created folder: ${folder.name}`);\n\n        // Create a file within the folder\n        const fileContent = Buffer.from('Hello, Nextcloud from Node.js!');\n        const file: File = await folder.createFile('hello.txt', fileContent);\n        console.log(`Created file: ${file.name}`);\n\n        // Add a tag to the file (the tag will be created if it doesn't exist)\n        await file.addTag('nodejs-api-test');\n        console.log('Added tag to file.');\n\n        // Get the content of the created file\n        const downloadedContent: Buffer = await file.getContent();\n        console.log(`Downloaded file content: ${downloadedContent.toString()}`);\n\n        // Share the file publicly with a password and note\n        const share: Share = await client.createShare({\n            fileSystemElement: file,\n            password: 'my-secure-password',\n            note: 'Shared via nextcloud-node-client example.'\n        });\n        console.log(`File shared publicly. Share link: ${share.url}`);\n        console.log(`Share password: ${share.password}`);\n\n        // Clean up: Delete the folder, which also deletes the file and share within it\n        await folder.delete();\n        console.log(`Deleted folder: ${folder.name}`);\n\n    } catch (e) {\n        console.error('An error occurred:', e);\n        // More robust error handling might include checking error types or messages\n        if (e instanceof Error) {\n            console.error(e.message);\n        }\n    }\n})();","lang":"typescript","description":"This example demonstrates creating a Nextcloud client, managing folders and files, adding tags, retrieving file content, and creating password-protected public shares, followed by cleanup. It uses environment variables for authentication."},"warnings":[{"fix":"Use the base Nextcloud server URL for `NEXTCLOUD_URL`. If experiencing connection issues, verify Nextcloud's WebDAV API is functioning correctly on your server by attempting to access it directly via a browser or a WebDAV client.","message":"When configuring the Nextcloud URL, specify the base URL of your Nextcloud instance (e.g., `https://your.nextcloud.host`). Earlier versions might have implicitly expected or preferred a WebDAV-specific URL, but as of v1.8.0, the client can infer the correct endpoints from a general server URL, simplifying configuration. Ensure your Nextcloud server's WebDAV API is correctly configured.","severity":"gotcha","affected_versions":">=1.8.0"},{"fix":"Generate an app-specific password in your Nextcloud security settings and use it for `NEXTCLOUD_PASSWORD` in your environment variables or client configuration.","message":"For production environments and enhanced security, it is strongly recommended to use app-specific passwords generated in your Nextcloud user settings instead of your main account password. These passwords offer more granular control and can be revoked independently.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Structure your code using `async` functions and `await` keywords for all operations that return a Promise. Implement robust `try...catch` blocks to handle potential API errors.","message":"The library primarily uses Promises for asynchronous operations. While you can use `.then().catch()`, modern TypeScript/JavaScript code should leverage `async/await` for better readability and error handling. Make sure to wrap your asynchronous code in an `async` function and use `try...catch` blocks.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Switch to ESM import syntax: `import Client, { File } from 'nextcloud-node-client';`. Ensure your project is configured for ESM or use a bundler if targeting older Node.js environments.","cause":"Attempting to use `require('nextcloud-node-client')` in an ECMAScript Module (ESM) context (e.g., a file with `\"type\": \"module\"` in `package.json` or a `.mjs` file).","error":"ReferenceError: require is not defined"},{"fix":"Set the `NEXTCLOUD_USERNAME`, `NEXTCLOUD_PASSWORD`, and `NEXTCLOUD_URL` environment variables before running your application, or pass them directly to the `Client` constructor: `new Client({ url: '...', username: '...', password: '...' })`.","cause":"The `Client` constructor was called without explicit credentials and the required environment variables (NEXTCLOUD_USERNAME, NEXTCLOUD_PASSWORD, NEXTCLOUD_URL) were not set or were misspelled.","error":"Error: Nextcloud credentials not found (NEXTCLOUD_USERNAME, NEXTCLOUD_PASSWORD, NEXTCLOUD_URL)"},{"fix":"Verify that `NEXTCLOUD_USERNAME` and `NEXTCLOUD_PASSWORD` (preferably an app-specific password) are correct. Ensure the Nextcloud user has the necessary permissions for the attempted operations. Check your Nextcloud server's `config/config.php` to ensure the `trusted_domains` array includes the domain or IP of your Node.js application.","cause":"This error often indicates incorrect credentials (username/password), insufficient permissions for the user, or issues with app-specific passwords not being correctly generated or applied. It can also occur if the Nextcloud server's `trusted_domains` configuration does not include the host from which your Node.js application is making requests.","error":"Error: Forbidden (403)"}],"ecosystem":"npm"}