How instructure/instructure-ui works
Project Type and Purpose
• This is an open-source, React-based UI framework & design system (“Instructure UI”) delivered as a monorepo.
• It houses hundreds of small, focused packages (components, utilities, themes, testing tools, scripts) managed via Lerna and published to NPM.
• It also contains documentation, examples, and end-to-end/regression test runners (Cypress, Karma, Vitest).
High-Level Architecture
• Monorepo Root
– Configuration: ESLint, Prettier, TypeScript (tsconfig.*.json), Babel, Husky (git hooks), commitlint.
– Orchestration: Lerna (lerna.json), custom build/test/deploy scripts (in /scripts and /.github/workflows).
• Package Groups (under /packages)
– UI Components (e.g., ui-buttons, ui-dialog, ui-menu, …)
– Theming & Styles (canvas-theme, canvas-high-contrast-theme, ui-themes, shared-types)
– Utilities (ui-utils, ui-dom-utils, ui-test-utils, ui-scripts, pkg-utils, command-utils, debounce, uid, etc.)
– Plugins/Config (babel-plugin-transform-imports, ui-babel-preset, ui-webpack-config, ui-karma-config)
– Docs & Examples ( __docs__, __examples__, docs/, packages/__docs__, packages/__examples__ )
– Regression & E2E tests ( regen-test, cypress, Karma config, Vitest config )
• CI/CD Pipelines
– GitHub Actions: lint, type-check, unit/regression tests, visual regression, versioning, publish to NPM, deploy docs.
– Manual workflows for releasing (to NPM or site previews).
• External Services
– npm registry (package publish)
– Website host (instructure.design docs site)
– GitHub (source, Issues, PRs, CodeQL)
Relationships & Data Flows
• Developer → GitHub Push/PR
– Husky → lint-staged → Pre-commit tests
– commitlint on commit messages
• GitHub Actions triggered on push/PR
– Steps: install dependencies → type-check → unit tests (Vitest/Karma) → Cypress E2E → visual regression → build packages → version bump (calculateVersion.sh) → publish
• Build Outputs
– Component bundles → NPM packages
– Documentation site static assets → Deployed website
• Consumers
– App developers import published packages from NPM
– Documentation site visitors view examples & API docs
– CI regression-test runner ensures backwards-compatibility
Architectural Patterns & Principles
• Monorepo modularization: each package is a small, single-responsibility module.
• “Build once, publish many”: shared build/config leveraged across packages (babel, TS, webpack).
• CI-driven quality gates: type safety, lint, unit/E2E, visual regression before merge/publish.
• Docs-as-code: examples and docs are first-class packages under the monorepo, built with custom scripts.
• Publish-on-tag: manual and automated release flows separate CI and publication.