[AI] Enable TypeScript composite project references across monorepo (#7062)

* [AI] Enable TypeScript composite project references across monorepo

- Add composite and declaration emit to all package tsconfigs
- Wire root and per-package project references in dependency order
- Replace cross-package include-based typing with referenced outputs
- Fix api TS5055 by emitting declarations to decl-output
- Add desktop-client alias for tests; fix oxlint import order in vite.config
- Add UsersState.data null type and openDatabase return type for strict emit

Co-authored-by: Cursor <cursoragent@cursor.com>

* Remove obsolete TypeScript configuration for API and update build script to emit declarations directly to the output directory. This streamlines the build process and ensures compatibility with the new project structure.

* Refactor TypeScript configuration in API package to remove obsolete decl-output directory and update build scripts. The changes streamline the build process by directing declaration outputs to the @types directory, ensuring better organization and compatibility with the new project structure.

* Add TypeScript declaration emission for loot-core in desktop-electron build process

* Refactor TypeScript configuration in API package to utilize composite references and streamline build scripts. Update include and exclude patterns for improved file management, ensuring better organization of declaration outputs and migration SQL files.

* Refactor TypeScript configuration in loot-core and desktop-client packages to streamline path management and remove obsolete dependencies. Update paths in tsconfig.json files for better organization and compatibility, and adjust yarn.lock to reflect changes in workspace dependencies.

* Update desktop-electron package to utilize loot-core as a workspace dependency. Adjust TypeScript import paths and tsconfig references for improved organization and compatibility across packages.

* Enhance Vite configuration for desktop-client to support Electron-specific conditions and update loot-core package.json to include Electron as a platform for client connection. This improves compatibility for Electron builds.

* Refactor TypeScript configuration across multiple packages to streamline path management. Update tsconfig.json files in root, api, and loot-core packages to improve import paths and maintain compatibility with internal typings.

* Update package dependencies and Vite configuration across component-library and desktop-client. Add vite-tsconfig-paths to component-library and remove it from desktop-client. Refactor Storybook preview file to include a TODO for future refactoring.

* Remove Node-specific path from loot-core package.json for client connection, streamlining platform configuration for Electron.

* Remove loot-core as a workspace dependency from desktop-electron package.json

* Update tsconfig.json to remove reference to desktop-client

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

.gitignore

@@ -33,7 +33,9 @@ packages/desktop-electron/dist
 packages/desktop-electron/loot-core
 packages/desktop-client/service-worker
 packages/plugins-service/dist
+packages/component-library/dist
 packages/loot-core/lib-dist
+**/.tsbuildinfo
 packages/sync-server/coverage
 bundle.desktop.js
 bundle.desktop.js.map

bin/package-electron

@@ -59,6 +59,9 @@ yarn workspace loot-core build:browser
 yarn workspace @actual-app/web build:browser
 yarn workspace @actual-app/sync-server build
 
+# Emit loot-core declarations so desktop-electron (which includes typings/window.ts) can build
+yarn workspace loot-core exec tsc -p tsconfig.json
+
 yarn workspace desktop-electron update-client
 
 (

package.json

@@ -54,10 +54,10 @@
     "vrt:docker": "./bin/run-vrt",
     "rebuild-electron": "./node_modules/.bin/electron-rebuild -m ./packages/loot-core",
     "rebuild-node": "yarn workspace loot-core rebuild",
-    "lint": "oxfmt --check . && oxlint --type-aware",
-    "lint:fix": "oxfmt . && oxlint --fix --type-aware",
+    "lint": "yarn workspace @actual-app/api clean && oxfmt --check . && oxlint --type-aware",
+    "lint:fix": "yarn workspace @actual-app/api clean && oxfmt . && oxlint --fix --type-aware",
     "install:server": "yarn workspaces focus @actual-app/sync-server --production",
-    "typecheck": "tsc -p tsconfig.root.json --noEmit && lage typecheck",
+    "typecheck": "yarn workspace @actual-app/api clean && tsc -b && tsc -p tsconfig.root.json --noEmit && lage typecheck",
     "jq": "./node_modules/node-jq/bin/jq",
     "prepare": "husky"
   },

packages/api/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
+    "composite": true,
     // Using ES2021 because that's the newest version where
     // the latest Node 16.x release supports all of the features
     "target": "ES2021",
@@ -8,14 +9,18 @@
     "moduleResolution": "node10",
     "noEmit": false,
     "declaration": true,
+    "declarationMap": true,
     "outDir": "dist",
     "rootDir": ".",
     "declarationDir": "@types",
+    "tsBuildInfoFile": "dist/.tsbuildinfo",
     "paths": {
-      "loot-core/*": ["./@types/loot-core/src/*"]
+      // TEMPORARY
+      "loot-core/*": ["../loot-core/src/*"]
     },
     "plugins": [{ "name": "typescript-strict-plugin", "paths": ["."] }]
   },
