# @nextcloud/files

> Nextcloud files utils

Latest version **4.1.1** (published 2026-10-21) · AGPL-3.0-or-later license · 0 weekly downloads

## Install

```sh
npm install @nextcloud/files
pnpm add @nextcloud/files
yarn add @nextcloud/files
bun add @nextcloud/files
```

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 4.1.1 |
| Published | 2026-10-21 |
| First published | 2019-10-02 |
| Weekly downloads | 0 |
| License | AGPL-3.0-or-later |
| TypeScript types | none |
| Module format | ESM |
| Node | ^24.0.0 \|\| >=26.0.0 |
| Dependencies | 13 |
| Unpacked size | 436.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 32 |
| Author | Nextcloud GmbH and Nextcloud contributors |
| Maintainers | icewind1991, skjnldsv, christophwurst, juliushaertl, nickvergessen, artonge, gretadoci, mejo-, susnux |
| Keywords | nextcloud, files, library |

## Links

- npm: https://www.npmjs.com/package/@nextcloud/files
- Repository: https://github.com/nextcloud-libraries/nextcloud-files
- Issues: https://github.com/nextcloud-libraries/nextcloud-files/issues
- npm.io page: https://npm.io/package/@nextcloud/files

## Dependencies (13)

- [is-svg](https://npm.io/package/is-svg.md) ^6.1.0
- [webdav](https://npm.io/package/webdav.md) ^5.11.0
- [p-queue](https://npm.io/package/p-queue.md) ^9.3.3
- [axios-retry](https://npm.io/package/axios-retry.md) ^4.5.0
- [@nextcloud/auth](https://npm.io/package/@nextcloud/auth.md) ^2.6.0
- [@nextcloud/l10n](https://npm.io/package/@nextcloud/l10n.md) ^3.4.1
- [@nextcloud/axios](https://npm.io/package/@nextcloud/axios.md) ^2.6.0
- [@nextcloud/paths](https://npm.io/package/@nextcloud/paths.md) ^3.1.0
- [@nextcloud/logger](https://npm.io/package/@nextcloud/logger.md) ^3.0.3
- [@nextcloud/router](https://npm.io/package/@nextcloud/router.md) ^3.2.0
- [@nextcloud/sharing](https://npm.io/package/@nextcloud/sharing.md) ^0.4.0
- [@nextcloud/capabilities](https://npm.io/package/@nextcloud/capabilities.md) ^1.2.1
- [typescript-event-target](https://npm.io/package/typescript-event-target.md) ^1.1.2

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 4.1.1 (latest) — 2026-10-21
- 3.13.0 (stable) — 2026-10-21
- 4.1.0-beta.2 (next) — 2026-08-25
- 4.1.0 — 2026-09-17
- 4.1.0-beta.1 — 2026-07-20
- 4.1.0-beta.0 — 2026-06-12
- 4.0.0 — 2026-02-10
- 4.0.0-rc.3 — 2026-02-09
- 4.0.0-rc.2 — 2026-02-07
- 4.0.0-rc.1 — 2026-02-05
- 4.0.0-rc.0 — 2026-01-15
- 4.0.0-beta.9 — 2026-01-13
- 4.0.0-beta.8 — 2025-12-29
- 4.0.0-beta.7 — 2025-12-23
- 4.0.0-beta.6 — 2025-12-22
- … 64 more at https://npm.io/package/@nextcloud/files/versions

## README

<!--
  - SPDX-FileCopyrightText: 2019-2024 Nextcloud GmbH and Nextcloud contributors
  - SPDX-License-Identifier: AGPL-3.0-or-later
-->
# @nextcloud/files
[![npm last version](https://img.shields.io/npm/v/@nextcloud/files.svg?style=flat-square)](https://www.npmjs.com/package/@nextcloud/files) [![REUSE status](https://api.reuse.software/badge/github.com/nextcloud-libraries/nextcloud-files)](https://api.reuse.software/info/github.com/nextcloud-libraries/nextcloud-files) [![Code coverage](https://img.shields.io/codecov/c/github/nextcloud-libraries/nextcloud-files?style=flat-square)](https://app.codecov.io/gh/nextcloud-libraries/nextcloud-files) [![Project documentation](https://img.shields.io/badge/documentation-online-blue?style=flat-square)](https://nextcloud-libraries.github.io/nextcloud-files/)

Nextcloud Files helpers for Nextcloud apps and libraries.

This library provides three kinds of utils:
1. WebDAV helper functions to work with the Nextcloud WebDAV interface.
   Those functions are available in `@nextcloud/files/dav`
2. Geneal purpose function related to files or folders, like filename validation.
3. Functions and classes to interact with the Nextcloud **files** app, like registering a new view or a file action.

## Compatibility

| `@nextcloud/files` version | Supported | Nextcloud version |
|----------------------------|-----------|-------------------|
|                        4.x |        ✅ |               33+ |
|                        3.x |        ✅ |             26-32 |
|                        2.x |        ❌ |             23-25 |
|                        1.x |        ❌ |             20-22 |

## Usage examples

### Files app

#### Register a "New"-menu entry

The "New"-menu allows to create new entries or upload files, it is also possible for other apps to register their own actions here.

```ts
import type { Entry } from '@nextcloud/files'
import { addNewFileMenuEntry } from '@nextcloud/files'
import { t } from '@nextcloud/l10n'

const myEntry: Entry = {
	// unique ID of the entry
	id: 'my-app',
	// The display name in the menu
	displayName: t('my-app', 'New something'),
	// optionally pass an SVG (string) to be used as the menu entry icon
	iconSvgInline: importedSVGFile,
	handler(context: Folder, content: Node[]): void {
		// `context` is the current active folder
		// `content` is the content of the currently active folder
		// You can add new files here e.g. use the WebDAV functions to create files.
		// If new content is added, ensure to emit the event-bus signals so the files app can update the list.
	}
}

addNewFileMenuEntry(myEntry)
```

#### Register a sidebar tab

It is possible to provide your own sidebar tabs for the files app.
For this you need to create a [custom web component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components),
which can either be done without any framework by using vanilla JavaScript but is also [possible with Vue](https://vuejs.org/guide/extras/web-components#building-custom-elements-with-vue).

This example will make use of the Vue framework for building a sidebar tab as this is the official UI framework for Nextcloud apps.

The sidebar tab consists of two parts:
1. The web component which will be rendered within the sidebar.
2. A definition object that provides all information needed by the files app.

##### SidebarTab definition object

This object provides the requires information such as:
- The order (to ensure a consistent tabs order)
- The display name for the tab navigation
- An icon, to be used in the tab navigation
- A callback to check if the sidebar tab is enabled for the current node shown in the sidebar.
- The web component tag name

The registration must happen in an `initScript`.

```ts
import type { ISidebarTab } from '@nextcloud/files'

import { getSidebar } from '@nextcloud/files'
import { t } from '@nextcloud/l10n'

const MyTab: ISidebarTab = {
	// Unique ID of the tab
	id: 'my_app',

	// The display name in the tab list
	displayName: t('my_app', 'Sharing'),

	// Pass an SVG (string) to be used as the tab button icon
	iconSvgInline: '<svg>...</svg>',

	// Lower values mean a more prominent position
	order: 50,

	// The tag name of the web component
	tagName: 'my_app-files_sidebar_tab',

	// Optional callback to check if the tab should be shown
	enabled({ node, folder, view }) {  
		// you can disable this tab for some cased based on:  
		// - node: The node the sidebar was opened for  
		// - folder: The folder currently shown in the files app  
		// - view: The currently active files view  
		return true  
	},

	// Optional, recommended to large tabs  
	async onInit() {
		// This is called when the tab is about to be activated the first time.  
		// So this can be used to do some initialization or even to define the web component.  
	},
}

// the you need to register it in the sidebar
getSidebar()
	.registerTab(MyTab)
```

##### SidebarTab web component

The web component needs to have those properties:
- node of type `INode`
- folder of type `IFolder`
- view of type `IView`
- active of type `boolean`

When using Vue you need to first create the Vue component:

```vue
<script setup lang="ts">
import type { IFolder, INode, IView } from '@nextcloud/files'

defineProps<{
	node: INode
	folder: IFolder
	view: IView
	active: boolean
}>()
</script>

<template>
	<div>
		<div>Showing node: {{ node.source }}</div>
		<div>... in folder: {{ folder.source }}</div>
		<div>... with view: {{ view.id }}</div>
	</div>
</template>
```

Which then can be wrapped in a web component and registered.

```ts
import { getSidebar } from '@nextcloud/files'
import { defineAsyncComponent, defineCustomElement } from 'vue'

getSidebar().registerTab({
	// ...

	tagName: `my_app-files_sidebar_tab`,

	onInit() {
		const MySidebarTab = defineAsyncComponent(() => import('./views/MySidebarTab.vue'))
		// make sure to disable the shadow root to allow theming with Nextcloud provided global styles.
		const MySidebarTabWebComponent = defineCustomElement(MySidebarTab, { shadowRoot: false })
		customElements.define('my_app-files_sidebar_tab', MySidebarTabWebComponent)
	},
})
```

### WebDAV
The `getClient` exported function returns a webDAV client that's a wrapper around [webdav's webDAV client](https://www.npmjs.com/package/webdav).
All its methods are available here.

#### Using WebDAV to query favorite nodes

```ts
import { getClient, defaultRootPath, getFavoriteNodes } from '@nextcloud/files/dav'

const client = getClient()
// query favorites for the root folder (meaning all favorites)
const favorites = await getFavoriteNodes(client)
// which is the same as writing:
const favorites = await getFavoriteNodes(client, '/', defaultRootPath)
```

#### Using WebDAV to list all nodes in directory

```ts
import {
    getClient,
    getDefaultPropfind,
    resultToNode,
    defaultRootPath,
    defaultRemoteURL
} from '@nextcloud/files/dav'

// Get the DAV client for the default remote
const client = getClient()
// which is the same as writing
const client = getClient(defaultRemoteURL)
// of cause you can also configure another WebDAV remote
const client = getClient('https://example.com/dav')

const path = '/my-folder/' // the directory you want to list

// Query the directory content using the webdav library
// `davRootPath` is the files root, for Nextcloud this is '/files/USERID', by default the current user is used
const results = client.getDirectoryContents(`${defaultRootPath}${path}`, {
    details: true,
    // Query all required properties for a Node
    data: getDefaultPropfind()
})

// Convert the result to an array of Node
const nodes = results.data.map((result) => resultToNode(r))
// If you specified a different root in the `getDirectoryContents` you must add this also on the `resultToNode` call:
const nodes = results.data.map((result) => resultToNode(r, myRoot))
// Same if you used a different remote URL:
const nodes = results.data.map((result) => resultToNode(r, myRoot, myRemoteURL))

```

#### Using WebDAV to get a Node from a file's name

```ts
import {
	getClient,
	getDefaultPropfind,
	resultToNode,
	defaultRootPath,
} from '@nextcloud/files/dav'
import { emit } from '@nextcloud/event-bus'

const client = getClient()
client.stat(`${defaultRootPath}${filename}`, {
	details: true,
	data: getDefaultPropfind(),
}).then((result) => {
	const node = resultToNode(result.data)
	emit('files:node:updated', node)
})
```

---
_Source: https://npm.io/package/@nextcloud/files · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
