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.
We’re using the Playwright for UI testing. The UI tests are located in the /tests/e2e
You’re more than welcome to make a pull request and adjust this section of the docs accordingly. :-) 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.jsonfile 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-epub-readera simple reader for.epubfilesweb-app-externalan iframe integration of all the apps coming from the app provider (e.g. OnlyOffice, Collabora Online and others)web-app-pdf-viewera viewer for.pdffiles, which relies on native PDF rendering support from the browserweb-app-previewa viewer for various media files (audio / video / image formats)web-app-text-editora simple editor for.txt,.mdand 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.
Additional unit testing code lives in test-helpers.