apollographql / apollographql/federation
Update DEVELOPMENT.md with instructions for installing dependencies
- Dominant language
- TypeScript
- Stars
- 725
- Forks
- 276
- Avg merge
- 1h 47m
- Merged PRs (30d)
- 1
Description
It would be beneficial if we documented how dependencies should be installed in this repository in the `DEVELOPMENT.md` within this repository. This reflects how there is a single `package-lock.json` at the root of this monorepo. (When completed, this could be copied into `apollo-server` and `apollo-tooling`.)
What is the instruction? Roughly, I think my straw-dog proposal that is representative of how we operate today, would be that:
### For "dev dependencies" (i.e., `devDependencies`) or types only necessary for local development
* They should be installed in the root of this monorepo, rather than in nested `subpackage/package.json` files. That's because they're shared by the entire monorepo and installed at the root.
* When specifying the version for the package, semver version specifiers should not be used. Instead, use the exact version (i.e., use `x.y.z`, rather than `^x.y.z`). Renovate will update them. (If you _do_ use a version specifier, Renovate will open a PR to "pin" the version.)
### For regular dependencies or types (e.g., `@types/*`) needed by library consumers
* To add a regular dependency for a package, an addition should be added to the `subpackage/package.json` **by hand** (i.e., adding a `"package": "^x.y.z"` to the `dependencies`). Do not run `npm install` in the `subpackage/` directory. (In theory, [a tool](https://stackoverflow.com/a/52524431/4874415) could be used for this, but VS Code is pretty friendly at suggesting the latest version.)
* After adding the package to the `subpackage/package.json` manually, **run `npm install` from the root of this monorepo**. This will update the `package-lock.json` at the root of this monorepo, while ensuring that the published package declares its dependencies appropriately (and that they're installed by library consumers!).
* A note on TypeScript types: When installing `@types/` for a package, if the types are used on the **public** API (e.g., a typed function of this repository returns a type provided by a `@types/` package, the types should be installed **both** in the root of this monorepo's `devDependencies` _as well as_ in the `dependencies` of the package (for the consumers, since only `dependencies` _not_ `devDependencies` are installed when consuming a library). I suspect a tool like [`tsd`](https://github.com/SamVerschueren/tsd) would be useful here to enforce the correct installation, but it's still manually decided right now. If you get this wrong, the consequences are usually just that someone will open an issue. 😉
Any additions to this?
Contributor guide
Research direction
Start with DEVELOPMENT.md and the root package-lock.json, then review the subpackage/package.json files referenced in the issue. Document the proposed root versus package dependency rules, including npm install from the monorepo root and the handling of public @types packages; done means the installation guidance is recorded in DEVELOPMENT.md.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- developer-experience, documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100