The file system is laid out as flat as possible. Component packages go
under components/, utility packages under utilities/, and
collections under collections/.
Be aware that the UI repository is a monorepo based on Yarn Workspaces, so the setup assumes a working knowledge about how workspaces behave, and use of Yarn.
Note: As of 2021-06-21, we rely on Yarn 1.x and support for Yarn 2.x is unverified.
See the workspaces key in the root package.json to see which
packages are considered part of the workspace.
There are three conceptual levels in UI which we will go over in turn.
UI has several utility packages that are helpful when building user
interfaces, for example @dhis2/ui-icons exposes icons ready to be used
as React components in an application or library. Using these ensures
that user interfaces look consistent, and that once a user has learned
an icon, that heuristic will be transferable across DHIS2 applications
both for core and custom apps.
Another example is the @dhis2/ui-constants package that exports
constants for e.g. DHIS2 colors, sizes, to allow for theme consistency.
If those constants are used, even if they are updated those updates will be reflected in applications that use the constants.
Using utilities from UI does not require use of UI components, so it can be useful even if another user interface framework (or custom components) are used.
UI Components are building blocks for constructing DHIS2 user interfaces that cover the most common use cases out-of-the-box, while allowing for customization to cover advanced, specialized, and uncommon use cases.
In React fashion we rely on composition to enable the goal of having "building blocks".
This means that:
-
complex components are constructed by connecting several simple components,
-
a consumer must have direct access to the building blocks that make up composed components,
-
components need to be isolated from each other with a well defined interface and scope,
-
components needs to be reusable across many contexts.
Note: Components are published under the
@dhis2-uiscope, and will eventually be considered part of the external API as things stabilize.As of 2021-06-21,
@dhis2-ui/*components are considered internal and may have breaking changes without us bumping the major version on@dhis2/ui-*components.
Each component package has a logical and semantic scope, that may group related components.
If needed, components can be extracted to distinct component packages to break e.g. circular dependencies or to provide a tighter scope.
If UI is fully decomposed, every single component would be its own package, and this would not be a problem. We may end up there in the future, but for now we are striking a pragmatic balance between packages and components.
To make extraction easier, each component package has a
{component}/src/index.js file that defines the exported components for that
package.
If a package contains multiple components, then each subcomponent should have a
index.js file that defines its module boundary. This makes it easier to
extract it in the future: {component}/src/{subcomponent}/index.js`.
Components should import from the index.js files and avoid reaching into
non-exported parts of a component.
In UI terms a collection is a set of components, and is considered the
primary entry-point for use in applications. An application will
primarily rely on @dhis2/ui and all internal components are available
through that collection.
Note:
@dhis2/ui-coreand@dhis2/ui-widgetsare deprecated and will be phased out. They will still get updates to existing components, but no new components will be available from these two packages, and they will be removed in a major update in the future.
UI uses two different scopes on NPM to publish:
-
@dhis2/ui*: Collections and utilities. -
@dhis2-ui/*: Component packages are published under this scope.