Dependency Types

Overview

This document describes how to use dependency tags in the package.json file of ADITO modules. The following dependency types are supported:

Type	Description
devDependencies	Required only during development (e.g., testing, build tools).
dependencies	Required at runtime. Installed automatically via npm install.
peerDependencies	Required at runtime and exposed to consuming modules. Must be installed manually via upstream dependencies.

---

devDependencies

Use devDependencies for tools and libraries needed only during development, such as:

• linters
• testing frameworks
• build scripts

These are not included in production builds.

---

dependencies

Use dependencies only in the following cases:

• In modules of type project
• In parent modules that aggregate other modules

Behavior

When npm install is run, dependencies are installed automatically. This includes transitive dependencies of nested modules.

Example:

If the project module basic-project has a dependency on contactmanagement, and contactmanagement depends on activity, all are installed recursively.

warning

If multiple modules require different versions of the same dependency, this can lead to duplicate installations. Such conflicts must be resolved manually.

---

peerDependencies

Use peerDependencies in all other modules to declare external modules that are required at runtime.

Characteristics

• Defines expected modules and their compatible version ranges.
• Makes dependencies visible and accessible to superordinated modules.
• Enables shared use of data models and APIs across modules.

Example:

If module activity has a peerDependency on contact, then activity can access all entities and services from contact.

API Integration via peerDependencies

Declaring a module as a peerDependency means that it becomes part of your module’s functional interface. Consumers of your module are expected to provide this dependency themselves, and they may also access and use its types and logic directly.

Example:

If activity declares a peerDependency on contact, then:

• activity can access all exported models, types, and services from contact
• other modules using activity can also access functionality from contact via activity, assuming a compatible version of contact is installed

This forms a transitive API relationship: contact effectively becomes part of the public interface of activity.

tip

This makes peerDependencies a deliberate part of module design and versioning responsibility.

Versioning Guidelines

Always use version ranges that exclude the next major version (e.g., ^1.0.0, not 1.0.0). This allows for hotfixes and minor updates without requiring a major version bump.

note

See Versioning Concept for detailed SemVer guidance.

---

Installation Behavior

• When npm install is run on a project module, only dependencies (and their nested dependencies) are installed.
• peerDependencies are not installed automatically. They must be resolved via other modules' dependencies.

Example

1. basic-project has a dependency on contactmanagement
2. contactmanagement has a dependency on activity
3. activity has a peerDependency on utility
4. platform (a parent module of basic-project) has a dependency on utility

Result: Although activity does not directly depend on utility, it declares a peerDependency on it. Because utility is included in the dependency graph of basic-project through platform, it is installed at the top level and made available to all modules that declare a compatible peerDependency. Thus, activity can access and use utility at runtime without explicitly listing it under dependencies.

npm does not install peerDependencies automatically. This behavior ensures that shared dependencies are not duplicated and are instead provided by the consuming project or an aggregating parent module.

If a required peerDependency is not declared somewhere in the top-level dependency tree—typically in a project or parent module—then:

• the affected module may throw errors during transpilation or at runtime,
• the module might appear installed, but its required peer will be missing in node_modules,
• and the application will be incomplete or non-functional.

warning

Always ensure that peerDependencies are fulfilled by a compatible dependency declared in a parent or project module. This is required to produce a valid and executable build.

---

Best Practices

• Always declare runtime-visible modules as peerDependencies, unless you are writing a project or parent module.
• Avoid using dependencies in feature or logic modules to prevent runtime duplication.
• Never declare peerDependencies in project or parent modules.

tip

Use peerDependencies when your module exposes or relies on types from other modules. Use dependencies only when the usage is internal and encapsulated.

---

Viewing the Dependency Tree in ADITO Designer

See Viewing the Dependency Tree in ADITO Designer for informations on how to visualize the dependency tree of your ADITO modules in the Designer.

---

Summary

Module Type	Use dependencies	Use peerDependencies
Project	✅	❌
Parent Module	✅	❌
Feature Module	❌	✅
Utility Module	❌	✅