|
| 1 | +# Graphile v5 RC Dependency Management |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This monorepo contains several packages that depend on the [Graphile](https://graphile.org/) v5 release candidate (RC) ecosystem. The Graphile v5 RC packages are **tightly coupled** -- all packages in the ecosystem must be at matching RC versions to work correctly. |
| 6 | + |
| 7 | +## The Problem (Why We Pin) |
| 8 | + |
| 9 | +Graphile v5 RC packages declare peer dependencies on each other. When a new RC is released, the minimum required versions of those peer deps often bump together. For example, `graphile-build-pg@5.0.0-rc.5` requires `@dataplan/pg@^1.0.0-rc.5` and `tamedevil@^0.1.0-rc.4`, whereas the earlier `rc.3` only required `rc.3` versions of those peers. |
| 10 | + |
| 11 | +If our packages use loose caret ranges (e.g., `^5.0.0-rc.3`), the package manager may resolve to the **latest** RC (e.g., `rc.5` or `rc.7`), which introduces new peer dependency requirements that nothing in our tree satisfies. This causes cascading "missing peer dependency" warnings like: |
| 12 | + |
| 13 | +``` |
| 14 | +graphile-build-pg 5.0.0-rc.5 |
| 15 | + - missing peer @dataplan/pg@^1.0.0-rc.5 |
| 16 | + - missing peer tamedevil@^0.1.0-rc.4 |
| 17 | +postgraphile 5.0.0-rc.7 |
| 18 | + - missing peer @dataplan/pg@^1.0.0-rc.5 |
| 19 | + - missing peer @dataplan/json@^1.0.0-rc.5 |
| 20 | + - missing peer grafserv@^1.0.0-rc.6 |
| 21 | + - missing peer tamedevil@^0.1.0-rc.4 |
| 22 | +``` |
| 23 | + |
| 24 | +## Our Approach: Pinned Exact Versions |
| 25 | + |
| 26 | +All Graphile RC dependencies are pinned to **exact versions** (no `^` or `~` prefix). This ensures: |
| 27 | + |
| 28 | +1. Every package in the monorepo uses the same RC version set |
| 29 | +2. No version drift when new RCs are published |
| 30 | +3. All peer dependency requirements are explicitly satisfied |
| 31 | +4. Deterministic installs across environments |
| 32 | + |
| 33 | +## Current Pinned Versions |
| 34 | + |
| 35 | +| Package | Pinned Version | |
| 36 | +|---------|---------------| |
| 37 | +| `grafast` | `1.0.0-rc.7` | |
| 38 | +| `grafserv` | `1.0.0-rc.6` | |
| 39 | +| `graphile-build` | `5.0.0-rc.4` | |
| 40 | +| `graphile-build-pg` | `5.0.0-rc.5` | |
| 41 | +| `graphile-config` | `1.0.0-rc.5` | |
| 42 | +| `graphile-utils` | `5.0.0-rc.6` | |
| 43 | +| `pg-sql2` | `5.0.0-rc.4` | |
| 44 | +| `postgraphile` | `5.0.0-rc.7` | |
| 45 | +| `@dataplan/json` | `1.0.0-rc.5` | |
| 46 | +| `@dataplan/pg` | `1.0.0-rc.5` | |
| 47 | +| `tamedevil` | `0.1.0-rc.4` | |
| 48 | +| `@graphile-contrib/pg-many-to-many` | `2.0.0-rc.1` | |
| 49 | +| `postgraphile-plugin-connection-filter` | `3.0.0-rc.1` | |
| 50 | + |
| 51 | +## Packages That Use Graphile |
| 52 | + |
| 53 | +### `graphile/` packages |
| 54 | + |
| 55 | +- **graphile-settings** -- Core settings/configuration for PostGraphile v5 (most deps, including the transitive peer deps `tamedevil`, `@dataplan/pg`, `@dataplan/json`, `grafserv`) |
| 56 | +- **graphile-schema** -- Builds GraphQL SDL from PostgreSQL using PostGraphile v5 |
| 57 | +- **graphile-query** -- Executes GraphQL queries against PostGraphile v5 schemas |
| 58 | +- **graphile-search-plugin** -- Full-text search plugin for PostGraphile v5 |
| 59 | +- **graphile-cache** -- LRU cache with PostGraphile v5 integration |
| 60 | +- **graphile-test** -- PostGraphile v5 testing utilities |
| 61 | +- **graphile-authz** -- Dynamic authorization plugin for PostGraphile v5 |
| 62 | +- **postgraphile-plugin-pgvector** -- pgvector similarity search plugin for PostGraphile v5 |
| 63 | + |
| 64 | +### `graphql/` packages |
| 65 | + |
| 66 | +- **@constructive-io/graphql-server** -- GraphQL server with PostGraphile v5 |
| 67 | +- **@constructive-io/graphql-test** -- GraphQL testing with all plugins loaded |
| 68 | +- **@constructive-io/graphql-query** -- GraphQL query builder |
| 69 | +- **@constructive-io/graphql-explorer** -- GraphQL Explorer UI |
| 70 | + |
| 71 | +**Important:** Having different versions of `grafast` (or other singleton graphile packages) installed in the same workspace causes runtime errors like `Preset attempted to register version 'X' of 'grafast', but version 'Y' is already registered`. This is why **all** packages must use the same pinned versions. |
| 72 | + |
| 73 | +## Upgrading Graphile RC Versions |
| 74 | + |
| 75 | +When upgrading to a new Graphile RC set: |
| 76 | + |
| 77 | +1. Check the latest RC versions on npm for all packages listed in the table above |
| 78 | +2. Verify peer dependency compatibility by running `npm view <package>@<version> peerDependencies` for each package |
| 79 | +3. Update **all** packages in this table simultaneously -- do not upgrade one without the others |
| 80 | +4. Update every `graphile/*/package.json` and `graphql/*/package.json` that references these packages |
| 81 | +5. Run `pnpm install` to update the lockfile |
| 82 | +6. Run `pnpm build` to verify no type errors |
| 83 | +7. Run tests to verify nothing broke |
| 84 | +8. Update the version table in this document |
0 commit comments