---
# System prepended metadata

title: Build convergence project
tags: [pitch, ' build']

---

---
robots: noindex, nofollow
tags: pitch, build
---
<!-- For instructions on shaping a project see here: [Shaping a Project](/kX02SXVbS6KzMOQd56i6Cg) -->

# Build convergence project

[TOC]

## Problem
<!-- *From: [Problem guidance](https://basecamp.com/shapeup/1.5-chapter-06#ingredient-1-problem)*
*The best problem definition consists of a single specific story that shows why the status quo doesn’t work.* -->
 
We have two different build systems in one repo: different tooling, options, file structure, and practices. (The differences stem from a combination of philisophical and historical reasons.) This is confusing to devs (especially when trying to add new projects) and harder to maintain.
 
## Appetite

(in 3 weeks)

## Solution

<!-- *The solution is what makes this Project "Shaped". Without a specific solution defined we leave too much ambiguity and risk for the Project team to figure out while coding. This is not, however, a detailed spec or list of task. It is good to leave details open for the team to decide on while building the solution* -->

- One clear way to create a new package (stop creating more technical debt!)
  - needs discussion early next week
    - make a list of what we need to discuss
  - update create-package (or use plop) to implement decisions
- All projects use just (not gulp) for task orchestration
  - ensure build perf doesn't regress
- Unblock upcoming projects
  - component doc gen (will also improve build perf)
- Start addressing technical debt (as time allows)
  - For existing packages, converge configuration options and practices
  - Make a github issue with the list of remaining things to address

## Risks (Rabbit holes)
<!-- *From: [Rabbit hole guidance](https://basecamp.com/shapeup/1.5-chapter-06#ingredient-4-rabbit-holes)*
*Another key aspect of shaping is de-risking. This involves identifying potential issues and complications in the solution. These may be non-obvious cases where the solution doesn't work. These could be constraints from other parts of the system (dependencies or dependent code). This aspect of shaping is what typically requires the most experience and understanding of the domain. This is likely something we will all collectively get better at with practice.* -->

- Bike shedding
- Potential for build perf regressions (and time spent to mitigate)
- Have to prevent TS issue with relative cross-package imports in .d.ts
  - https://github.com/ecraig12345/learn-a/tree/inferred-relative-imports
- TS project references
  - These have potential benefits like build-less intellisense (maybe even without path aliases) and improved build perf, but they're confusing how to set them up correctly and have historically been a huge time sink.
  - Not all tools support them (issues with both webpack and jest, at least 2 months ago)
  - We may not be configuring them properly to get the full build caching benefits (possible that path mapping breaks caching?)
  - To fully set this up properly for our specific scenario, we probably need to directly talk with someone from the TS team (due to lack of documentation and very confusing observed behavior to this point)
- Random unanticipated issues with seemingly simple tooling changes/upgrades
  - After 1 hour dealing with any issue like this, reconsider how essential it is or any alternatives 
  - Seriously reconsider again after 1 day

## Out of scope (No-gos)
<!-- *From: [No-gos guidance](https://basecamp.com/shapeup/1.5-chapter-06#ingredient-5-no-gos)*
*A key way to deal with complicated risks or issues with the solution, is to decide a particular funcionatliy is out of scope. If reducing the scope to remove a risk or issue does not prevent us from fulfilling the original problem, then it is fine. Reducing scope may require reaching out to the original customer that had the problem we are solving, or working with a representive of the customer on our team.* -->

These are out of scope **for this month** but should potentially be addressed later.

- Update all existing projects to fully use converged structure
  - We may do *some* higher-priority updates this month, but full convergence would take too long
- Any new work involving TS project references
- Optimization opportunities
  - Share TS program between build steps
  - Exclude test files from main TS/babel build and only transpile while running jest
- Converge doc metadata generation

## Detailed notes

### Decisions

Notes here: [Build convergence decisions](/Rcd6JbL9TNCqClyglBxQ1w)

- **Orchestration**: just (not gulp)
- **What must work before building**
  - Long-term we want to set up project references
  - Not feasible to do this month (requires help from TS team)
- **Output file structure**
  - Similar to 
Transpilation tooling and options
Tooling
Compiler options
Output target and helpers/polyfills
How to import our code
Test file structure
Linter and lint rules
Inner loop and example structure
API rollup/review
Component doc generation

### Technical debt

- [ ] All build scripts run with ts-node
  - [ ] Measure build performance before and after
    - Using transpileOnly option to speed up
  - [ ] Switch v0 scripts to use ts-node rather than babel-register. Notes:
    - Shift said in Dec he'd prefer this
    - babel-register doesn't have type checks
    - original switch https://github.com/microsoft/fluent-ui-react/pull/1395, https://github.com/microsoft/fluent-ui-react/issues/508
  - [ ] Convert v7 scripts to TS
- [ ] Finish moving examples to examples package
- [ ] Add create-package variant for node-based packages
- [ ] TS
  - [ ] v7 projects use config inheritance (and resolve minor discrepancies)
  - [ ] Remove path aliases
    - [ ] Legacy ones: src, test, docs
    - [ ] harder: `@fluentui/*`
      - [ ] !!! have to prevent cross-package relative paths in .d.ts
  - [ ] Remove `noImplicitAny` and `strictNullChecks` overrides from build scripts tsconfig?
  - [ ] Enable `noImplicitAny`
  - [ ] Enable `strict` (lower priority, probably incremental)
    - [ ] noImplicitAny
    - [ ] noImplicitThis
    - [ ] alwaysStrict
    - [ ] strictBindCallApply
    - [ ] strictNullChecks
    - [ ] strictFunctionTypes
    - [ ] strictPropertyInitialization
- [ ] Testing
  - [ ] Remove component info dep in conformance tests
  - [ ] Move all tests to structure we decide on (potentially feasible for this month)
  - [ ] (later) Exclude tet files from main TS/babel compilation?
  - [ ] Converge screener?
    - [ ] how tests are run
    - [ ] where tests live (get v0 tests out of docs!!)
    - [ ] configs
- [ ] webpack
  - [ ] configs move to individual packages
  - [ ] ensure we've fully split bundle from build in all packages
- [ ] all packages declare all their deps
- [ ] For existing packages, converge configuration options and practices
- [ ] Add back caching or single-file rebuilds for component info?

### Additional notes

- Existing unfinished work
  - [project references + main: src/index](https://github.com/microsoft/fluent-ui-react/pull/2253)
    - this got stuck on the relative path in .d.ts bug and other issues
    - https://github.com/ecraig12345/learn-a/tree/inferred-relative-imports
  - [Remove path aliases from tests](https://github.com/microsoft/fluent-ui-react/pull/2243)
  - [Remove path aliases: the fun parts](https://github.com/microsoft/fluent-ui-react/pull/2245)
- Babel config
  - plugins:
    - babel-plugin-lodash to cherry-pick lodash imports
    - babel-plugin-remove-prop-types to remove prop types
    - future:
      - annotating code for better tree shaking?
      - optimize stylesheets?
  - unfinished PR switching dist build to babel: https://github.com/microsoft/fluent-ui-react/pull/1169
