From d756a2ef1cada41577b706b325ce2ad79b166296 Mon Sep 17 00:00:00 2001
From: Simon <10131203+gaomeng1900@users.noreply.github.com>
Date: Fri, 5 Dec 2025 20:00:31 +0800
Subject: [PATCH] chore: improve monorepo

---
 CONTRIBUTING.md                            | 6 +++++-
 package-lock.json                          | 1 -
 packages/page-agent/vite.config.js         | 3 +++
 packages/page-controller/tsconfig.dts.json | 9 +++++++++
 packages/page-controller/vite.config.js    | 4 ++--
 packages/website/package.json              | 1 -
 6 files changed, 19 insertions(+), 5 deletions(-)
 create mode 100644 packages/page-controller/tsconfig.dts.json

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d9e967b..81ccd0a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -27,7 +27,11 @@ This is a **monorepo** with npm workspaces containing **two main packages**:
 1. **Core Library** (`packages/page-agent/`) - Pure JavaScript/TypeScript AI agent library for browser DOM automation, published as `page-agent` on npm
 2. **Website** (`packages/website/`) - React documentation and landing page. Also as demo and test page for the core lib. private package `@page-agent/website`
 
-We use a simplified monorepo solution with native npm-workspace. No fancy tooling. Hoisting is required.
+We use a simplified monorepo solution with native npm-workspace + ts reference + vite alias. No fancy tooling. Hoisting is required. 
+
+- When developing. Use alias so that we don't have to pre-build.
+- When bundling. Use external and disable ts `paths` alias to leave deps out.
+- When bundling `UMD` or `Website`. Bundle everything including local packages.
 
 ## 🤝 How to Contribute
 
diff --git a/package-lock.json b/package-lock.json
index 613f7c6..fa7fb15 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -7023,7 +7023,6 @@
 				"@vitejs/plugin-react-swc": "^4.1.0",
 				"i18next": "^25.7.1",
 				"i18next-browser-languagedetector": "^8.2.0",
-				"page-agent": "*",
 				"react": "^19.2.0",
 				"react-dom": "^19.2.0",
 				"react-i18next": "^16.1.4",
diff --git a/packages/page-agent/vite.config.js b/packages/page-agent/vite.config.js
index 6c3c962..b02d5b6 100644
--- a/packages/page-agent/vite.config.js
+++ b/packages/page-agent/vite.config.js
@@ -47,6 +47,9 @@ const libConfig = {
 
 // ============================================================================
 // UMD Config (Browser Bundle for CDN)
+// - alias all local packages so that they can be build in
+// - no external
+// - no d.ts. dts does not work with monorepo aliasing
 // ============================================================================
 /** @type {import('vite').UserConfig} */
 const umdConfig = {
diff --git a/packages/page-controller/tsconfig.dts.json b/packages/page-controller/tsconfig.dts.json
new file mode 100644
index 0000000..9f94da4
--- /dev/null
+++ b/packages/page-controller/tsconfig.dts.json
@@ -0,0 +1,9 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		// @workaround DTS bug
+		// dts do not work with monorepo path mapping
+		// disable path mapping for it
+		"paths": {}
+	}
+}
diff --git a/packages/page-controller/vite.config.js b/packages/page-controller/vite.config.js
index 9f9b06c..c2243af 100644
--- a/packages/page-controller/vite.config.js
+++ b/packages/page-controller/vite.config.js
@@ -13,7 +13,7 @@ console.log(chalk.cyan(`📦 Building @page-agent/page-controller`))
 export default defineConfig({
 	clearScreen: false,
 	plugins: [
-		dts({ tsconfigPath: './tsconfig.json', bundleTypes: true }),
+		dts({ tsconfigPath: './tsconfig.dts.json', bundleTypes: true }),
 		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
 	],
 	publicDir: false,
@@ -29,7 +29,7 @@ export default defineConfig({
 		},
 		outDir: resolve(__dirname, 'dist', 'lib'),
 		rollupOptions: {
-			external: [],
+			external: ['@page-agent/*'],
 		},
 		minify: false,
 		sourcemap: true,
diff --git a/packages/website/package.json b/packages/website/package.json
index 01d1193..361f407 100644
--- a/packages/website/package.json
+++ b/packages/website/package.json
@@ -10,7 +10,6 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"devDependencies": {
-		"page-agent": "*",
 		"@tailwindcss/vite": "^4.1.14",
 		"@types/react": "^19.2.2",
 		"@types/react-dom": "^19.2.1",