An API Boilerplate project built with Node.js and Typescript.
⏱Runtime: Node.js 🖥API Framework: Fastify 🔏Type System: TypeScript 🧪Test Runner: Jest 👕Linter: ESLint 📦Continuous Integration: Azure DevOps
🍴Fork the repository 👯♀️Clone it to your computer 🏃♀️Run npm run install && npm run dev 📝Edit any of the files in src/ 👀Watch as the app magically rebuilds and relaunches itself
The following npm scripts can be run using
npm run <script>. This project relies on
rimraf utilities in order to support cross-platform opening and deleting files.
build- build the TypeScript files and output to
build:watch- automatically rebuild files if changes are detected in
clean- recursively delete the
clean:build- recursively delete the
clean:coverage- recursively delete the
coverage- run the test suite and generate code coverage reports
coverage:open- run npm run coverage then open the results in a browser
dev- concurrently run
lint- run the linter configured by TSLint on the
start- run the app from
lib/. Make sure to use npm run build first!
start:watch- relaunch the server if new changes are detected in
test- run unit tests defined in the
test:ci- run unit tests and generate necessary files for CI integration
Command Line Arguments & Environment Variables
Matterhorn implements example usage of both command line arguments and environment variables. It uses
yargs-parser to manage command line arguments. Command line arguments are passed in through the start command:
node lib/index.js <command line arguments>. The
--log argument has been enabled as an example. Running
npm run start starts up the project without any command line arguments. This command is intended to be used in production, so logging is disabled by default (i.e. we don't pass the
--log argument). If you are using this command to test your code locally and want to see the logging output, then run
npm run start -- --log. This passes the command line argument through npm and into the aliased command.
Environment variables work in a similar way to command line arguments. They can be set in multiple ways depending on the terminal and operating system you are using. In a bash terminal you can specify environment variables as you use any of the above mentioned scripts by prepending the assignment to the command. For example, this project has the PORT environment variable enabled. In a bash terminal run
PORT=8080 npm run start to run the API on port 8080.
Open an issue if you'd like to report a bug or a feature. Make sure to write a detailed description and indicate if you will or will not be resolving the issue yourself.
If you are interested in contributing make sure to follow these practices:
- Prepend branches with
docs/depending on the change being made
- NPM commands
buildrun without failing.
- If you are solving an open issue, reference it in the Pull Request description using
Ref #<issue number>.
Matterhorn has a unique Jest set up. Under the
jest/ directory there are three configuration files
test.config.json. Each configuration file maps to a specific jest experience.
npm run test
Runs jest with the
test.config.json configuration. This configuration does not collect any code coverage.
npm run coverage
Runs jest with the
coverage.config.json configuration. It runs the same test suite as
npm run test and collects coverage from all files under the
src/ directory. It outputs the coverage information in the following formats:
html. It does not rely on any external reporter dependencies.
npm run test:ci
Runs jest with the
ci.config.json configuration. It runs the same test suite as
npm run test and collects coverage similar to the
npm run coverage command, but utilizes jest's built in
ci caching functionality. Additionally, it outputs the coverage in the following formats:
cobertura. It utilizes
jest-junit reporter to generate compatible junit xml files for Azure DevOps test reporting, and the
cobertura format for the code coverage reporting.