Nextcloud Node.js Client

Common errors

• ReferenceError: require is not defined

  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).
  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.

• Error: Nextcloud credentials not found (NEXTCLOUD_USERNAME, NEXTCLOUD_PASSWORD, NEXTCLOUD_URL)

  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.
  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: '...' })`.

• Error: Forbidden (403)

  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.
  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.

Warnings

• gotcha 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.
  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.
• gotcha 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.
  Fix: Generate an app-specific password in your Nextcloud security settings and use it for `NEXTCLOUD_PASSWORD` in your environment variables or client configuration.
• gotcha 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.
  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.

Install

• npm install nextcloud-node-client npm
• yarn add nextcloud-node-client yarn
• pnpm add nextcloud-node-client pnpm

Imports

• Client
  wrong:

  import { Client } from 'nextcloud-node-client';

  correct:

  import Client from 'nextcloud-node-client';

  The main `Client` class is typically imported as a default export.
• File, Folder, Tag, Share
  wrong:

  import File from 'nextcloud-node-client/File';

  correct:

  import { File, Folder, Tag, Share } from 'nextcloud-node-client';

  Auxiliary classes like `File`, `Folder`, `Tag`, and `Share` are named exports.
• * as NextcloudClient
  wrong:

  const NextcloudClient = require('nextcloud-node-client');

  correct:

  import * as NextcloudClient from 'nextcloud-node-client';

  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.

Quickstart

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.

import Client, { File, Folder, Share } from 'nextcloud-node-client';

// Ensure these environment variables are set:
// process.env.NEXTCLOUD_USERNAME
// process.env.NEXTCLOUD_PASSWORD
// process.env.NEXTCLOUD_URL (e.g., 'https://your.nextcloud.host')

(async () => {
    try {
        // Create a new client. Credentials are automatically picked up from environment variables.
        const client = new Client();

        // Create a folder structure if it doesn't exist
        const folder: Folder = await client.createFolder('my-test-folder/subfolder');
        console.log(`Created folder: ${folder.name}`);

        // Create a file within the folder
        const fileContent = Buffer.from('Hello, Nextcloud from Node.js!');
        const file: File = await folder.createFile('hello.txt', fileContent);
        console.log(`Created file: ${file.name}`);

        // Add a tag to the file (the tag will be created if it doesn't exist)
        await file.addTag('nodejs-api-test');
        console.log('Added tag to file.');

        // Get the content of the created file
        const downloadedContent: Buffer = await file.getContent();
        console.log(`Downloaded file content: ${downloadedContent.toString()}`);

        // Share the file publicly with a password and note
        const share: Share = await client.createShare({
            fileSystemElement: file,
            password: 'my-secure-password',
            note: 'Shared via nextcloud-node-client example.'
        });
        console.log(`File shared publicly. Share link: ${share.url}`);
        console.log(`Share password: ${share.password}`);

        // Clean up: Delete the folder, which also deletes the file and share within it
        await folder.delete();
        console.log(`Deleted folder: ${folder.name}`);

    } catch (e) {
        console.error('An error occurred:', e);
        // More robust error handling might include checking error types or messages
        if (e instanceof Error) {
            console.error(e.message);
        }
    }
})();