Migrate to typed-firestore and make common a build package (#36)

* Migrate to typed-firestore and make common built

* Simplify readme

Author: 0x80

.github/checks.yml

@@ -0,0 +1,83 @@
+name: Checks
+
+on:
+  pull_request:
+    branches:
+      - "**"
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  init:
+    runs-on: ubuntu-latest
+    outputs:
+      gcloud_project: ${{ steps.set-project-value.outputs.value }}
+      phase: ${{ steps.set-phase-value.outputs.value }}
+    strategy:
+      matrix:
+        node-version: [22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: "pnpm"
+      - run: pnpm install --frozen-lockfile
+
+  lint:
+    runs-on: ubuntu-latest
+    needs: init
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: "pnpm"
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run lint
+
+  prettier:
+    runs-on: ubuntu-latest
+    needs: init
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: "pnpm"
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run prettier:check
+
+  test:
+    runs-on: ubuntu-latest
+    needs: init
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: "pnpm"
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run test
+
+  compile:
+    runs-on: ubuntu-latest
+    needs: init
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: "pnpm"
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run compile

README.md

@@ -6,17 +6,11 @@
 - [Features](#features)
 - [Install](#install)
 - [Usage](#usage)
-- [Workspace](#workspace)
+- [Monorepo Setup](#monorepo-setup)
   - [Namespace](#namespace)
   - [Packages](#packages)
   - [Apps](#apps)
   - [Services](#services)
-- [The "built packages" strategy](#the-built-packages-strategy)
-  - [Convert path aliases](#convert-path-aliases)
-  - [Write ESM without import file extensions](#write-esm-without-import-file-extensions)
-  - [Tree shaking](#tree-shaking)
-- [The "internal packages" strategy](#the-internal-packages-strategy)
-- [Live code changes from internal packages](#live-code-changes-from-internal-packages)
 - [Firebase](#firebase)
   - [Demo Project](#demo-project)
   - [Deploying](#deploying)
@@ -27,12 +21,12 @@
 
 ## Introduction
 
+This is a personal quest for the perfect Typescript monorepo setup.
+
 > There is an accompanying article
 > ["My quest for the perfect TS monorepo"](https://thijs-koerselman.medium.com/my-quest-for-the-perfect-ts-monorepo-62653d3047eb)
 > that you might want to read for context.
 
-This is a personal quest for the perfect Typescript monorepo setup.
-
 It is the best I could come up with given the tooling that is available, so
 expect this repository to change over time as the ecosystem around Typescript
 evolves.
@@ -59,20 +53,19 @@ and I recommend reading
 
 - [Turborepo](https://turbo.build/) to orchestrate the build process and
   dependencies, including the v2 watch task.
-- Showcasing a traditional "built package" with multiple entry points, as well
-  as the ["internal package"](#the-internal-packages-strategy) strategy
-  referencing Typescript code directly.
 - Multiple isolated Firebase deployments, using
   [firebase-tools-with-isolate](https://github.com/0x80/firebase-tools-with-isolate)
 - Firebase emulators with hot reloading
 - A web app based on Next.js with [ShadCN](https://ui.shadcn.com/) and
   [Tailwind CSS](https://tailwindcss.com/)
 - Working IDE go-to-definition and go-to-type-definition using `.d.ts.map` files
-- ES modules for everything
+- ESM everything
 - Path aliases
 - Shared configurations for ESLint
-- Simple standardized configuration for TypeScript
+- Simple standard configuration for TypeScript
 - Vitest
+- Clean, strongly-typed Firestore code for both React (using
+  `@typed-firestore/react`) and Node.js (using `@typed-firestore/server`)
 
 ## Install
 
@@ -112,7 +105,11 @@ UI on http://localhost:4000.
 You should now have a working local setup, in which code changes to any package
 are picked up.
 
-## Workspace
+## Monorepo Setup
+
+> There is an accompanying article
+> ["My quest for the perfect TS monorepo"](https://thijs-koerselman.medium.com/my-quest-for-the-perfect-ts-monorepo-62653d3047eb)
+> that you might want to read for context.
 
 ### Namespace
 
@@ -143,127 +140,13 @@ clear, but I went with `@repo` because I expect it will become the standard.
 - [api](./services/api) A 2nd gen Firebase function (based on Cloud Run) serving
   as an API endpoint. This package also illustrates how to use secrets.
 
-## The "built packages" strategy
-
-In a traditional monorepo setup, each package exposes its code as if it was a
-published NPM package. For Typescript this means the code has to be transpiled
-and the manifest entry points reference to the build output files. You can use
-Typescript `tsc` compiler for this, but it is likely you will want to use a
-bundler for the reasons explained below.
-
-The `services` in this codebase use TSUP as a bundler. It is a modern, simple to
-use Rollup-inspired bundler for Typescript.
-
-The advantages of using a bundler are discussed below.
-
-### Convert path aliases
-
-If you use path aliases like `~/*` or `@/*` to conveniently reference top-level
-folders from deeply nested import statements, these paths are not converted by
-the standard Typescript `tsc` compiler.
-
-A bundler will typically remove path aliases, because it combines your code into
-self-contained files that do not import other local files themselves.
-
-If you target platforms without using bundler, you will have to convert them.
-You can run something like `tsc-alias` after your build step. Note that path
-aliases can also end up in `d.ts` files.
-
-### Write ESM without import file extensions
-
-A bundler will allow you to output ESM-compatible code without having to adhere
-to the ESM import rules. ESM requires all relative imports to be explicit,
-appending a `.js` file extension for importing TS files and appending
-`/index.js` when importing from the root of a directory.
-
-The reason you need to use `.js` and not `.ts` is because these imports, like
-path aliases are not converted by the Typescript compiler, and so at runtime the
-transpiled JS file is what is getting imported.
-
-Because a bundler, by nature, will bundle code into one or more isolated files,
-those files do not use relative imports and only contain imports from
-`node_modules`, which do not require a file extension. For this reason, a
-bundled js file that uses import and export keywords is an ES module.
-
-An advantage of writing your code as ESM is that you can import both ES modules
-and CommonJS without conversion. An application that uses CJS can not import ESM
-directly, because CJS imports are synchronous and ESM imports are asynchronous.
-
-Not having to use ESM import extensions can be especially valuable if you are
-trying to convert a large codebase to ESM, because I have yet to find a solution
-that can convert existing imports. There is
-[this ESLint plugin](https://github.com/solana-labs/eslint-plugin-require-extensions)
-that you could use it in combination with the --fix flag to inject the
-extensions, but at the time of writing it does not understand path aliases.
-
-### Tree shaking
-
-Some bundlers like TSUP are capable of eliminating dead code by tree-shaking the
-build output, so that less code remains to be deployed. Eliminating dead code is
-most important for client-side code that is shipped to the user, but for the
-core it can also reduce cold-start times for serverless functions, although in
-most situations, it is probably not going to be noticeable.
-
-## The "internal packages" strategy
-
-The
-[internal packages](https://turbo.build/blog/you-might-not-need-typescript-project-references)
-strategy, as it was coined by Jared Palmer of Turborepo, removes the build step
-from the internal packages by linking directly to the Typescript source files in
-the package manifest.
-
-There are some advantages to this approach:
-
-- Code and type changes can be picked up directly, removing the need for a watch
-  task in development mode.
-- Removing the build step reduces overall complexity where you might otherwise
-  use a bundler with configuration.
-- IDE go-to-definition, in which cmd-clicking on a reference takes you to the
-  source location instead of the typed exports, works without the need for
-  Typescript project references or generating `d.ts.map` files.
-
-But, as always, there are also some disadvantages you should be aware of:
-
-- You can not publish the shared packages to NPM, as you do not expose them as
-  Javascript.
-- If you use path aliases like `~/`, you will need to make sure every package
-  has its own unique aliases. You might not need aliases, because shared
-  packages typically do not have a deeply nested folder structure anyway.
-- Since all source code gets compiled by the consuming application, build times
-  can start to suffer when the codebase grows. See
-  [caveats](https://turbo.build/blog/you-might-not-need-typescript-project-references#caveats)
-  for more info.
-- The shared package is effectively just a source folder, and as a whole it
-  needs to be transpiled and bundled into the consuming package. This means that
-  its dependencies must also be available in the consuming package. Next.js can
-  do this for you with the `transpilePackage` setting, but this is the reason
-  `services/api` includes `remeda`, as it is used by `packages/common`.
-
-For testing and comparison, mono-ts uses the internal packages approach for
-`@repo/common` and a traditional built approach for `@repo/core`. Both are
-compatible with `isolate-package` for deploying to Firebase.
-
-## Live code changes from internal packages
-
-Traditionally in a monorepo, each package is treated similarly to a released NPM
-package, meaning that the code and types are resolved from the built "dist"
-output for each module. Adding new types and changing code in shared packages
-therefore requires you to rebuild these, which can be cumbersome during
-development.
-
-Turborepo does not (yet) include a watch task, so
-[Turbowatch](https://github.com/gajus/turbowatch) was created to solve this
-issue. I haven't tried it but it looks like a neat solution. However, you might
-want to use the
-[internal packages strategy instead](#the-internal-packages-strategy).
-
 ## Firebase
 
 In their
 [documentation for monorepos](https://firebase.google.com/docs/functions/organize-functions?gen=2nd#managing_multiple_source_packages_monorepo),
 Firebase recommends putting all configurations in the root of the monorepo. This
-makes it possible to deploy all packages at once, and most importantly, run the
-emulators shared on common ports.
+makes it possible to deploy all packages at once, and easily start the emulators
+shared between all packages.
 
 ### Demo Project
 

apps/web/package.json

@@ -15,14 +15,14 @@
     "@radix-ui/react-icons": "^1.3.2",
     "@radix-ui/react-slot": "^1.1.1",
     "@repo/common": "workspace:*",
+    "@typed-firestore/react": "1.0.0-0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "firebase": "^11.1.0",
     "lucide-react": "^0.471.0",
     "next": "15.1.4",
     "react": "19.0.0",
     "react-dom": "19.0.0",
-    "react-firebase-hooks": "^5.1.1",
     "tailwind-merge": "^2.6.0",
     "tailwindcss-animate": "^1.0.7",
     "typescript": "^5.7.3"

apps/web/src/app/components/counter-view.tsx

@@ -1,13 +1,10 @@
-import type { Counter } from "@repo/common";
-import { doc } from "firebase/firestore";
-import { useTypedDocument } from "~/lib/firestore";
-import { refs } from "~/refs";
+import { useDocument } from "@typed-firestore/react";
+import { refs } from "~/db-refs";
 import KeyValueList from "./key-value-list";
 
 export function CounterView(props: { counterId: string }) {
-  const [counter, isLoading] = useTypedDocument<Counter>(
-    doc(refs.counters, props.counterId)
-  );
+  /** Note that counter is typed correctly here by `@typed-firestore/react` ✨ */
+  const [counter, isLoading] = useDocument(refs.counters, props.counterId);
 
   if (isLoading) {
     return <div>Loading...</div>;

apps/web/src/db-refs.ts

@@ -0,0 +1,15 @@
+import type { Counter } from "@repo/common";
+import { collection, type CollectionReference } from "firebase/firestore";
+import { db } from "~/lib/firebase";
+
+/**
+ * Here we define reusable references to collections and type each of them so
+ * that functions from `@typed-firestore/react` can infer the types
+ * automatically for us.
+ *
+ * Note that this file is slightly different from the one in `services/api`
+ * because the backend types from firebase-admin are possibly not compatible.
+ */
+export const refs = {
+  counters: collection(db, "counters") as CollectionReference<Counter>,
+};

apps/web/src/refs.ts

@@ -3,18 +3,19 @@
   "description": "Common code for both backend and frontend",
   "version": "0.0.0",
   "type": "module",
-  "types": "./src/index.ts",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./dist/index.js"
   },
   "files": [
-    "src"
+    "dist"
   ],
   "scripts": {
     "compile": "tsc --noEmit",
     "test": "vitest",
     "lint": "eslint . --max-warnings 0",
-    "build?": "No build step required. This package links directly to its source files",
+    "build": "tsup && tsc --emitDeclarationOnly",
+    "clean": "del-cli dist tsconfig.tsbuildinfo",
     "coverage": "vitest run --coverage "
   },
   "license": "MIT",
@@ -28,6 +29,7 @@
     "eslint": "^8.57.1",
     "eslint-plugin-require-extensions": "^0.1.3",
     "prettier": "^3.4.2",
+    "tsup": "^8.3.5",
     "typescript": "^5.7.3",
     "vitest": "^2.1.8"
   }

packages/common/package.json

@@ -1,5 +1,5 @@
 import * as R from "remeda";
 
-export function unique<T>(array: T[]) {
-  return R.unique<T>(array);
+export function unique<T extends readonly unknown[]>(array: T) {
+  return R.unique(array);
 }

packages/common/src/utils/unique.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: {
+    index: "src/index.ts",
+  },
+  format: ["esm"],
+  target: "es2022",
+  sourcemap: true,
+
+  /**
+   * Do not use tsup for generating d.ts files because it can not generate type
+   * the definition maps required for go-to-definition to work in our IDE. We
+   * use tsc for that.
+   */
+});