Skip to the content

Vendor Isolation

@apollion-dsi/core uses third-party libraries for positioning, forms, tables, virtualization, dates and color math. Components never import those libraries directly: each one sits behind a wrapper in packages/core/src/vendors/<Lib>/ whose interface the design system controls.
Contributing

The rule

  • Inside packages/core/src/, import a third-party library only from its wrapper.
  • Only files under src/vendors/** may import the upstream package.
  • Consumers import only public subpaths such as @apollion-dsi/core/form/input, never a vendor.

The shared ESLint config enforces the first two points as errors, so a direct import fails lint.

How it works

A wrapper exports only the surface the design system uses, so the bundler drops the rest and an upstream swap stays local to one folder. Each wrapper has a README.md that records what it exposes, what it leaves out and when to re-evaluate the library.

Culori · DateFns · Deepmerge · EmotionIsPropValid · FastDeepEqual · FloatingUI
LodashDebounce · Nanoid · ObjectHash · ReactContentLoader · ReactDayPicker
ReactHookForm · ReactSelect · StyledComponents · StyledNormalize
TanstackReactTable · TanstackReactVirtual · Zod

Culori is the terminal case: the wrapper now contains the design system's own color engine, and the upstream library survives only as the oracle of the parity tests. No consumer changed a line.

react and react-dom are peer dependencies, not wrapped. styled-components is wrapped even though it is a regular dependency: the facade isolates the global DefaultTheme type.

Add a dependency

  1. Create src/vendors/<NewLib>/ with index.ts and README.md.
  2. Export only the surface the design system needs.
  3. Import from the wrapper inside components.

Pitfalls

  • import { DayPicker } from 'react-day-picker' in a component → import { DayPicker } from '../../vendors/ReactDayPicker'.
  • Re-exporting the whole upstream module from a wrapper → export the names in use, nothing more.

See also