Skip to main content

App Hub Submission Guidelines

Submitting your app to the DHIS2 App Hub is an easy way to share your app with the DHIS2 community around the world. Apps submitted to the App Hub are reviewed by the DHIS2 core team. Apps approved by the DHIS2 core team will be available publicly on the App Hub.

The following guidelines are intended to make the App Hub submission and approval process simple and transparent. Following these guidelines will ensure your app works well on the DHIS2 platform and is well documented on the App Hub.

App Hub Documentation​

Providing good information about your app on the App Hub will help users find your app, quickly understand what it does and know if it is right for their instance.

App name​

An app should have a clear, descriptive name. Try to capture the core functionality of the app in a few words.

In addition, observing the following guidelines will help create a helpful app name:

  • Avoid generic, ambiguous words. Be as specific as possible.
  • Don't include redundant words like "app", "web", "interactive" or "DHIS2". All apps are available on the web, are interactive, and run on DHIS2, so you don't need to include this in the app name.
  • Avoid adjectives in general, especially words like "new", "modern" or "best".
  • Avoid names that are very similar to other core DHIS2 apps or apps on the App Hub.

App Icon​

All apps submitted to the App Hub should have a unique app icon. App icons are shown in the apps menu and help users to quickly navigate around DHIS2.

See how App Icons can be included in your application using the App Platform

Keep the following guidelines in mind when creating an app icon:

  • Try to capture a core idea about your app in an icon. What does your app do? - Try to hint towards that answer with your app icon.
  • Use clear, bold shapes.
  • Avoid photographs or complex shapes.
  • Use contrasting colors to make your icon clear at all sizes.
  • Icons should be uploaded in high-resolution, at least 512×512px in size.
  • Make sure all images and icons are correctly licensed. Do not take images or icons from a web image search without obtaining a license.
  • Do not use the DHIS2 logo in your app icon. The DHIS2 logo is a protected asset and we ask you not to modify it.

Description​

A good app description helps users of the App Hub quickly understand what the purpose of an app is and any requirements to using it.

An app description should clearly and concisely answer the following questions:

  • What does this app allow a user to do? Explain the core functionality.
  • Who is this app useful for? Define the target audience if one exists.
  • How does this app provide that functionality? Quickly summarize the main interaction.
  • Will this app only work on some DHIS2 instances? Be clear about any requirements for the app to function, such as how metadata is structured. Remember, DHIS2 apps in the App Hub should be generic.
  • What technical requirements does this app have? Make it easy for users to know if they can use this app. Be clear and upfront about any performance or network requirements.
  • All connections to external services must be clearly declared.

A short, clear app description for a core DHIS2 app, Data Visualizer, might look like this:

Create charts, tables and other visualizations from aggregate data. Data Visualizer is useful for any DHIS2 instance that wants to see their aggregate data visually. Visualizations can be included in Dashboards. Making visualizations is as easy as choosing data and dimensions, organizing them in the layout and choosing a visualization type. Data visualizer works on all DHIS2 versions that collect aggregate data. A network connection is needed to download data and save visualizations.

Screenshots​

Screenshots provide a quick overview of an app's interface and any generated items.

To provide helpful screenshots, follow these guidelines:

  • 3–5 screenshots is usually enough for most apps, every screen of the app doesn't need to be shown.
  • Use a common screen size to show in-app screenshots, 1280×800px is a good, easy-to-view size.
  • Screenshots should show the app in-use with data. Empty screens are rarely interesting or helpful.
  • Show the common or main use-case of the app in at least one screenshot.
  • Include an example screenshot of anything that the app generates, like reports or documents.

Source code​

When uploading your app, you will be required to provide your source code with a link to a public repository on a source control platform like Github. Sharing the source code of your app helps the DHIS2 core team carry out a quick review process and lets technical users evaluate if the app is right for their instance.

App guidelines 📝​

These guidelines are for the app itself, rather than how it appears on the App Hub. Apps that meet these criteria will be generic, useful, open-source, well-designed, documented, secure, performant and appropriate for the DHIS2 platform.

Generic​

Apps available in the App Hub should, by default, run on any DHIS2 instance. Apps that are flexible and generic are useful for a large audience and can help many DHIS2 users around the world.

Apps should not depend on the instance they were developed on. In practice, this means:

  • No hard-coded metadata IDs, such as organisation units, programs or data elements.
  • No hard-coded organisation unit level names, branding or contact details from a specific implementation.
  • No hard-coded DHIS2 API base URL. Resolve it through @dhis2/app-runtime's config.baseUrl or by using the injected value in HTML (document.querySelector('meta[name="dhis2-base-url"]')?.getAttribute('content')) on v41+.
  • App configuration (such as metadata linking) is read from the instance at runtime or set by the user, for example through a settings page within the app or in the DataStore.

