# Nextcloud Contacts: a CardDAV address book on the Nextcloud server

> The Nextcloud Contacts app gives a Nextcloud instance a browsable address book backed by the server's CardDAV endpoint, with sharing and Calendar integration, and it is only the frontend half of the picture. The app sticks to vCard 3.0 and 4.0 and refuses custom properties on purpose.

**nextcloud/contacts** — 📇 Contacts app for Nextcloud

- Repository: https://github.com/nextcloud/contacts
- Website: https://apps.nextcloud.com/apps/contacts
- Stars: 648 · Forks: 223
- Language: JavaScript
- License: AGPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/nextcloud-contacts

## A frontend for a CardDAV endpoint that lives in the server

The first thing to understand about Nextcloud Contacts is that it is not a contact database. The support section of the README states it directly: this repository only manages the frontend, and if you find bugs or have problems with the CardDAV backend you should ask the Nextcloud server team for help.

That boundary decides everything about how you use the app. The storage, the CardDAV implementation and the synchronisation protocol all live in the Nextcloud server. What this repository provides is the web interface that talks to them, plus the app packaging that puts it in the app store.

The interface lets you sync contacts from various devices with your Nextcloud and edit them online. Under the hood the app relies on the SabreDAV library, which the project credits as the reason the project did not reinvent the wheel. That matters in practice because SabreDAV is the same CardDAV stack used across the wider Nextcloud ecosystem, so a contact created in the web interface and a contact created by a phone both end up as vCard data served by the same server component.

The dependency list in package.json confirms the shape. The client side pulls in @nextcloud/cdav-library for CardDAV access, along with @nextcloud/axios for HTTP, @nextcloud/auth, @nextcloud/dialogs, @nextcloud/event-bus, @nextcloud/initial-state, @nextcloud/files, @nextcloud/capabilities and @mattkrick/sanitize-svg for sanitising SVG content that arrives with a contact card.

The licensing is AGPL-3.0-or-later, with SPDX headers attributing Nextcloud GmbH and contributors from 2016 to 2024, and ownCloud, Inc. for the earlier 2015 to 2016 period.

## vCard 3.0 and 4.0 only, and why custom properties are refused

The app supports vCard 3.0 and 4.0 and states that it is compatible with the same browsers as the server except Internet Explorer.

The interesting part of the project is its answer to the request to add a custom property. The maintainers call it a complicated answer and then explain it clearly. They did not invent the way contacts work, they follow the official vCard format, and that format includes a predefined set of properties which other applications and devices already support, naming Android, iOS, Windows and GNOME.

The consequence they draw is that adding a custom property would make the card compatible with Nextcloud only, would not be understood by any other client, and would make it harder for them to guarantee its sustainability over time. The suggestion is to use the Notes field for custom data.

That is a defensible position, and it is worth understanding rather than fighting. A contact card that only your own server understands is a card that will lose its extra field the first time someone syncs with a phone. Using a standard field keeps the card portable at the cost of structure.

It also explains why the browser support statement exists. CardDAV clients in the wild are numerous, and each of them has its own idea of which vCard version it will accept, so pinning the app to two versions is how the project keeps the ecosystem interoperable.

## The features that actually make it worth installing

Four capabilities are highlighted, and they are the reason to install the app rather than a standalone contact manager.

Integration with other Nextcloud apps comes first, with Mail and Calendar named as the current integrations. The Calendar one has a concrete form: you can sync birthdays and other recurring events with your Nextcloud Calendar, which turns a contact list into a source of dates without any extra configuration from the user.

Sharing of address books is the second. You can share your contacts with friends or coworkers, and for a Nextcloud deployment this matters more than it would in a standalone app because sharing is handled by the server's own permissions model rather than by a second access control layer inside the app.

Third, and the one people tend to miss, the frontend is based on the open SabreDAV library. For a self hosted setup this is the difference between a client you can debug and one you cannot, because the protocol layer is shared with the rest of the server ecosystem and is therefore documented and maintained elsewhere.

The fourth is simply that the app is distributed through the Nextcloud app store and can be installed directly from a Nextcloud installation, with release tarballs hosted at the nextcloud-releases/contacts GitHub repository. That last detail matters more than it looks, given the release history discussed below.

## Building the app and running the front-end tests

The build documentation lists the commands, and the first block covers setup and a production build:

```bash
composer install
npm ci
npm run build
```

The dependency step runs both ecosystems. Composer installs the PHP side, npm ci installs the JavaScript side from the lockfile, and npm run build produces the production bundle. The package.json scripts map directly onto the documented commands, with build set to vite build --mode production, dev to vite build --mode development, and watch to vite build --mode development --watch for continuous rebuilds.

The front-end tests run under Jest:

```bash
npm run test
```

and the continuous variant is:

```bash
npm run test:watch
```

Beyond that, the script list in package.json shows the wider tooling. Jest handles the unit tests, Playwright handles the end-to-end tests with a separate ui mode, ESLint and stylelint cover JavaScript, TypeScript, Vue and SCSS, and the coverage script runs jest with the coverage flag.

