{"id":22489095,"url":"https://github.com/nextcloud-libraries/nextcloud-files","last_synced_at":"2026-02-09T18:08:45.331Z","repository":{"id":37048688,"uuid":"192706603","full_name":"nextcloud-libraries/nextcloud-files","owner":"nextcloud-libraries","description":"Nextcloud Files helpers for Nextcloud apps and libraries https://npmjs.org/@nextcloud/files","archived":false,"fork":false,"pushed_at":"2026-02-07T12:46:37.000Z","size":32474,"stargazers_count":30,"open_issues_count":2,"forks_count":12,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-02-07T13:31:10.548Z","etag":null,"topics":["nextcloud","nextcloud-plugin"],"latest_commit_sha":null,"homepage":"https://nextcloud-libraries.github.io/nextcloud-files","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nextcloud-libraries.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-06-19T09:58:55.000Z","updated_at":"2026-02-07T12:44:39.000Z","dependencies_parsed_at":"2024-04-15T12:32:26.549Z","dependency_job_id":"44c3d59a-315b-4cf1-bbe3-1d18527ff7dd","html_url":"https://github.com/nextcloud-libraries/nextcloud-files","commit_stats":null,"previous_names":["nextcloud/nextcloud-files"],"tags_count":68,"template":false,"template_full_name":null,"purl":"pkg:github/nextcloud-libraries/nextcloud-files","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud-libraries%2Fnextcloud-files","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud-libraries%2Fnextcloud-files/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud-libraries%2Fnextcloud-files/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud-libraries%2Fnextcloud-files/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nextcloud-libraries","download_url":"https://codeload.github.com/nextcloud-libraries/nextcloud-files/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud-libraries%2Fnextcloud-files/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29274792,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T17:15:22.002Z","status":"ssl_error","status_checked_at":"2026-02-09T17:14:42.395Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nextcloud","nextcloud-plugin"],"created_at":"2024-12-06T17:19:13.922Z","updated_at":"2026-02-09T18:08:45.326Z","avatar_url":"https://github.com/nextcloud-libraries.png","language":"TypeScript","readme":"\u003c!--\n  - SPDX-FileCopyrightText: 2019-2024 Nextcloud GmbH and Nextcloud contributors\n  - SPDX-License-Identifier: AGPL-3.0-or-later\n--\u003e\n# @nextcloud/files\n[![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/)\n\nNextcloud Files helpers for Nextcloud apps and libraries.\n\nThis library provides three kinds of utils:\n1. WebDAV helper functions to work with the Nextcloud WebDAV interface.\n   Those functions are available in `@nextcloud/files/dav`\n2. Geneal purpose function related to files or folders, like filename validation.\n3. Functions and classes to interact with the Nextcloud **files** app, like registering a new view or a file action.\n\n## Compatibility\n\n| `@nextcloud/files` version | Supported | Nextcloud version |\n|----------------------------|-----------|-------------------|\n|                        4.x |        ✅ |               33+ |\n|                        3.x |        ✅ |             26-32 |\n|                        2.x |        ❌ |             23-25 |\n|                        1.x |        ❌ |             20-22 |\n\n## Usage examples\n\n### Files app\n\n#### Register a \"New\"-menu entry\n\nThe \"New\"-menu allows to create new entries or upload files, it is also possible for other apps to register their own actions here.\n\n```ts\nimport type { Entry } from '@nextcloud/files'\nimport { addNewFileMenuEntry } from '@nextcloud/files'\nimport { t } from '@nextcloud/l10n'\n\nconst myEntry: Entry = {\n\t// unique ID of the entry\n\tid: 'my-app',\n\t// The display name in the menu\n\tdisplayName: t('my-app', 'New something'),\n\t// optionally pass an SVG (string) to be used as the menu entry icon\n\ticonSvgInline: importedSVGFile,\n\thandler(context: Folder, content: Node[]): void {\n\t\t// `context` is the current active folder\n\t\t// `content` is the content of the currently active folder\n\t\t// You can add new files here e.g. use the WebDAV functions to create files.\n\t\t// If new content is added, ensure to emit the event-bus signals so the files app can update the list.\n\t}\n}\n\naddNewFileMenuEntry(myEntry)\n```\n\n#### Register a sidebar tab\n\nIt is possible to provide your own sidebar tabs for the files app.\nFor this you need to create a [custom web component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components),\nwhich 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).\n\nThis example will make use of the Vue framework for building a sidebar tab as this is the official UI framework for Nextcloud apps.\n\nThe sidebar tab consists of two parts:\n1. The web component which will be rendered within the sidebar.\n2. A definition object that provides all information needed by the files app.\n\n##### SidebarTab definition object\n\nThis object provides the requires information such as:\n- The order (to ensure a consistent tabs order)\n- The display name for the tab navigation\n- An icon, to be used in the tab navigation\n- A callback to check if the sidebar tab is enabled for the current node shown in the sidebar.\n- The web component tag name\n\nThe registration must happen in an `initScript`.\n\n```ts\nimport type { ISidebarTab } from '@nextcloud/files'\n\nimport { getSidebar } from '@nextcloud/files'\nimport { t } from '@nextcloud/l10n'\n\nconst MyTab: ISidebarTab = {\n\t// Unique ID of the tab\n\tid: 'my_app',\n\n\t// The display name in the tab list\n\tdisplayName: t('my_app', 'Sharing'),\n\n\t// Pass an SVG (string) to be used as the tab button icon\n\ticonSvgInline: '\u003csvg\u003e...\u003c/svg\u003e',\n\n\t// Lower values mean a more prominent position\n\torder: 50,\n\n\t// The tag name of the web component\n\ttagName: 'my_app-files_sidebar_tab',\n\n\t// Optional callback to check if the tab should be shown\n\tenabled({ node, folder, view }) {  \n\t\t// you can disable this tab for some cased based on:  \n\t\t// - node: The node the sidebar was opened for  \n\t\t// - folder: The folder currently shown in the files app  \n\t\t// - view: The currently active files view  \n\t\treturn true  \n\t},\n\n\t// Optional, recommended to large tabs  \n\tasync onInit() {\n\t\t// This is called when the tab is about to be activated the first time.  \n\t\t// So this can be used to do some initialization or even to define the web component.  \n\t},\n}\n\n// the you need to register it in the sidebar\ngetSidebar()\n\t.registerTab(MyTab)\n```\n\n##### SidebarTab web component\n\nThe web component needs to have those properties:\n- node of type `INode`\n- folder of type `IFolder`\n- view of type `IView`\n- active of type `boolean`\n\nWhen using Vue you need to first create the Vue component:\n\n```vue\n\u003cscript setup lang=\"ts\"\u003e\nimport type { IFolder, INode, IView } from '@nextcloud/files'\n\ndefineProps\u003c{\n\tnode: INode\n\tfolder: IFolder\n\tview: IView\n\tactive: boolean\n}\u003e()\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n\t\u003cdiv\u003e\n\t\t\u003cdiv\u003eShowing node: {{ node.source }}\u003c/div\u003e\n\t\t\u003cdiv\u003e... in folder: {{ folder.source }}\u003c/div\u003e\n\t\t\u003cdiv\u003e... with view: {{ view.id }}\u003c/div\u003e\n\t\u003c/div\u003e\n\u003c/template\u003e\n```\n\nWhich then can be wrapped in a web component and registered.\n\n```ts\nimport { getSidebar } from '@nextcloud/files'\nimport { defineAsyncComponent, defineCustomElement } from 'vue'\n\ngetSidebar().registerTab({\n\t// ...\n\n\ttagName: `my_app-files_sidebar_tab`,\n\n\tonInit() {\n\t\tconst MySidebarTab = defineAsyncComponent(() =\u003e import('./views/MySidebarTab.vue'))\n\t\t// make sure to disable the shadow root to allow theming with Nextcloud provided global styles.\n\t\tconst MySidebarTabWebComponent = defineCustomElement(MySidebarTab, { shadowRoot: false })\n\t\tcustomElements.define('my_app-files_sidebar_tab', MySidebarTabWebComponent)\n\t},\n})\n```\n\n### WebDAV\nThe `getClient` exported function returns a webDAV client that's a wrapper around [webdav's webDAV client](https://www.npmjs.com/package/webdav).\nAll its methods are available here.\n\n#### Using WebDAV to query favorite nodes\n\n```ts\nimport { getClient, defaultRootPath, getFavoriteNodes } from '@nextcloud/files/dav'\n\nconst client = getClient()\n// query favorites for the root folder (meaning all favorites)\nconst favorites = await getFavoriteNodes(client)\n// which is the same as writing:\nconst favorites = await getFavoriteNodes(client, '/', defaultRootPath)\n```\n\n#### Using WebDAV to list all nodes in directory\n\n```ts\nimport {\n    getClient,\n    getDefaultPropfind,\n    resultToNode,\n    defaultRootPath,\n    defaultRemoteURL\n} from '@nextcloud/files/dav'\n\n// Get the DAV client for the default remote\nconst client = getClient()\n// which is the same as writing\nconst client = getClient(defaultRemoteURL)\n// of cause you can also configure another WebDAV remote\nconst client = getClient('https://example.com/dav')\n\nconst path = '/my-folder/' // the directory you want to list\n\n// Query the directory content using the webdav library\n// `davRootPath` is the files root, for Nextcloud this is '/files/USERID', by default the current user is used\nconst results = client.getDirectoryContents(`${defaultRootPath}${path}`, {\n    details: true,\n    // Query all required properties for a Node\n    data: getDefaultPropfind()\n})\n\n// Convert the result to an array of Node\nconst nodes = results.data.map((result) =\u003e resultToNode(r))\n// If you specified a different root in the `getDirectoryContents` you must add this also on the `resultToNode` call:\nconst nodes = results.data.map((result) =\u003e resultToNode(r, myRoot))\n// Same if you used a different remote URL:\nconst nodes = results.data.map((result) =\u003e resultToNode(r, myRoot, myRemoteURL))\n\n```\n\n#### Using WebDAV to get a Node from a file's name\n\n```ts\n\timport { getClient, davGetDefaultPropfind, resultToNode, davRootPath } from '@nextcloud/files'\n\timport { emit } from '@nextcloud/event-bus'\n\tconst client = getClient()\n\tclient.stat(`${davRootPath}${filename}`, {\n\t\tdetails: true,\n\t\tdata: davGetDefaultPropfind(),\n\t}).then((result) =\u003e {\n\t\tconst node = resultToNode(result.data)\n\t\temit('files:node:updated', node)\n\t})\n```\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnextcloud-libraries%2Fnextcloud-files","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnextcloud-libraries%2Fnextcloud-files","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnextcloud-libraries%2Fnextcloud-files/lists"}