Presenting “nextcloud-link”

What is Nextcloud?

Before we can go into details about nextcloud-link, we should probably spent a minute to explain what Nextcloud is. Nextcloud GmbH is a German company that develops a Free/Libre Software alternative – of the same name – to centralized cloud services such as Dropbox, Google Drive, Microsoft OneDrive and others.

Although Nextcloud can easily be made into a fully fledged groupware – including calendaring, live and collaborative word processing, and so on by using its many available modules and extensions, this particular post is talking about the Nextcloud Files app specifically, which is a Free/Libre open-source software and self-hosted online file sharing and collaboration software licensed under the AGPL v3. Nextcloud is suitable to SOHOs and large corporations alike, since it can be run in set-ups ranging from a single Docker container to a cluster of multiple physical nodes.

In August 2019, some EU governments have decided to use Nextcloud over any US-based cloud storage solution.

Why nextcloud-link?

nextcloud-link is a nodejs library developed at TenTwentyFour¹⁰²⁴ that provides a TypeScript/JavaScript API to interact with Nextcloud instances using the WebDAV and OCS protocols.

Having surveyed the nodejs eco-system mid-2018, but not having discovered any existing libraries that fulfilled our requirements, we internally developed nextcloud-link for use with our online payroll management suite paperless.lu, which uses Nextcloud as a storage back-end. Having finally reached – in our humble opinion – a sufficient level of functionality and stability, we have decided to release nextcloud-link as Free Software under the MIT license to aid any developers finding themselves in the position where they’d like to connect a nodejs-based project to Nextcloud.

We’d like to believe that nextcloud-link offers developers a straightforward interface to easily find, retrieve or store files on a Nextcloud instance without the need to know the intricate details of the WebDAV protocol. Additionally interfacing with Nextcloud’s OpenCloudMesh (OCS) API, nextcloud-link allows to retrieve additional information on files, such as identifying the respective author of an uploaded file, as well as managing shares and permissions.

Some of the current nextcloud-link features are:

• Managing folder structure
• Retrieving file/folder information, such as their authors and modification dates
• Downloading and uploading files
• Moving, renaming and deleting files directly on Nextcloud

nextcloud-link , written in TypeScript but pre-built for es6 common.js, can be installed through npm, either as a pre-built npm package or direcly from github (for those who want to dig into, or tinker with its source):

~ $ npm install nextcloud-link
# OR
~ $ yarn install nextcloud-link

Using nextcloud-link

Using nextcloud-link ought to be fairly straight-forward. Import nextcloud-link as any other nodejs module, then establish a connection by passing it a configuration object:

import NextcloudClient from 'nextcloud-link';

// Supply a configuration object to NextcloudClient to
// set-up the connection
const client = NextcloudClient({
    url: 'http://localhost:16000,
    username: 'example',
    password: 'example'
});

The client object is now your interface to your nextcloud instance. Either pass it on to your storage repositories or use it as-is. Methods available on the client object return promises, allowing you to either use a Promise or await/async based-approach according to your preference.

// Managing files folders is just as easy
await this.client.touchFolder('/example');

// Add a file with content.
// The content argument can be either a string or a Buffer.
await this.client.put('/example/file.txt', 'Hello!');
await this.client.move('/example', '/otherlocation');

// And we can get the content back from the new location
const content: ReadableStream = await this.client.getReadStream('/otherlocation/file.txt');
// Or simply as a string
const text = await this.client.get('/otherlocation/file.txt');

We hope that nextcloud-link will take some of the burden when developing nodejs based applications that communicate with Nextcloud. You may find the full documentation of the nextcloud-link API on its github page. Please don’t hesitate to let us know if you run into any trouble.