Some apps are built for a specific metadata configuration, such as a particular tracker program or metadata package. This is acceptable, but the required metadata must be documented in the app description and in the README, so that users know what needs to be in place before installing the app.

Supported versions​

The DHIS2 versions an app supports are declared with minDHIS2Version and maxDHIS2Version in d2.config.js. Apps not built with the App Platform declare the same information in manifest.webapp. These values tell users which instances the app can be installed on, and they should reflect what has actually been tested.

When an app declares a version as supported, it is expected to have been tested on that version before submission. If minDHIS2Version is set to 2.40, the app should be tested on 2.40 and on each later DHIS2 release up to the declared maximum. Do not declare support for versions the app has not been tested on. The minimum version should be a released DHIS2 version, not a development or -SNAPSHOT build.

Reproducible build​

An app should build from a fresh clone, without depending on the author's environment.

  • Do not rely on local paths, machine-specific scripts or resources that only exist in the author's environment.
  • Use released versions of the build toolchain and dependencies, not alpha, prerelease or -SNAPSHOT builds.
  • Commit a single lockfile that is in sync with package.json.
  • For App Platform apps, let the platform generate manifest.webapp rather than committing a hand-written one.

Useful​

Apps must be meaningful and useful. To best benefit DHIS2 users and maintain an easy-to-use App Hub, apps should solve specific problems and use-cases that are not already covered by other applications.

Forking existing DHIS2 applications without providing new, different functionality and features is not recommended and may result in rejection. Apps which are forks or replicas of existing DHIS2 App Hub applications must include justification for and documentation of the changes which were made to the original app.

Open-source​

Make sure all components, libraries and resources that are running on the DHIS2 instance are open-source. Connections to third-party services do not need to be open source, but must be clearly declared in the app description.

To meet this requirement, the repository should include an open-source license file. Make sure dependencies like charting and visualization libraries are also compatible with this license.

Well-designed​

The DHIS2 Design System provides principles, guidelines and components for designing and building user-friendly apps. Follow the principles and use the available components where possible. Apps should be user-friendly and respect a users' time and resources. The Design System components are available as a set of pre-built React components via @dhis2/ui.

Apps built using the DHIS2 App Platform will automatically include the necessary Header Bar component and functionality. Apps not using the App Platform need to manually include and set up the standalone Header Bar component from @dhis2/ui. All DHIS2 apps must include the Header Bar component.

From DHIS2 2.42, apps run inside the global shell, which provides its own header bar. App Platform apps hide their header bar automatically when running inside the global shell. Apps not using the App Platform must handle this themselves. If such an app supports versions both before and after 2.42, it must show its own header bar on earlier versions and hide it inside the global shell. Examples on how to hide the header bar can be found here.

If the app supports translations, all user-facing text should go through internationalization (i18n). See Translation support for guidance.

Use of AI agents​

If you use a coding agent, we recommend the DHIS2 app development skill from dhis2/ai-devtools, which guides the agent to follow App Platform conventions. See the AI-assisted App Development guide for how to get started. The skill does not replace testing the app on the supported DHIS2 versions.

Documented​

Providing thorough documentation is essential for all apps. Documentation can be hosted on your website or a source control platform like Github. Think of documentation like an instruction manual for your app. Most users installing your app from the App Hub will not know how the app works. Documentation helps bridge this gap, introducing the main app interactions and providing guidance for common use cases.

warning

AI tools tend to produce verbose documentation and to fill it with content that is not relevant to users. AI-generated documentation must therefore be reviewed and approved by a human before submission, and it is held to the same standard as any other documentation described in these guidelines.

We have no objection to apps developed with the help of AI tools, but we ask that this is stated openly. If AI tools were used in the development of the app, state this in the README together with the extent of the use, for example whether AI assisted with parts of the code, generated most of the code, or wrote the documentation.

The documentation should be written for someone who did not build the app. A non-author should be able to install and set up the app using only the provided documentation. At a minimum, it should describe:

  • What the app does and who it is for.
  • How to use the main features of the app.
  • How to install and run the app.
  • What must be in place on the DHIS2 side, such as required metadata, user authorities, routes or system settings.
  • How to configure the app itself, and who should have access to it.
  • Any external services the app depends on, and how to set them up.

Keep the user documentation concise. Development history, such as development logs, implementation notes and plans, is not relevant to someone using the app and should not be part of the user documentation, including the README. Such information can be placed in separate developer documentation, for example a docs/ folder or a DEVELOPMENT.md file.

Secure​

All apps should follow modern, up-to-date security best practices.

