{"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 `