From ead33399c55f9912bcd320f61c2705179225781f Mon Sep 17 00:00:00 2001
From: Pete Miller <miller.pete@gmail.com>
Date: Wed, 12 May 2021 20:21:14 -0700
Subject: [PATCH] Readme and comments for webpack build inputs and typescript
 global definitions

---
 components/common/typescript.gni | 27 ++++++++++++++++-----------
 components/definitions/README.md | 12 ++++++++++++
 2 files changed, 28 insertions(+), 11 deletions(-)
 create mode 100644 components/definitions/README.md

diff --git a/components/common/typescript.gni b/components/common/typescript.gni
index 64fdd217698..2719526ac42 100644
--- a/components/common/typescript.gni
+++ b/components/common/typescript.gni
@@ -1,14 +1,14 @@
 import("//tools/grit/grit_rule.gni")
 
-# Make sure webpack re-builds when...
+# JS / TS imports via `require` or `import` will be added to a list and
+# provided to GN so it knows which projects to re-build when you modify a file
+# that is used by your build.
+# This variable contains additional files that will cause a re-build of all
+# WebUI projects if they are modified:
 brave_common_web_compile_inputs = [
-  # common includes change
-  rebase_path("classSet.ts"),
-  rebase_path("debounce.ts"),
-  rebase_path("locale.ts"),
-  rebase_path("BraveCoreThemeProvider.tsx"),
-
-  # common definitions change
+  # Global Definitions
+  # Only add actual globally-available type definitions to this directory,
+  # see ../definitions/README.md.
   rebase_path("../definitions/adBlock.d.ts"),
   rebase_path("../definitions/ipfs.d.ts"),
   rebase_path("../definitions/webcompatReporter.d.ts"),
@@ -26,14 +26,19 @@ brave_common_web_compile_inputs = [
   rebase_path("../definitions/webtorrent.d.ts"),
   rebase_path("../definitions/welcome.d.ts"),
 
-  # webpack config changes
+  # webpack config changes warrant a re-build of all webpack builds
   rebase_path("../webpack/webpack.config.js"),
   rebase_path("../webpack/webpack-plugin-depfile.js"),
 
-  # typescript config changes
+  # typescript config changes warrant a re-build of all typescript builds
   "//brave/tsconfig.json",
 
-  # brave-ui changes on its own (perhaps a manual local link)
+  # modifying npm dependencies warrants a re-build of all webpack
+  # and typescript builds
+  "//brave/package.json",
+
+  # brave-ui changes (perhaps a manual local link which wouldn't affect
+  # //brave/package.json)
   "//brave/node_modules/brave-ui/package.json",
 ]
 
diff --git a/components/definitions/README.md b/components/definitions/README.md
new file mode 100644
index 00000000000..90681075c67
--- /dev/null
+++ b/components/definitions/README.md
@@ -0,0 +1,12 @@
+## Typescript Definition Files
+
+This directory is where we locate Typescript type definitions of Javascript APIs and objects. Only .d.ts files should be present - that is, files that do not result in any extra Javascript.
+
+### What needs a global definiton
+
+- Globally-available APIs that are not common outside of Brave - generally at `chrome.*` or `window.*`.
+- JS / NPM modules that do not already have Typescript types built-in.
+
+### What does _not_ need a global definition
+
+Types that are local to your specific page or app. Instead, define the type within your component, export it and import it where you need to reference it.