{"id":15929,"library":"webdav","title":"WebDAV Client for Node.js and Browser","description":"The `webdav` library provides a promise-based WebDAV client for interacting with remote filesystems, supporting both Node.js and browser environments. Currently at version 5.9.0, the library is under active development, with version 4 in maintenance mode until January 2025, and earlier versions deprecated. It differentiates itself by prioritizing an easy-to-consume client API for common WebDAV services (like Nextcloud, ownCloud, Box, Yandex) over strict RFC adherence. Version 5 transitioned to ECMAScript Modules (ESM) and uses `@buttercup/fetch` for requests, replacing Axios from prior versions. This enables cross-platform compatibility, leveraging native `fetch` in browsers and `node-fetch` in Node.js, making it suitable for modern JavaScript projects.","status":"active","version":"5.9.0","language":"javascript","source_language":"en","source_url":"https://github.com/perry-mitchell/webdav-client","tags":["javascript","webdav","client","remote","sync","typescript"],"install":[{"cmd":"npm install webdav","lang":"bash","label":"npm"},{"cmd":"yarn add webdav","lang":"bash","label":"yarn"},{"cmd":"pnpm add webdav","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Handles cross-platform HTTP requests, abstracting `fetch` API differences between browser and Node.js environments. Uses `node-fetch` in Node.js.","package":"@buttercup/fetch","optional":false}],"imports":[{"note":"ESM-only since v5. The CommonJS `require` syntax will result in `ERR_REQUIRE_ESM`.","wrong":"const { createClient } = require('webdav');","symbol":"createClient","correct":"import { createClient } from 'webdav';"},{"note":"The `WebDAVClient` class is a named export, not a default export.","wrong":"import WebDAVClient from 'webdav';","symbol":"WebDAVClient","correct":"import { WebDAVClient } from 'webdav';"},{"note":"In v5, `import { createClient } from 'webdav'` works for most modern bundlers for both Node and browser. This explicit `/web` entry point was more critical in v4 and earlier for browser usage, but is still available.","wrong":"import { createClient } from 'webdav'; // for older browser environments that need an explicit web entrypoint","symbol":"createClient (web entrypoint)","correct":"import { createClient } from 'webdav/web';"},{"note":"Used for type-checking when working with file and directory statistics returned by methods like `getDirectoryContents`.","symbol":"FileStat (type)","correct":"import type { FileStat } from 'webdav';"}],"quickstart":{"code":"import { createClient, FileStat } from 'webdav';\nimport * as fs from 'fs/promises'; // For Node.js file system operations\nimport path from 'path';\n\n// Configure your WebDAV client\nconst webdavUrl = process.env.WEBDAV_URL ?? 'https://example.com/webdav/';\nconst username = process.env.WEBDAV_USERNAME ?? 'your-username';\nconst password = process.env.WEBDAV_PASSWORD ?? 'your-password';\n\nconst client = createClient(webdavUrl, {\n    username,\n    password\n});\n\nasync function runWebDAVOperations() {\n    try {\n        console.log(`Connecting to WebDAV at: ${webdavUrl}`);\n\n        // 1. List contents of the root directory\n        const contents: FileStat[] = await client.getDirectoryContents('/');\n        console.log('Root directory contents:');\n        contents.forEach(item => {\n            console.log(`- ${item.type === 'directory' ? 'Dir' : 'File'}: ${item.filename} (size: ${item.size ?? 'N/A'} bytes)`);\n        });\n\n        // 2. Create a new directory\n        const newDirPath = '/test-directory';\n        await client.createDirectory(newDirPath);\n        console.log(`Directory created: ${newDirPath}`);\n\n        // 3. Upload a file\n        const localFilePath = path.join(__dirname, 'test-upload.txt');\n        await fs.writeFile(localFilePath, 'Hello, WebDAV from checklist.day!');\n        const remoteFilePath = `${newDirPath}/uploaded-file.txt`;\n        await client.putFileContents(remoteFilePath, await fs.readFile(localFilePath));\n        console.log(`File uploaded: ${remoteFilePath}`);\n\n        // 4. Download the file and verify content\n        const downloadedContent = await client.getFileContents(remoteFilePath, { format: 'text' });\n        console.log(`Downloaded content from ${remoteFilePath}: \"${downloadedContent}\"`);\n\n        // 5. Delete the uploaded file and directory\n        await client.deleteFile(remoteFilePath);\n        console.log(`File deleted: ${remoteFilePath}`);\n        await client.deleteFile(newDirPath); // Can delete directories too\n        console.log(`Directory deleted: ${newDirPath}`);\n\n        // Clean up local test file\n        await fs.unlink(localFilePath);\n\n    } catch (error) {\n        console.error('WebDAV operation failed:', error);\n    }\n}\n\nrunWebDAVOperations();","lang":"typescript","description":"This quickstart demonstrates how to initialize a WebDAV client, list directory contents, create a directory, upload a file, download it, and finally clean up the created resources."},"warnings":[{"fix":"Migrate your project to use ES Modules (e.g., add `'type': 'module'` to `package.json` and use `import` statements) or use an earlier `webdav` version (4.x or below) which supports CommonJS.","message":"Version 5.x of the `webdav` library is ESM-only. CommonJS `require()` is no longer supported, requiring projects to adopt ES Modules syntax and configuration.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update any code that directly interacted with Axios-specific features or expected Axios-shaped error objects. Ensure your environment correctly handles `fetch` API polyfills if necessary, though `@buttercup/fetch` abstracts much of this.","message":"The underlying HTTP request library changed from Axios to `@buttercup/fetch` (which uses `node-fetch` in Node.js) in version 5.x. Direct reliance on Axios APIs or its error structure will no longer work.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Migrate to version 5.x as soon as possible to receive ongoing updates and security fixes. Review the breaking changes for v5 before migrating.","message":"Support for version 4.x of the `webdav` library will be dropped in January 2025. This means no further security or stability bugfixes will be provided for v4.","severity":"deprecated","affected_versions":"<5.0.0"},{"fix":"For optimal stability, performance, and support, use `webdav` v5 with Node.js 18 or newer. If using older Node.js versions, be prepared for potential compatibility issues and ensure thorough testing.","message":"While Node.js 14+ is officially supported for `webdav` v5, active testing only occurs on Node.js 18 and newer. Issues encountered on older Node.js versions may require community support for resolution.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Configure your project's bundler to correctly handle ESM modules. The explicit `/web` entry point is still available but often not required with modern bundlers.","message":"Browser environments using `webdav` v5 require an ESM-compatible bundler (e.g., Webpack, Rollup) as UMD module format support was removed. Loading via a `<script>` tag is no longer directly supported for browser builds.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change `require('webdav')` to `import { ... } from 'webdav';` and ensure your `package.json` has `'type': 'module'`, or downgrade to `webdav` version 4.x.","cause":"Attempting to `require()` the `webdav` package in a CommonJS environment when using version 5 or higher.","error":"ERR_REQUIRE_ESM"},{"fix":"Ensure you are using `import { createClient } from 'webdav';` for named exports, and avoid `import createClient from 'webdav';` unless the library explicitly exports a default. Check for correct module resolution in your build configuration.","cause":"Incorrect import of `createClient` or `WebDAVClient`, often due to mixing default/named imports or CJS/ESM patterns.","error":"TypeError: client.getDirectoryContents is not a function"},{"fix":"Verify Node.js version compatibility (>=14 for v5). If in a custom environment or older browser, ensure `global.fetch` is correctly polyfilled. `@buttercup/fetch` should handle `node-fetch` transparently in supported Node.js versions.","cause":"Potential issues with `node-fetch` resolution by `@buttercup/fetch` in Node.js, or `fetch` not being globally available or correctly polyfilled in certain environments.","error":"Error: fetch failed (in Node.js) or TypeError: fetch is not a function (in older Node.js/browser environments)"},{"fix":"Check the WebDAV server's configuration and permissions for the affected path. Some servers are read-only or restrict certain operations. Ensure your client's authentication details are correct.","cause":"The WebDAV server does not support the HTTP method being used (e.g., PUT, DELETE, MKCOL) for the requested resource or path, often due to server configuration or permissions.","error":"405 Method Not Allowed"}],"ecosystem":"npm"}