Repo structure and (published) packages

From a developer’s perspective, the most important parts of the ownCloud Web repo are the following files and folders:

The /dev folder contains all the configuration files that are needed in the docker-compose.yml file. This docker compose stack contains all the backend and testing related infrastructure that is needed for an out-of-the-box usable localhost development setup, as described in the tooling section.

Within the /docs folder you will find all the documentation source documents that get published to the dev docs.

We’re using the ownCloud Web repo as a mono repo. It contains a variety of packages. Some of them get published to npmjs.com, others define the core packages, apps and extensions that are the foundation of the ownCloud Web release artifact.

Having these packages side by side within the /packages folder of the repo is possible because of a pnpm feature called Workspaces. You can learn more about that by visiting the pnpm docs.

For historic reasons, there are two end-to-end test collections in the ownCloud Web project. The older one lives in /tests/acceptance, using Nightwatch.js. The newer one lives in /tests/e2e, using Playwright. We’re slowly moving away from the nightwatch.js-based e2e tests. As our coverage with playwright based e2e tests grows continuously, it might happen that you will not find the /tests/acceptance folder anymore. If that’s the case at the time of reading this, those are happy times. You’re more than welcome to make a pull request and adjust this section of the docs accordingly. :-)

The rest of the folder contains helpers and configuration files for our automated testing infrastructure.

You can read more about testing in our testing section

This is probably no surprise: the root level package.json file defines the project information, build scripts, dependencies and some more details. Each package in /packages can and most likely will contain another package.json which does the same for the respective package.

We’re working with Vite as a local development server and build tool. vite.config.ts is the main configuration file for that. You can read more about the usage in our tooling section.

Each package in the /packages folder can - not exclusively, but most commonly - consist of

• source code (/src),
• unit tests (/tests),
• translations (/l10n) and
• a package.json file for package specific details and dependencies.

Some of our packages in /packages are pure helper packages which ensure a common code style and build configuration for all our internal (mono repo) and external packages. We encourage you to make use of the very same packages. This helps the community understand code more easily, even when coming from different developers or vendors in the ownCloud Web ecosystem.

Namely those packages are

• /packages/babel-preset
• /packages/eslint-config
• /packages/extension-sdk
• /packages/prettier-config
• /packages/tsconfig/

The ownCloud Design System (/packages/design-system) is a collection of components, design tokens and styles which ensure a unique and consistent look and feel and branding throughout the ownCloud Web ecosystem. We hope that you use it, too, so that your very own apps and extensions will blend in with all the others. Documentation and code examples can be found in the design system documentation.

The ownCloud Design System is a standalone project, but to make development easier we have the code in our mono repo. We’re planning to publish it on npmjs.com as @ownclouders/design-system as soon as possible. Since it’s bundled with ownCloud Web, you should not bundle it with your app or extension.

The client package (/packages/web-client) serves as an abstraction layer for the various ownCloud APIs, like LibreGraph, WebDAV and OCS. The package provides TypeScript interfaces for various entities (like files, folders, shares and spaces) and makes sure that raw API responses are properly transformed so that you can deal with more useful objects. The web-client package gets published on npmjs.com as @ownclouders/web-client.

Dedicated documentation for the web-client package is not available, yet, since our extension system is still work in progress. However, the package’s README.md gives you a few examples on how to use it.

The web-pkg package (/packages/web-pkg) is a collection of opinionated components, composables, types and other helpers that aim at making your app and extension developer experience as easy and seamless as possible. The web-pkg package gets published on npmjs.com as @ownclouders/web-pkg.

Dedicated documentation for the web-pkg package is not available, yet, since our extension system is still work in progress.

At the very heart of ownCloud Web, the web-runtime is responsible for dependency injection, app bootstrapping, configuration, authentication, data preloading and much more. It is very likely that you will never get in touch with it as most of the developer-facing features are exposed via web-pkg. If you have more questions about this package, please join our public chat and simply ask or write an issue in our issue tracker.

Both web-app-admin-settings and web-app-files are standalone apps which are bundled with the default ownCloud Web release artifact.

Apps which fall into the categories viewer or editor can be opened from the context of a file or folder. This mostly happens from within the files app. We currently bundle the following apps with the default ownCloud Web release artifact:

• web-app-draw-io an editor for .drawio files
• web-app-external an iframe integration of all the apps coming from the app provider (e.g. OnlyOffice, Collabora Online and others)
• web-app-pdf-viewer a viewer for .pdf files, which relies on native PDF rendering support from the browser
• web-app-preview a viewer for various media files (audio / video / image formats)
• web-app-text-editor a simple editor for .txt, .md and other plain text files

If you’re interested in writing your own viewer or editor app for certain file types, please get in touch with us for more info.