webdav client

The webdav library is a TypeScript-based client for NodeJS and the browser.

Version 5 (Current)

Version 5 uses ESM (ECMAScript Modules). To use it, your environment must be one of the following:

• A NodeJS project with "type": "module" in package.json.
• A web project bundled with a tool that handles ESM (e.g., Webpack).
• A React-Native project.

NodeJS Support (v5): Node 14+ is supported, though Node 18+ is recommended for active testing.

Browser Support

Version 5 provides an ESM-enabled bundle. Unlike version 4, you no longer need a specific web entry point; both webdav and webdav/web work in supported bundlers.

Warning: Streams (createReadStream and createWriteStream) are not available in the browser and will throw an exception if called.

React-Native is supported via a specific build. While imports are usually automatic, you can force the React-Native build by importing from webdav/react-native.

If the Metro build system fails to resolve the entry point, you may need to configure your babel.config.js using module-resolver to alias webdav to webdav/dist/react-native.

import { createClient } from "webdav/react-native";

// babel.config.js example
module.exports = {
    presets: ["module:metro-react-native-babel-preset"],
    plugins: [
        [
            "module-resolver",
            {
                alias: {
                    // Point the webdav client entry to the react native build:
                    webdav: "webdav/dist/react-native"
                },
                extensions: [".tsx", ".ts", ".js", ".jsx", ".json"]
            }
        ]
    ]
};

To use the library, call the createClient factory function with the WebDAV service URL and a configuration object. The configuration object can include authentication credentials like username and password.

const { createClient } = require("webdav");

const client = createClient(
    "https://webdav.example.com/marie123",
    {
        username: "marie",
        password: "myS3curePa$$w0rd"
    }
);

// Get directory contents
const directoryItems = await client.getDirectoryContents("/");

Install the webdav package as a dependency using npm to use the client in your project.

npm install webdav --save

The entityDecoder option controls how XML entity references are decoded. Use this to set security limits on entity expansion to prevent attacks.

const client = createClient("https://some-server.org", {
    username: "user",
    password: "pass",
    entityDecoder: {
        limit: {
            maxTotalExpansions: 1000,
            maxExpandedLength: 50000
        }
    }
});

For large files, use streams instead of fetching full contents into memory.

• createReadStream(filename, options): Returns a Stream.Readable. You can specify a range (start/end bytes) to stream parts of a file.
• createWriteStream(filename, options, callback): Returns a Stream.Writable. Use options.overwrite (defaults to true) to control if existing files are replaced.

// Stream a specific range of a file
client
    .createReadStream(
        "/video.mp4", 
        { range: { start: 0, end: 1024 } }
    ).pipe(fs.createWriteStream("~/video.mp4"));

// Upload a local file using a write stream
fs
    .createReadStream("~/Music/song.mp3")
    .pipe(client.createWriteStream("/music/song.mp3"));

Retrieve data from the server:

• getDirectoryContents(path, options): Returns an array of FileStat objects. Use options.deep: true for recursive listing and options.glob (using minimatch syntax) to filter files.
• getFileContents(filename, options): Returns file data. Use options.format: "text" for text files; otherwise, it defaults to "binary" (returning a Buffer).
• getQuota(options): Returns DiskQuota information (used/available space).

// Get all PNG/JPG files recursively
const images = await client.getDirectoryContents("/", { 
    deep: true, 
    glob: "/**/*.{png,jpg,gif}" 
});

// Fetch a text file
const str: string = await client.getFileContents("/config.json", { format: "text" });

// Get quota
const quota = await client.getQuota();

Use the following methods to manipulate the remote filesystem:

• copyFile(filename, destination, options): Copies a file.
• deleteFile(filename, options): Deletes a file.
• moveFile(filename, destinationFilename, options): Moves a file.
• createDirectory(path, options): Creates a directory. If options.recursive is true, it creates parent directories as needed.
• exists(path, options): Returns true if the path exists, false otherwise.

// Copy a file
await client.copyFile("/images/test.jpg", "/public/img/test.jpg");

// Create a directory recursively
await client.createDirectory("/data/system/storage", { recursive: true });

// Check if a file exists
if (await client.exists("/some/path") === false) {
    await client.createDirectory("/some/path");
}

Import createClient and AuthType from webdav to initialize a connection to a WebDAV server. You can specify the server URL and an options object containing authentication details like authType, username, and password.

import { AuthType, createClient } from "webdav";

const client = createClient("https://some-server.org", {
    authType: AuthType.Digest,
    username: "user",
    password: "pass"
});

If a specific WebDAV method is not implemented, use customRequest(path, requestOptions) to send a raw request. This method handles boilerplate authentication and headers automatically.

const resp: Response = await this.client.customRequest("/alrighty.jpg", {
    method: "PROPFIND",
    headers: {
        Accept: "text/plain",
        Depth: "0"
    }
});