payload-nextcloud

Nextcloud storage adapter for Payload CMS (Payload 3). It integrates Nextcloud WebDAV for file uploads and can automatically create public share links via the OCS Files Sharing API.

Features

• Upload files to Nextcloud via WebDAV
• Optional public share link creation (sets nextcloud.share_url on uploaded document)
• Exposes a direct WebDAV URL (nextcloud.webdav_url) for internal use
• Adds an admin sidebar group with Nextcloud metadata and sync status fields

Requirements

• Payload ^3.37.0 (peerDependency)
• Node 18+ (or 20+)
• A Nextcloud account and preferably an App Password (token)

Install

pnpm add payload-nextcloud @payloadcms/plugin-cloud-storage webdav

Quick start Add the plugin to your Payload config and supply Nextcloud credentials and WebDAV settings.

// payload.config.ts
import { payloadNextcloud } from 'payload-nextcloud'

export default buildConfig({
  collections: [
    {
      slug: 'media',
      upload: {
        mimeTypes: ['image/*', 'application/pdf'],
      },
      fields: [/* your fields */],
    },
  ],
  plugins: [
    payloadNextcloud({
      collections: {
        // enable integration for a collection
        media: true,
      },
      nextcloud: {
        auth: {
          username: process.env.NEXTCLOUD_USERNAME || '',
          // Prefer app password (token). Provide ONE of token or password.
          token: process.env.NEXTCLOUD_TOKEN,
          // password: process.env.NEXTCLOUD_PASSWORD,
        },
        metadata: {
          // optional custom WebDAV properties namespace + field map
          customPropertiesNamespace: 'http://payloadcms.com/ns/nextcloud',
          fieldMap: {
            'nextcloud.custom_metadata.title': 'pc:title',
            'nextcloud.custom_metadata.description': 'pc:description',
          },
        },
        webdav: {
          // Base Nextcloud URL, e.g. https://cloud.example.com
          baseUrl: process.env.NEXTCLOUD_URL || '',
          // If omitted, defaults to /remote.php/dav/files/{username}
          filesPath: process.env.NEXTCLOUD_FILESPATH,
          // Optional root directory under the user's files area
          rootDirectory: process.env.NEXTCLOUD_ROOTDIR || '/Payload',
          timeoutMs: 15000,
          // verifyTLS: false, // only in dev with self-signed certs
        },
      },
    }),
  ],
})

What gets added to your Media collection

• A nextcloud group in the sidebar with read-only fields:
  • fileId, path, name, size, mimeType, etag, lastModified, permissions, isDirectory
  • webdav_url (direct WebDAV path)
  • share_url (public link if sharing succeeds)
• A custom_metadata group (optional editable fields you can sync via WebDAV PROPPATCH)
• A sync_status group to track last sync and errors

Public share links

• On successful upload, the plugin attempts to create a public share via Nextcloud OCS API.
• If successful, nextcloud.share_url will be set to the base public link.
• If you prefer a direct binary URL, consider using ${share_url}/download in your app.

Nextcloud app password guidance

• Strongly recommended: create an App Password in Nextcloud and use it as your token.
  • Nextcloud: Settings → Security → Create new app password → copy the generated password
  • Use that value as NEXTCLOUD_TOKEN; do not share your main account password
• OCS API requires the OCS-APIRequest: true header and Basic auth—we handle this internally.
• For self-signed certificates in dev, you can temporarily set verifyTLS: false (avoid in production).

Development notes

• This package’s top-level exports point to dist, not src.
• You need to build before running the dev project:
  • pnpm build
  • pnpm dev
• The dev folder is for local testing only and is not published.

License MIT

Author / Support Update package.json with your name and repository URL. Tag your repo with payload-plugin on GitHub for discoverability.