Skip to main content

Creating a DHIS2 Web app

It's time to create a new Web app! Below we'll show you how to quickly bootstrap an app and how to connect it to a DHIS2 instance.

Creating a new Web app​

  1. From the terminal, create a new DHIS2 app called "my-app"
# with pnpm
pnpm create @dhis2/app my-app --yes

We recommend the use of pnpm as a package manager, but you can also use npm if you prefer:

# with npm
npx @dhis2/create-app my-app --yes

The --yes will create a new DHIS2 web application using the default options (pnpm as a package manager, and TypeScript for the language).

If you remove the --yes flag, then you will have the chance to go through the wizard and customize the project, to choose JavaScript instead of TypeScript, or the legacy yarn 1 package manager.

  1. Change directories to ./my-app and start the app
cd my-app && pnpm start

Replace pnpm start with npm start or yarn start if you chose a different package manager.

note

Most places in the rest of the DHIS2 documentation assume yarn classic as the package manager. This was historically the default, but we are deprecating it in favour of more modern package managers. You can still choose yarn classic when initialising new applications, but we recommend using pnpm or npm unless you have a very good reason not to.

Connecting your Web app to DHIS2​

  1. From the browser, navigate to your DHIS2 Web App, which by default runs under port 3000 http://localhost:3000. You will see the following page:

  1. Enter your DHIS2 server URL and the username and password of the default admin user (local DHIS2 instance assumed in the example below)
server: http://localhost:8080
username: admin
password: district
note

If you're running into some Cross-Origin Resource Sharing (CORS) policy issues when trying to connect to your application, please check the guide on how to debug common development errors.

note

You can also run your web app by creating a proxy to one of the environments on play.dhis2.org.

To do so, run:

pnpm start --proxy https://play.im.dhis2.org/dev-2-42

This will create a proxy from http://localhost:8080 to the play instance, and you can enter http://localhost:8080 as the server url, and login using the play credentials.

  1. You will see the default admin user name and a welcome message

Congratulations! You are ready to start developing a DHIS2 app 🎊

Next steps​

Now that you have created a DHIS2 app and connected it to a DHIS2 instance you can learn more about developing apps on DHIS2.