Cross-Package Dependencies

Cross-package dependencies occur when design system packages depend on other packages within the same monorepo. Managing these dependencies requires careful version specification, update coordination, and consumer guidance. Proper handling ensures packages work together correctly.

What Are Cross-Package Dependencies

Cross-package dependencies are references between packages in a monorepo. A components package might depend on a tokens package. A React wrapper might depend on a framework-agnostic core. These internal dependencies create relationships that must be maintained across versions.

Managing cross-package dependencies differs from external dependencies because both sides are controlled by the design system team. This control enables coordination but also requires it. Mismatched internal dependencies can break consumer installations.

How Cross-Package Dependencies Work

Cross-package dependency management involves specifying versions correctly, coordinating updates, and ensuring consumers receive compatible packages.

Version specification defines how packages reference each other. Regular dependencies include the package in node_modules. Peer dependencies expect consumers to provide the package. Dev dependencies are used only during development. The choice affects how consumers experience the relationship.

Range selection determines which versions satisfy dependencies. Caret ranges (^1.0.0) allow minor and patch updates. Tilde ranges (~1.0.0) allow only patch updates. Exact versions lock to specific releases. Range choice affects how package updates propagate.

Update coordination ensures dependencies remain valid as packages evolve. When the depended-on package releases new versions, the depending package’s dependency specification may need updating. Automated tools can help manage this coordination.

Consumer installation resolves dependencies in consumer projects. npm or yarn hoists packages and resolves version ranges. Cross-package dependencies must resolve to compatible versions in consumer environments, not just the monorepo.

Key Considerations

• Use peer dependencies for packages consumers likely install directly
• Coordinate version ranges across packages
• Test in consumer-like environments, not just the monorepo
• Consider dependency hoisting effects
• Document cross-package compatibility

Common Questions

When should cross-package dependencies use peer dependencies?

Peer dependencies are appropriate when consumers will install both packages and expect to control the version. Understanding when to use peer versus regular dependencies prevents consumer confusion.

Peer dependencies suit packages consumers interact with directly. If consumers import from both @design-system/components and @design-system/tokens, making tokens a peer dependency of components lets consumers control their tokens version.

Regular dependencies suit internal implementation details. If a package uses another package only internally (consumers do not interact with it), a regular dependency that installs automatically is appropriate.

Multiple versions can cause issues with peer dependencies. If the consumer’s tokens version differs from what components expects, subtle bugs may occur. Clear peer dependency ranges and consumer guidance help prevent issues.

Peer dependency warnings alert consumers to version mismatches. npm and yarn warn when peer dependencies are not satisfied. These warnings help catch compatibility issues before they cause problems.

How do cross-package dependencies affect release coordination?

Cross-package dependencies create release coordination requirements. Changes to depended-on packages can require updates to depending packages.

Compatible changes may not require coordination. If the tokens package releases a patch fix within its existing API, components’ existing dependency range likely still works. No coordination is needed.

Expanding APIs typically works within ranges. Minor versions adding new features maintain backward compatibility. Components’ existing dependency range should accommodate new tokens minor versions.

Breaking changes require coordination. If tokens releases a breaking change (major version), components must update its dependency specification to include the new major version. This often means releasing components alongside tokens.

Range updates should accompany or follow dependency releases. When tokens goes from 2.x to 3.0, components should update its peer dependency range to include ^3.0.0, possibly supporting both 2.x and 3.x during transition.

Summary

Cross-package dependencies connect packages within design system monorepos. Managing these dependencies requires appropriate version specification, update coordination, and consumer-like testing. Peer dependencies let consumers control shared packages while regular dependencies handle internal implementation details.