A very opinionated template for Node.js applications written in TypeScript.
This is a GitHub template repository. You can create a new repository from this template by clicking the green Use this template button. See https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template.
- Node.js 14
- TypeScript 4.2
- ESLint 7
- Yarn berry
You need to have yarn
installed. To install, run npm install -g yarn
.
This template uses the yarn
package manager in the version berry
with the nodeLinker
for maximum compatibility.
Dependency installations are nearly instant and work offline due to the use of a cache in .yarn/cache
.
Documentation: https://yarnpkg.com/getting-started
# With dependency pinning
yarn add -E package # Install package to dependencies
yarn add -DE package # Install package to devDependencies
# Without dependency pinning
yarn add package # Install package to dependencies
yarn add -D package # Install package to devDependencies
yarn
is configured to automatically install corresponding @types/
packages. (See https://yarnpkg.com/api/modules/plugin_typescript.html)
# Install dependencies
yarn
# Run app in development mode with hot reload (powered by nodemon and ts-node)
yarn dev
# Build app
yarn build
# Check for TypeScript errors
yarn tsc:check
# Serve app in production
yarn start
We use the opinionated Prettier code formatter along with ESLint for static code analysis.
ESLint is configured to automatically format the code based on Prettier rules and apply recommended rules based on eslint
and @typescript-eslint
.
This template automatically configures IntelliJ based IDEs (PHPStorm, Webstorm, ...) and Visual Studio Code to apply ESLint fixes on every file save.
You can also run ESLint from the command line. Remember that this also runs prettier, so you should never need to run prettier manually.
# Lint all files
yarn lint
# Lint and auto-fix all files
yarn lint:fix
The testing framework jest is pre-configured to work with TypeScript.
Write tests in the test directory and configure jest with the jest.config.js
.
# Run tests
yarn test
# Run tests and watch for file changes
yarn test:watch
Don't need tests?
- Run
yarn remove jest ts-jest @types/jest
- Remove the
test
directory andjest.config.js
- Change the
test
script inpackage.json
to executeyarn tsc:check
instead. - Remove the
test:watch
script inpackage.json
You can create a .env
file in the root of the directory. The variables will be automatically available in development when using yarn dev
. This uses the dotenv
package under the hood by running node -r dotenv/config
(see nodemon.json
).
This template comes with 2 actions pre-configured. There is a free tier to GitHub actions, but depending on the usage, you might be charged. To avoid this, update the spending limit of your GitHub account. More information: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/managing-your-spending-limit-for-github-actions
Every pull request automatically gets tested by running yarn test
. Results will be visible in the Actions tab in the repository and under the pull request.
Don't want to use the test workflow? Remove the file .github/workflows/test.yml
On every push to the branches main
and next
, the code will be tested using yarn test
and afterwards semantic-release
will be run.
semantic-release is a tool to fully automate version management and package publishing.
What this means is on every push this will:
- Analyze your commit history to find out whether this is a patch, minor or major (breaking) release. This uses the Angular commit message format, so you must author your commits in this format.
- Bump the version in your
package.json
- Generate a changelog which will be written to
CHANGELOG.md
- Create a git tag and a release in GitHub which includes the changelog.
- Notify every PR author if their changes are released.
When pushing to the next
branch, a pre-release is created.
Want to publish your package to npm automatically? Update the package.json
and configure @semantic-release/npm.
Because every commit will lead to a new release automatically, you need to work on the dev
branch and feature branches and only merge your work over to main when you want to draft a release.
See the semantic-release
website for additional help.
Don't want to use semantic-release? I recommend you to try it out, but I agree that it can be very challenging if you dont have any experience with it, to start writing commits in angular format and working with multiple branches. You can remove the release workflow by doing the following:
yarn remove semantic-release @types/semantic-release @semantic-release/changelog @semantic-release/git
- Remove the
release
section inpackage.json
- Remove the file
.github/workflows/release.yml
Renovate is pre-configured to keep dependencies pinned and up-to-date.
Renovate will make PRs against the dev
branch. This and more can be configured in .github/renovate.json
. You have to install Renovate in your GitHub repo for this to work.
Don't want to use Renovate? Remove the file .github/renovate.json
It is recommended that you always pin your dependencies and let Renovate author PRs to update your dependencies.
See https://docs.renovatebot.com/dependency-pinning/ for more information.
If you use Renovate, it is pre-configured to pin your dependencies and you can use the -E
flag of yarn
to pin dependencies during installation.
However if you are authoring a library to be used by others or dont want to use a tool like Renovate, it might be better to not pin your dependencies, but use version ranges.
Just leave out the -E
flag when installing dependencies. If you are using renovate, edit the .github/renovate.json
file and remove :pinVersions
in line 5.
There is a sample Dockerfile
which will produce a lightweight image of your application, which only includes production dependencies and code. It is based on alpine Linux.
# Build docker image
docker build -t myapplication .
This repository is meant to be a good starting point for Node.js applications written in TypeScript. It is very opinionated, but can save a lot of time. You can customize everything to your liking after using this template. You think there's something that could be changed which would help everybody? Feel free to open a pull requeqst!