Context and Problem Statement¶

As our codebase grows in complexity, it becomes increasingly important to understand and manage dependencies between modules. We need a tool that can help us visualize, analyze, and enforce dependency rules to maintain a clean architecture and prevent issues like circular dependencies.

Which dependency visualization and analysis tool should we use for our JavaScript/TypeScript application?

Decision Drivers¶

• Support for JavaScript and TypeScript
• Ability to visualize dependencies in various formats
• Rule enforcement capabilities
• Integration with our build process
• Developer experience and ease of use
• Community support and documentation
• Customizability

Considered Options¶

• Dependency-cruiser
• Madge

Decision Outcome¶

Chosen option: Dependency-cruiser

We have decided to use Dependency-cruiser for the Newgotiate UI application due to its comprehensive feature set, rule enforcement capabilities, and excellent visualization options.

Reasoning¶

1. Rule Enforcement: Dependency-cruiser allows us to define and enforce custom dependency rules, which is crucial for maintaining architectural boundaries.

2. Visualization Options: It provides multiple output formats (DOT, SVG, HTML, etc.) for dependency visualization, making it versatile for different use cases.

3. TypeScript Support: Dependency-cruiser has excellent support for TypeScript, which is our primary language.

4. Integration: It can be easily integrated into our CI/CD pipeline and build process.

5. Developer Experience: The tool has a clear API and documentation, making it accessible for all team members.

Implementation Notes¶

• Configuration will be stored in .dependency-cruiser.js at the project root
• We'll integrate dependency validation into our CI pipeline
• We'll generate dependency graphs as part of our documentation process
• Custom rules will be developed to enforce our architectural boundaries

Consequences¶

• Team members need to understand the dependency rules and how to interpret validation errors
• We need to ensure proper setup in both development and CI environments
• We should document common patterns for dependency management

Pros and Cons of the Options¶

Dependency-cruiser¶

• Good, because it provides comprehensive rule enforcement capabilities
• Good, because it supports multiple output formats for visualization
• Good, because it has excellent TypeScript support
• Good, because it integrates well with CI/CD pipelines
• Good, because it has active community support and documentation
• Good, because it allows for custom rules tailored to our architecture
• Bad, because it requires additional configuration for complex rule sets
• Bad, because the learning curve can be steeper for new team members

Madge¶

• Good, because it's simple and easy to use
• Good, because it supports JavaScript (AMD, CommonJS, ES6) and CSS preprocessors
• Good, because it can identify circular dependencies
• Good, because it has a straightforward API
• Bad, because it has limited rule enforcement capabilities
• Bad, because it has fewer visualization options
• Bad, because it has less active development compared to alternatives

Links¶

• Dependency-cruiser Documentation
• Madge Documentation