|
| 1 | +# TypeScript Template |
| 2 | + |
| 3 | +This repo is meant to act as a reasonable foundation for a single NPM package developed in TypeScript. It makes use of a few tools that we've found particularly useful. Below are some notes on how to get started using these tools and ways in which you might want (or need) to configure them. |
| 4 | + |
| 5 | +## GitHub |
| 6 | + |
| 7 | +In the GitHub settings tab, we typically configure a few things. |
| 8 | + |
| 9 | +**General** |
| 10 | +✅ Automatically delete head branches |
| 11 | + |
| 12 | +**Collaborators and Teams** |
| 13 | +Add relevant teams and contributors with appropriate roles |
| 14 | + |
| 15 | +**Branches** |
| 16 | +Typically we add a branch protection rule for `main` |
| 17 | +Generally, this rule enables: |
| 18 | +* ✅ Require a pull request before merging |
| 19 | + * ✅ Require approvals (1) |
| 20 | +* ✅ Require status checks to pass before merging |
| 21 | + * Each status check must be selected via the search box. Typing "ci/" will show you a list of the ones which exist within this template. "CLA" should also be enabled. |
| 22 | + |
| 23 | +**Code Security and Analysis** |
| 24 | +* Enable "Dependabot security updates" to receive security-related PRs from Dependabot |
| 25 | + |
| 26 | +## CircleCI |
| 27 | + |
| 28 | +This repo comes with a few Circle jobs already implemented (see [`.circleci/config.yml`](.circleci/config.yml)). Circle will run tests on the versions of Node specified in the matrix and enforce linting via Prettier. |
| 29 | + |
| 30 | +In order to enable CircleCI on your new repo, visit the [Apollo org's dashboard](https://app.circleci.com/projects/project-dashboard/github/apollographql/) and add your project. If your repo has already been initialized and added to the apollographql org, you should see the option to add your new project. |
| 31 | + |
| 32 | +## Jest |
| 33 | + |
| 34 | +Jest is a testing framework used by most of Apollo's current projects. |
| 35 | + |
| 36 | +To run tests in the repo: |
| 37 | +`npm test` |
| 38 | + |
| 39 | +The Jest configuration can be found at `jest.config.ts`. As configured, Jest will run all files named `*.test.ts` found within any `__tests__` folder. This is simply a convention chosen by this repo and can be reconfigured via the `testRegex` configuration option in [`jest.config.ts`](jest.config.ts). |
| 40 | + |
| 41 | +For more information on configuring Jest see the [Jest docs](https://jestjs.io/docs/configuration). |
| 42 | + |
| 43 | +## Changesets |
| 44 | + |
| 45 | +Changesets is a tool for managing package versioning, NPM releases, GitHub releases, and CHANGELOG entries. In this template, it comes configured for all of the above. |
| 46 | + |
| 47 | +### Basic usage |
| 48 | + |
| 49 | +Changesets uses changeset files in the `.changeset` directory to determine what versioning upgrades need to happen next, along with related `CHANGELOG` updates and release notes. A changeset file is created by running `npx changeset` and following the prompts. PRs which make functional changes to the package should always come with an accompanying changeset file. The Changeset bot (details below) will comment on PRs as a reminder to contributors to include a changeset file when appropriate. |
| 50 | + |
| 51 | +### Changeset bot |
| 52 | + |
| 53 | +#### Installation |
| 54 | + |
| 55 | +[GitHub app](https://github.com/apps/changeset-bot) |
| 56 | +> Note: a GitHub _org_ admin must approve app installations. By adding a GitHub app to your repo, you'll be submitting a request for approval. At the time of writing this, the GitHub UI doesn't make this clear. |
| 57 | +
|
| 58 | + |
| 59 | +You might also be interested in adding `changeset-bot` to the repo - it leaves comments about the changeset (or lack thereof) for each PR. This serves as a nice reminder and set of instructions for how to create a changeset. |
| 60 | + |
| 61 | +### Changesets enforced in CI (alternative to Changeset bot) |
| 62 | + |
| 63 | +The `changeset-bot` will leave a comment on every PR. If you'd prefer to enforce changesets in CI without the additional noise, you can do so by adding a step to your CircleCI config. We use the following in the Apollo Server repo: |
| 64 | + |
| 65 | +```yaml |
| 66 | + # Ensure that any PR that changes packages has a changeset on it (perhaps |
| 67 | + # an empty one created with `changeset --empty`). |
| 68 | + # We run the Changesets job itself on all branches so that we can require |
| 69 | + # it to pass, but we don't run any steps on the "Version Packages" PRs |
| 70 | + # themselves. |
| 71 | + Changesets: |
| 72 | + docker: |
| 73 | + - image: cimg/base:stable |
| 74 | + steps: |
| 75 | + - run: echo Ensure there is at least one step |
| 76 | + - unless: |
| 77 | + condition: |
| 78 | + matches: |
| 79 | + pattern: "^changeset-release/.+$" |
| 80 | + value: << pipeline.git.branch >> |
| 81 | + steps: |
| 82 | + - setup-node |
| 83 | + - run: npm run changeset-check |
| 84 | +``` |
| 85 | +
|
| 86 | +The referenced script `changeset-check` is defined in `package.json` and is a simple script that runs `changeset status` and exits with a non-zero status if there are any changesets missing like so: |
| 87 | + |
| 88 | +```json |
| 89 | +{ |
| 90 | + // ... |
| 91 | + "scripts": { |
| 92 | + // ... |
| 93 | + "changeset-check": "changeset-check": "changeset status --verbose --since=origin/main" |
| 94 | + } |
| 95 | +} |
| 96 | +``` |
| 97 | + |
| 98 | +### CHANGELOG updates |
| 99 | + |
| 100 | +For proper CHANGELOG management, you MUST configure the [`.changeset/config.json`](.changeset/config.json) file for your repo. The `changelog.repo` field must be the `<org>/<name>` of the repo. |
| 101 | + |
| 102 | +### NPM Publishing |
| 103 | + |
| 104 | +Changesets manages and updates a release PR automatically via a GitHub action [`.github/workflows/release-pr.yml`](.github/workflows/release-pr.yml). The PR consumes all of the committed changesets on `main` in order to bump versions of packages and update the `CHANGELOG` accordingly. Merging this PR will result in publishes to npm IF you've provided an `NPM_TOKEN` as a secret to your repo's GitHub actions (`https://github.com/apollographql/<repo-name>/settings/secrets/actions`). Please reach out to anyone in the `#npm-apollo-bot-owners` Slack channel for a token. Changesets will also publish a GitHub release when this PR is merged. |
| 105 | + |
| 106 | +> Our action borrows directly from the action provided by `changesets`. Visit [the changesets action repo](https://github.com/changesets/action) for more info. |
| 107 | + |
| 108 | +### Removing Changesets |
| 109 | + |
| 110 | +If you're not interested in using `changesets`, just delete the [workflow](.github/workflows/release-pr.yml), uninstall the related dependencies, and delete the related scripts. |
| 111 | + |
| 112 | +> For additional information on `changesets`, [visit the docs](https://github.com/changesets/changesets#documentation). |
| 113 | + |
| 114 | +## CodeSandbox CI |
| 115 | + |
| 116 | +> At the time of writing this, CodeSandbox CI only works for public repos. |
| 117 | + |
| 118 | +### Installation |
| 119 | + |
| 120 | +[GitHub app](https://github.com/apps/codesandbox) |
| 121 | +> Note: a GitHub _org_ admin must approve app installations. By adding a GitHub app to your repo, you'll be submitting a request for approval. At the time of writing this, the GitHub UI doesn't make this clear. |
| 122 | + |
| 123 | +CodeSandbox CI provides an installable build of your package on every PR. If your package builds successfully, CS:CI will leave a comment on the PR with instructions on how to try out your build in a project. This gives contributors access to their work immediately, allowing them to manually test their builds or even use a fix right away. |
| 124 | + |
| 125 | +CS:CI will also provide links to sandboxes which use your newly built package if you choose. This is configurable via the `sandboxes` field in [`.codesandbox/ci.json`](.codesandbox/ci.json). This field is a list of sandbox IDs which you can find via the CodeSandbox web interface. For example, the Apollo Server repo specifies both JS and TS Apollo Server sandboxes like so: `["apollo-server-typescript-3opde","apollo-server"]`. |
| 126 | + |
| 127 | +> For additional information on configuring CS:CI, [visit the docs](https://codesandbox.io/docs/ci). |
| 128 | + |
| 129 | +## Renovate |
| 130 | + |
| 131 | +### Installation |
| 132 | + |
| 133 | +[GitHub app](https://github.com/apps/renovate) |
| 134 | + |
| 135 | +> Note: a GitHub _org_ admin must approve app installations. By adding a GitHub app to your repo, you'll be submitting a request for approval. At the time of writing this, the GitHub UI doesn't make this clear. |
| 136 | + |
| 137 | +Renovate automates dependency updates. The bot will open and merge PRs with updates to a variety of dependencies (including but not limited to npm dependencies). Renovate is _highly_ configurable via the [renovate.json5](renovate.json5) file. Package restrictions and scheduling are just a couple things that we commonly configure. |
| 138 | + |
| 139 | +If you've configured PRs to require approval (mentioned in [GitHub](#github)), you may want to also install [Renovate's Approve bot](https://github.com/apps/renovate-approve). The approve bot will approve all renovate PRs in order to appease the PR approval requirement. |
| 140 | + |
| 141 | +If you're unfamiliar with Renovate, the docs are really worth perusing even if just to get an idea of what kinds of configuration are possible. |
| 142 | + |
| 143 | +> For additional information on configuring Renovate, [visit the docs](https://docs.renovatebot.com/). |
| 144 | + |
| 145 | +## Prettier |
| 146 | + |
| 147 | +Prettier is an opinionated code formatting tool. |
| 148 | + |
| 149 | +To check for formatting issues: |
| 150 | +`npm run prettier:check` |
| 151 | + |
| 152 | +To auto-fix formatting issues: |
| 153 | +`npm run prettier:fix` |
| 154 | + |
| 155 | +This is enforced in CI via the `Prettier` job. |
| 156 | + |
| 157 | +> For additional information on configuring Prettier, [visit the docs](https://prettier.io/docs/en/options). |
| 158 | + |
| 159 | +## Volta |
| 160 | + |
| 161 | +Volta is a fast JS toolchain manager. Similar in effect to nvm, Volta allows for projects to specify their node / npm versions and will automatically handle the switching for you. |
| 162 | + |
| 163 | +If using [direnv](https://direnv.net/), Volta will automatically be installed for you. The node and npm versions are specified in [`package.json`](package.json) and Renovate handles keeping these versions up to date. |
| 164 | + |
| 165 | +> For additional information on configuring Volta, [visit the docs](https://docs.volta.sh/guide/). |
0 commit comments