+  "references": [{ "path": "../crdt" }, { "path": "../loot-core" }],
   "include": ["."],
   "exclude": ["**/node_modules/*", "dist", "@types", "*.test.ts"]
 }

packages/component-library/.storybook/preview.tsx

@@ -3,6 +3,7 @@ import { type ReactNode } from 'react';
 import type { Preview } from '@storybook/react-vite';
 
 // Not ideal to import from desktop-client, but we need a source of truth for theme variables
+// TODO: this needs refactoring
 import * as darkTheme from '../../desktop-client/src/style/themes/dark';
 import * as developmentTheme from '../../desktop-client/src/style/themes/development';
 import * as lightTheme from '../../desktop-client/src/style/themes/light';

packages/component-library/package.json

@@ -58,6 +58,7 @@
     "react": "19.2.4",
     "react-dom": "19.2.4",
     "storybook": "^10.2.7",
+    "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {

packages/component-library/tsconfig.json

@@ -1,9 +1,14 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
-    "noEmit": true,
+    "composite": true,
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": true,
     "rootDir": "src",
-    "strict": true
+    "strict": true,
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo"
   },
   "include": ["src/**/*.ts", "src/**/*.tsx"],
   "exclude": ["node_modules"]

packages/crdt/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
+    "composite": true,
     // Using ES2021 because that's the newest version where
     // the latest Node 16.x release supports all of the features
     "target": "ES2021",
@@ -8,8 +9,10 @@
     "moduleResolution": "node10",
     "noEmit": false,
     "declaration": true,
+    "declarationMap": true,
     "strict": true,
-    "outDir": "dist"
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo"
   },
   "include": ["."],
   "exclude": ["dist", "**/*.test.ts", "**/*.spec.ts"]

packages/desktop-client/package.json

@@ -97,7 +97,6 @@
     "uuid": "^13.0.0",
     "vite": "^7.3.1",
     "vite-plugin-pwa": "^1.2.0",
-    "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^4.0.18",
     "xml2js": "^0.6.2"
   }

packages/desktop-client/tsconfig.json

@@ -1,13 +1,29 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
-    "noEmit": true,
+    "composite": true,
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "outDir": "build/ts",
+    "rootDir": "src",
+    "tsBuildInfoFile": "build/ts/.tsbuildinfo",
+    "paths": {
+      // TODO: move to subpath imports
+      "@desktop-client/*": ["./src/*"]
+    },
     "plugins": [{ "name": "typescript-strict-plugin", "paths": ["."] }]
   },
+  "references": [
+    { "path": "../loot-core" },
+    { "path": "../component-library" }
+  ],
   "include": [
     "src/**/*.ts",
     "src/**/*.tsx",
-    "../../packages/loot-core/typings/pegjs.ts",
+    "src/**/*.js",
+    // TODO: remove loot-core dependency
     "../../packages/loot-core/typings/window.ts"
   ],
   "exclude": [

packages/desktop-client/tsconfig.service-worker.json

@@ -1,7 +1,9 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
+    "composite": true,
     "noEmit": false,
+    "declaration": true,
     "outDir": "./service-worker",
     "target": "ES2022",
     "lib": ["ES2022", "WebWorker", "DOM", "DOM.Iterable"],
@@ -11,7 +13,8 @@
     "esModuleInterop": true,
     "skipLibCheck": true,
     "strict": false,
-    "types": ["vite/client"]
+    "types": ["vite/client"],
+    "tsBuildInfoFile": "./service-worker/.tsbuildinfo"
   },
   "include": ["src/plugin-service-worker.ts"],
   "exclude": ["**/*.test.ts", "**/*.spec.ts"]