The packaging side is handled by krankerl. The Makefile wraps it, with the appstore target running krankerl package, and it defines where the build artifacts go, the build/artifacts directory, along with the appstore_package_name. The Makefile also has clean targets that remove the js and node_modules and vendor directories, and it is the Krankerl tool that produces the tarball the app store accepts.

The repository also carries a .php-cs-fixer.dist.php, psalm.xml, rector.php, renovate.json, a .tx directory for translation, and a l10n directory, which is the usual shape for a Nextcloud app that has to pass the server's own checks.

## Version numbers that do not line up with the release tags

The version information in this repository is genuinely confusing at first glance, and getting it right matters if you plan to install from a tarball rather than the app store.

The listed GitHub releases are v5.3.0-rc.1 from 2023-05-17, v5.0.1 from 2022-10-18 and v5.0.0-rc1 from 2022-10-02. Meanwhile the version field in package.json reads 8.10.0-dev.0, and the CHANGELOG.md file is at the root of the repository.

The explanation is in the installation section. The app is distributed through the app store, and release tarballs are hosted at https://github.com/nextcloud-releases/contacts/releases. So the nextcloud-releases repository is where the actual shipped versions live, and the releases attached to the main repository are a partial view. A tag such as v5.3.0-rc.1 on the development repository does not mean version 5.3 is what you get from the app store.

For an administrator, the practical rule is to read the version from the app store or from the nextcloud-releases tarball, and to use the app store's own upgrade mechanism, since the documentation points at the Nextcloud admin manual for installing and updating apps.

The last push to the repository was on 2026-10-19, so the frontend is receiving changes regularly. The project is not archived, and the maintainers listed are Hamza Mahjoubi and the Nextcloud Groupware team, with the groupware team also named as the place to go for CardDAV backend problems.

## Contributing and the conventions the project enforces

The project documents how to contribute, and it does so with a few concrete rules rather than general encouragement.

Commits follow the Conventional Commits specification, which the documentation links. That matters more than it might seem for a Nextcloud app, because the release process is driven by commit message shape, so an unstructured commit can end up in a release under a heading you did not intend or in none at all.

Pull requests follow the general open source guide for opening one. The documentation also suggests joining by going through the issue list and fixing something, which is a reasonable route for a project with a large issue backlog.

There is a code of conduct section pointing at the Nextcloud community values, and the project participates in the community events described there, including conferences and hackweeks.

The repository layout backs all of this up. The src directory holds the application code, lib and templates hold the PHP backend part of the app and its server side templates, l10n holds translations, tests holds the test suites with a __mocks__ directory, and build holds the built assets. There is a jest.config.cjs for the unit tests and a playwright.config.js for the browser tests, so the two test layers are configured separately and run under the npm scripts test, test:e2e and test:coverage.

There is also an AGENTS.md file at the root, which in this project family usually carries guidance for automated coding agents working in the tree. Combined with the .coderabbit.yaml configuration and a Renovate configuration for dependency updates, the repository shows a modern automation setup layered on top of a long-lived application.

## Conclusion

Adopt Nextcloud Contacts when you already run Nextcloud and want a shared, editable address book that phones and desktop clients can sync through CardDAV, since the app is a frontend for the server's own backend. Do not adopt it for custom contact fields, because the maintainers state that adding a non-standard property breaks compatibility with other clients and suggest using the Notes field instead, and do not adopt it expecting to fix CardDAV server bugs here, since this repository only manages the frontend. Before installing, check the release tarballs rather than the app store tag list, because the newest listed GitHub release is v5.3.0-rc.1 from 2023 while the working tree reports version 8.10.0-dev.0.

## FAQ

### Where are the Nextcloud Contacts releases published?

The app is distributed through the Nextcloud app store and release tarballs are hosted at https://github.com/nextcloud-releases/contacts/releases. The releases listed on the main repository are only a partial view, and package.json shows version 8.10.0-dev.0.

### Which vCard versions does the Nextcloud Contacts app support?

Only vCard 3.0 and vCard 4.0. The app states it is compatible with the same browsers as the Nextcloud server except Internet Explorer.

### Can I add a custom property to a contact in Nextcloud Contacts?

The maintainers advise against it, since a custom property would only be understood by Nextcloud clients and not by other applications or devices. They suggest using the Notes field for custom data instead.

### Does the Nextcloud Contacts repository contain the CardDAV backend?

No. The repository only manages the frontend. Problems with the CardDAV backend should be reported to the Nextcloud server team, as the project documentation states.

### How do I build the Nextcloud Contacts app locally and run its tests?

Run composer install, npm ci and npm run build for a production build, or npm run dev and npm run watch for development. The front-end tests run with npm run test, or npm run test:watch to rerun on every change, and end-to-end tests use Playwright.

## Sources

- [License: AGPL-3.0](https://github.com/nextcloud/contacts/blob/main/LICENSE)
- [nextcloud/contacts on GitHub](https://github.com/nextcloud/contacts)
- [Project website](https://apps.nextcloud.com/apps/contacts)
- [README](https://github.com/nextcloud/contacts/blob/main/README.md)
- [Releases](https://github.com/nextcloud/contacts/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nextcloud-contacts