Consider implementing the following guidelines to address harden application security:

  • Never hard-code security parameters in application source-code: It is never acceptable to hard-code credentials or encryption keys into application source-code, even if an environment variable is used to inject the key in the application .zip file at build-time. Everything in the .zip application archive is publicly-accessible to anyone with a browser and should never include any sensitive information. Encryption keys should never be shared between app installations in different DHIS2 instances.

    • Use .gitignore and environment variables to ensure that development environment credentials are not accidentally committed with the source-code.

  • DataStore and UserDataStore: It is more secure to put configuration in the UserDataStore in DHIS2, rather than in the DataStore which is shared with all users. When using either the UserDataStore or DataStore, be sure to:

    • Choose a unique and specific namespace which will not conflict with other applications
    • Reserve the namespace used by your application by specifying it in the manifest.webapp file, so that only users with access to that application can access it (see an example of a manifest file here). Functionality to reserve namespaces is coming soon to the Application Platform tools.
    • Do not store external service credentials in the DataStore or UserDataStore for use by browser-side code. Credentials for third-party services should never be available to the client.
    • If sensitive information must be stored in the datastore for server-side use, set the ?encrypt=true query string parameter in order to ensure that the value is encrypted at rest.
    • Whenever possible, use the DataStore sharing API to explicitly grant read and write permissions to the users which need them and prevent access by any unprivileged users. It is particularly important to lock down write access as much as possible.

  • External service communication: Integrations with external systems (for example, other DHIS2 instances) should use DHIS2 routes for backend-to-backend communication:

    • When handling sensitive information such as credentials, use routes instead of DataStore or UserDataStore values exposed to the client.
    • Route configuration can be managed with the Route Manager App, which supports managing routes using the DHIS2 Routes API.
    • Do not call external services directly from the browser when authentication credentials are required.
    • Do not fetch or expose third-party credentials in client-side application code.
    • Avoid CORS-based patterns that require exposing external service endpoints broadly to browsers.

  • Authentication: Using basic authentication to communicate with DHIS2 from a DHIS2 application which already uses cookie session authentication is not recommended. Consider implementing the following:

    • Leverage the existing user session (using a cookie in the browser) instead of basic authentication
    • If possible, perform all synchronization processes on the server-side instead of in the browser. This is more secure and more performant but puts some onus on the server administrator to maintain an additional server-side service.

  • XSS: If your framework of choice can be configured to provide XSS protection, ensure that it is enabled. For example, React protects against XSS injection by default as long as dangerouslySetInnerHTML is not used.

  • Set rel="noreferrer" attribute on external links with target="_blank": When linking to external resources that should open in a new tab (using target="_blank") ensure that the rel="noreferrer" attribute is set. This will prevent the external resource from being able to manipulate your page using window.opener. See this short article for more information.

  • Avoid externally hosted scripts and stylesheets: External scripts and stylesheets, such as those served by global CDNs, should be avoided unless absolutely necessary - these can cause security and performance issues when accessed in various global contexts.

  • Dependencies: Dependencies are part of the app's security surface. All lockfile entries should resolve from the official package registry, not from git, http or tarball URLs. Install and lifecycle scripts (preinstall, postinstall, prepare) should only be present when needed. Remove unused dependencies, and avoid packages with known, unpatched security advisories.

  • Browser storage: Never store credentials or tokens in localStorage, sessionStorage or IndexedDB. For DHIS2 access, rely on the user's existing session instead.

Performant​

Apps should run smoothly on widely available hardware and with a reasonable internet connection. Consider the following guidelines to make sure your app is available to a wide range of users:

  • Consider a range of desktop screen sizes. Approximately 75% of worldwide desktop and laptop users have a screen width below 1600px, so make sure your app doesn't need a wide screen.
  • Some users will have limited-resource hardware. If necessary, test your app with virtual limiting tools to check performance and usability on devices with limited memory and processing power.
  • Don't assume a stable or fast internet connection. If necessary, test your app with network throttling tools to see how a slow or intermittent connection affects the user experience. As much as possible, try to anticipate and allow for a wide range of network types and performances.

Appropriate for DHIS2​

Including any of the following will result in immediate App Hub rejection or removal:

  • In-app advertisement.
  • Cryptocurrency mining.
  • Background downloads not initiated by the user.
  • Repackaged DHIS2 core apps.
  • Forked existing DHIS2 apps without meaningful functionality or feature changes.

Submission Process​

Upon submitting to the App Hub, the DHIS2 core team will review your app. Note that the core team does not have the resources to carry out extensive testing and bug reporting, this is the responsibility of the app author(s). Keep in mind the following points when you're ready to submit your app:

  • The review process will be quicker if your app is well-documented and follows the guidelines above.
  • Providing example use-cases and any example data/metadata are always helpful. If your app is rejected, the core team will let you know why, so make sure your contact details are up to date. You can resubmit your app after addressing any issues.
  • If your app is approved, it'll soon be available publicly on the App Hub. You can manage your app through your App Hub account.