packages/desktop-client/vite.config.mts

@@ -1,4 +1,5 @@
 import * as path from 'path';
+import { fileURLToPath } from 'url';
 
 import inject from '@rollup/plugin-inject';
 import basicSsl from '@vitejs/plugin-basic-ssl';
@@ -9,7 +10,8 @@ import { visualizer } from 'rollup-plugin-visualizer';
 import { defineConfig, loadEnv } from 'vite';
 import type { Plugin } from 'vite';
 import { VitePWA } from 'vite-plugin-pwa';
-import viteTsconfigPaths from 'vite-tsconfig-paths';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 const addWatchers = (): Plugin => ({
   name: 'add-watchers',
@@ -150,6 +152,12 @@ export default defineConfig(async ({ mode }) => {
     },
     resolve: {
       extensions: resolveExtensions,
+      alias: {
+        '@desktop-client': path.join(__dirname, 'src'),
+      },
+      ...(!env.IS_GENERIC_BROWSER && {
+        conditions: ['electron', 'module', 'browser', 'default'],
+      }),
     },
     plugins: [
       // electron (desktop) builds do not support PWA
@@ -204,7 +212,6 @@ export default defineConfig(async ({ mode }) => {
           plugins: ['babel-plugin-react-compiler'],
         },
       }),
-      viteTsconfigPaths({ root: '../..' }),
       visualizer({ template: 'raw-data' }),
       !!env.HTTPS && basicSsl(),
     ],

packages/desktop-electron/preload.ts

@@ -1,3 +1,4 @@
+// @ts-strict-ignore
 import { contextBridge, ipcRenderer } from 'electron';
 import type { IpcRenderer } from 'electron';
 

packages/desktop-electron/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
+    "composite": true,
     // Using ES2021 because that's the newest version where
     // the latest Node 16.x release supports all of the features
     "target": "ES2021",
@@ -8,11 +9,14 @@
     "moduleResolution": "node10",
     "noEmit": false,
     "declaration": true,
+    "declarationMap": true,
     "outDir": "build",
     "rootDir": "..",
+    "tsBuildInfoFile": "build/.tsbuildinfo",
     "plugins": [{ "name": "typescript-strict-plugin", "paths": ["."] }]
   },
-  "include": [".", "../../packages/loot-core/typings/window.ts"],
+  "references": [{ "path": "../loot-core" }, { "path": "../sync-server" }],
+  "include": ["."],
   "exclude": [
     "**/node_modules/*",
     "build/**/*",

packages/loot-core/bin/build-api

@@ -5,17 +5,7 @@ set -euo pipefail
 cd "$(dirname "$0")/.." || exit 1
 ROOT="$(pwd -P)"
 
-yarn tsc -p tsconfig.api.json --outDir ../api/@types/loot-core/
-# Copy existing handwritten .d.ts files, as tsc doesn't move them for us
-dest="../../api/@types/loot-core"
-cd src
-find . -type f -name "*.d.ts" | while read -r f
-do
-    d=$(dirname "${f}")
-    d="${dest}/${d}"
-    mkdir -p "${d}"
-    cp "${f}" "${d}"
-done
-cd "$ROOT"
-yarn vite build --config ./vite.api.config.ts;
+# Emit declarations to lib-dist/decl so api package (and tsc -b) can consume them
+yarn tsc -p tsconfig.json
+yarn vite build --config ./vite.api.config.ts
 ./bin/copy-migrations ../api

packages/loot-core/package.json

@@ -33,7 +33,7 @@
     "./client/undo": "./src/client/undo.ts",
     "./mocks": "./src/mocks/index.ts",
     "./platform/client/connection": {
-      "node": "./src/platform/client/connection/index.ts",
+      "electron": "./src/platform/client/connection/index.ts",
       "default": "./src/platform/client/connection/index.browser.ts"
     },
     "./platform/client/undo": "./src/platform/client/undo/index.ts",
@@ -47,8 +47,8 @@
     "./server/budget/types/*": "./src/server/budget/types/*.d.ts",
     "./server/*": "./src/server/*.ts",
     "./shared/*": "./src/shared/*.ts",
-    "./types/models": "./src/types/models/index.d.ts",
-    "./types/*": "./src/types/*.d.ts",
+    "./types/models": "./src/types/models/index.ts",
+    "./types/*": "./src/types/*.ts",
     "./lib-dist/electron/bundle.desktop.js": "./lib-dist/electron/bundle.desktop.js"
   },
   "scripts": {
@@ -90,7 +90,6 @@
   "devDependencies": {
     "@actual-app/api": "workspace:^",
     "@actual-app/crdt": "workspace:^",
-    "@actual-app/web": "workspace:^",
     "@swc/core": "^1.15.11",
     "@types/adm-zip": "^0.5.7",
     "@types/better-sqlite3": "^7.6.13",

packages/loot-core/src/platform/client/undo/index.ts

@@ -1,10 +1,10 @@
-// This is temporary until we move all loot-core/client over to desktop-client.
-// oxlint-disable-next-line eslint/no-restricted-imports
-import type { Modal } from '@actual-app/web/src/modals/modalsSlice';
 import { v4 as uuidv4 } from 'uuid';
 
 import type { UndoState as ServerUndoState } from '../../../server/undo';
 
+// oxlint-disable-next-line @typescript-eslint/no-explicit-any
+type Modal = any; // TODO: fix me
+
 type UndoState = {
   url: string | null;
   openModal: Modal | null;

packages/loot-core/tsconfig.api.json

@@ -1,17 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "rootDir": ".",
-    "declaration": true,
-    "emitDeclarationOnly": true,
-    "allowJs": false,
-    "noEmit": false
-  },
-  "include": ["./typings", "./src/server/*"],
-  "exclude": [
-    "**/node_modules/*",
-    "**/build/*",
-    "**/lib-dist/*",
-    "./src/server/bench.ts"
-  ]
-}

packages/loot-core/tsconfig.json

@@ -1,15 +1,28 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
-    "noEmit": true,
+    "composite": true,
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "outDir": "lib-dist/decl",
+    "rootDir": ".",
+    "tsBuildInfoFile": "lib-dist/decl/.tsbuildinfo",
     "types": ["vite/client", "vitest/globals", "node"],
+    "paths": {
+      // Allow importing from hyperformula's internal typings for custom function plugins
+      "hyperformula/typings/*": ["../../node_modules/hyperformula/typings/*"]
+    },
     "plugins": [{ "name": "typescript-strict-plugin", "paths": ["."] }]
   },
   "include": [
     "src/**/*.ts",
     "src/**/*.tsx",
     "typings/**/*.ts",
-    "typings/**/*.d.ts"
+    "typings/**/*.d.ts",
+    "migrations/**/*.js",
+    "src/server/tests/mockData.json"
   ],
   "exclude": [
     "node_modules",

packages/plugins-service/tsconfig.json

@@ -1,5 +1,6 @@
 {
   "compilerOptions": {
+    "composite": true,
     "target": "ES2022",
     "lib": ["ES2022", "WebWorker", "DOM", "DOM.Iterable"],
     "module": "ES2022",
@@ -9,8 +10,11 @@
     "skipLibCheck": true,
     "strict": false,
     "types": ["vite/client"],
+    "declaration": true,
+    "declarationMap": true,
     "outDir": "dist",
     "rootDir": "src",
+    "tsBuildInfoFile": "dist/.tsbuildinfo",
     "plugins": [{ "name": "typescript-strict-plugin", "paths": ["."] }]
   },
   "include": ["src/**/*"],

packages/sync-server/tsconfig.json

@@ -1,11 +1,16 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
+    "composite": true,
     "lib": ["ES2021"],
     "noEmit": false,
+    "declaration": true,
+    "declarationMap": true,
     "outDir": "build",
+    "tsBuildInfoFile": "build/.tsbuildinfo",
     "plugins": [{ "name": "typescript-strict-plugin", "paths": ["."] }]
   },
+  "references": [{ "path": "../crdt" }],
   "include": [
     "src/**/*",
     "migrations/**/*",

tsconfig.json

@@ -1,11 +1,15 @@
 {
   "references": [
-    // TODO: enable once every project is ts
-    // { "path": "./packages/api" },
-    // { "path": "./packages/desktop-client" }
+    { "path": "./packages/crdt" },
+    { "path": "./packages/component-library" },
+    { "path": "./packages/plugins-service" },
+    { "path": "./packages/loot-core" },
+    { "path": "./packages/api" },
+    { "path": "./packages/desktop-client" },
+    { "path": "./packages/sync-server" },
+    { "path": "./packages/desktop-electron" }
   ],
   "compilerOptions": {
-    // "composite": true,
     "target": "ES2022",
     "lib": ["ES2022", "DOM", "DOM.Iterable"],
     "allowSyntheticDefaultImports": true,
@@ -28,17 +32,9 @@
     "moduleResolution": "bundler",
     "module": "es2022",
     // Until/if we build using tsc
-    "noEmit": true,
-    "paths": {
-      // TEMPORARY: Until we can fix the "exports" in the loot-core package.json
-      "loot-core/*": ["./packages/loot-core/src/*"],
-      "@desktop-client/*": ["./packages/desktop-client/src/*"],
-      "@desktop-client/e2e/*": ["./packages/desktop-client/e2e/*"],
-      // Allow importing from hyperformula's internal typings for custom function plugins
-      "hyperformula/typings/*": ["./node_modules/hyperformula/typings/*"]
-    }
+    "noEmit": true
   },
-  "include": ["packages/**/*", "bin/*.ts"],
+  "include": ["bin/*.ts"],
   "exclude": [
     "**/.*/",
     "node_modules",

upcoming-release-notes/7062.md

@@ -0,0 +1,6 @@
+---
+category: Maintenance
+authors: [MatissJanis]
+---
+
+TypeScript: start using composite references

yarn.lock

@@ -60,6 +60,7 @@ __metadata:
     react-dom: "npm:19.2.4"
     storybook: "npm:^10.2.7"
     usehooks-ts: "npm:^3.1.1"
+    vite-tsconfig-paths: "npm:^5.1.4"
     vitest: "npm:^4.0.18"
   peerDependencies:
     react: ">=19.2"
@@ -138,7 +139,7 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@actual-app/web@workspace:*, @actual-app/web@workspace:^, @actual-app/web@workspace:packages/desktop-client":
+"@actual-app/web@workspace:*, @actual-app/web@workspace:packages/desktop-client":
   version: 0.0.0-use.local
   resolution: "@actual-app/web@workspace:packages/desktop-client"
   dependencies:
@@ -220,7 +221,6 @@ __metadata:
     uuid: "npm:^13.0.0"
     vite: "npm:^7.3.1"
     vite-plugin-pwa: "npm:^1.2.0"
-    vite-tsconfig-paths: "npm:^5.1.4"
     vitest: "npm:^4.0.18"
     xml2js: "npm:^0.6.2"
   languageName: unknown
@@ -19649,7 +19649,6 @@ __metadata:
   dependencies:
     "@actual-app/api": "workspace:^"
     "@actual-app/crdt": "workspace:^"
-    "@actual-app/web": "workspace:^"
     "@jlongster/sql.js": "npm:^1.6.7"
     "@reduxjs/toolkit": "npm:^2.11.2"
     "@rschedule/core": "npm:^1.5.0"