Implement incremental TypeScript compilation and caching for monorepo builds

[Lakes41]

Background

With a 9-package monorepo spanning Docusaurus docs, Next.js apps, TypeScript libraries, and Discord/API services, full workspace rebuilds are slow and I/O-intensive. Currently, pnpm -r build compiles all packages sequentially regardless of what changed, taking 30+ seconds even when only one file is modified.

Problem

1. No incremental compilation: Each pnpm build runs tsc fresh, recompiling all TypeScript files
2. No build cache: TypeScript doesn't persist compilation state between runs
3. No dependency awareness: Packages rebuild even if their dependencies didn't change
4. Slow iteration: Developers wait for full builds during development cycles

This becomes critical in a Stellar/Soroban migration where frequent iterative changes are expected.

Expected Outcome

• TypeScript incremental mode enabled across all packages
• Build times reduced for incremental changes (3-5s vs. 30+s)
• Clear build cache strategy documented
• Developer experience improved for fast iteration

Suggested Implementation

1. Enable incremental compilation in tsconfig.base.json:

   {
     "compilerOptions": {
       "incremental": true,
       "tsBuildInfoFile": "./dist/.tsbuildinfo",
       "composite": false
     }
   }

2. (Optional) Use TypeScript project references for monorepo builds:

   • Create a root tsconfig.json with references to each package's tsconfig.json
   • Use tsc -b (build mode) instead of tsc to leverage project references
   • Enables true incremental, dependency-aware builds

3. Add .tsbuildinfo to .gitignore (build artifact)

4. Update build scripts:

   "build": "tsc -b",
   "build:clean": "rm -rf dist .tsbuildinfo && tsc"

5. Benchmark:

   time pnpm -r build  # First run: full compile
   echo '// change' >> packages/contracts/src/index.ts
   time pnpm -r build  # Second run: incremental

6. Document in monorepo README.md:

   ## Build Caching
   - Incremental builds are enabled by default
   - First build is slower; subsequent builds reuse cached data
   - Clean builds: `pnpm build:clean`

Acceptance Criteria

• Incremental compilation is enabled in tsconfig.base.json (or each package's tsconfig)
• First full build succeeds; .tsbuildinfo files are created in each package's dist/
• Incremental builds (after minor changes) complete in <10 seconds
• .tsbuildinfo is ignored by Git
• Build documentation updated with caching strategy
• Team verifies faster iteration cycle during development

Affected Files/Directories

• tsconfig.base.json or each packages/*/tsconfig.json
• .gitignore (add .tsbuildinfo)
• README.md (document build caching)

[Emelie-Dev]

Hi, I would love to work on this issue.

[Phantomcall]

I’d like to take this on. I’m comfortable working with TypeScript monorepos, pnpm workspaces, tsconfig configuration, build tooling, and incremental compilation, and I understand that the goal here is not simply to change one compiler flag but to make sure the resulting cache actually improves the developer iteration cycle without introducing stale or inconsistent build artifacts.

I’ll first inspect the monorepo structure and the existing build scripts across the nine packages to understand how the Docusaurus documentation, Next.js applications, TypeScript libraries, and Discord/API services currently compile. I’ll specifically check whether the packages inherit from tsconfig.base.json, whether any packages override compiler options, and whether their current build commands use plain tsc, framework-specific builds, or other tooling.

I’ll then enable TypeScript incremental compilation in the appropriate shared configuration, using a package-local .tsbuildinfo location such as dist/.tsbuildinfo so the cache remains a build artifact rather than repository state. I’ll make sure package-specific configurations do not accidentally override the shared incremental settings.

Where the monorepo structure supports it cleanly, I’ll also evaluate whether TypeScript project references and tsc -b are appropriate. I won’t introduce project references simply for the sake of complexity: the existing package dependency graph and build behavior need to support them without breaking Next.js, Docusaurus, or library builds.

The implementation will cover:

• Enabling incremental: true in the shared TypeScript configuration or relevant package configurations.
• Configuring predictable .tsbuildinfo locations under each package's build output.
• Ensuring build artifacts and .tsbuildinfo files are excluded from Git.
• Reviewing package build scripts for compatibility with incremental compilation.
• Adding a clean-build command that can remove cached compiler state when a completely fresh build is required.
• Preserving existing package outputs and build behavior.
• Updating the root README with a clear explanation of incremental caching and when developers should use a clean build.

I’ll pay particular attention to the interaction between pnpm -r build and the package dependency graph. Incremental TypeScript compilation can reduce work inside an individual package, but simply enabling incremental does not automatically make pnpm's recursive build dependency-aware. If the repository's existing workspace setup can benefit from project references, I’ll assess that separately and only introduce it where it provides a measurable improvement without destabilizing the build.

For testing, I’ll establish a baseline before making the change by running the current workspace build and recording the relevant timing. After implementation I'll verify:

1. A clean/full workspace build succeeds.
2. .tsbuildinfo files are generated in the intended package output directories.
3. A small source change causes only the necessary TypeScript work to be performed.
4. A subsequent incremental pnpm -r build completes successfully and meets the <10s target under the repository's normal environment.
5. .tsbuildinfo is ignored by Git.
6. A clean build removes cached state and still produces a correct build from scratch.
7. Framework-specific packages such as Next.js and Docusaurus continue to build correctly.
8. Package dependency changes correctly invalidate the relevant incremental compilation state.

I'll also check for stale-cache edge cases. In particular, the implementation should make it straightforward for developers to recover from compiler configuration changes or unusual dependency-state changes using the documented clean-build command rather than leaving them with confusing stale artifacts.

For the documentation, I'll add a concise Build Caching section explaining that the first build establishes the cache, subsequent builds reuse TypeScript's persisted compilation state, .tsbuildinfo is intentionally untracked, and developers can use the clean-build command when they need to invalidate the cache.

I’ll keep the changes focused on build performance and avoid unrelated refactors. Before submitting, I’ll run the workspace build, relevant package-level checks, and lint/type checks where available, and include the before/after benchmark results so the PR demonstrates an actual improvement rather than only claiming incremental compilation is enabled.

The end result should be a predictable incremental build workflow where small TypeScript changes no longer require recompiling the entire nine-package workspace from scratch, while still retaining a reliable clean-build path when a full rebuild is necessary.

[grantfox-oss]

🦊 GrantFox — @Emelie-Dev has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #337)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@Emelie-Dev's PR #347 was approved and merged by @Lakes41.

🏆 @Emelie-Dev: You earned 40 FoxPoints for this contribution! Your current tier: Builder (1,049 total points). Track your full progress on GrantFox.

👏 Great work, @Emelie-Dev! Keep contributing to Adamantine-guild.