Example base for typescript projects
Get the latest version of node from the official website or using nvm Nvm approach is preferred.
Run npm install or yarn from rootpath of the project.
Before running the app, make sure you have postgresql installed and a db created, to create it run the following steps inside a psql terminal:
CREATE DATABASE db_project_name;\c db_project_name;CREATE ROLE "project_name" LOGIN CREATEDB PASSWORD 'project_name';
Then, set in .env file following variables:
DB_HOST="localhost"
DB_PORT=5432
DB_USERNAME="project_name"
DB_PASSWORD="project_name"
DB_NAME="db_project_name"
DB_NAME_DEV="db_project_name_dev"
DB_NAME_TEST="db_project_name_test"
To create a migration from changes in models, run npm run migrations-generate <migration_name>
Migrations should be generated after each change you made to your models.
To create a migration manually, run npm run migrations-create <migration_name>.
To run migrations, execute npm run migrations.
Now, to start your app run npm start in the rootpath of the project. Then access your app at localhost:port, where the port was logged into the console at startup.
By default, the environment will be development, but you can change it easily using the NODE_ENV environmental variable.
Dotenv is used for managing environment variables. They are stored in the /.env file. Take into account that the variables defined in the bashrc are not overrided.
The environment variables should be added to the .env file in the form of NAME=VALUE, as the following example:
DB_USERNAME="root"
DB_PASS="superpass"
DB_PASSWORD="superpass"
PORT=8081
CLIENTS_API="http://api.clients.example.org/"
Remember not to push nor commit the .env file.
In the next few sections I will call out everything that changes when adding TypeScript to an Express project. Note that all of this has already been setup for this project, but feel free to use this as a reference for converting other Node.js projects to TypeScript.
TypeScript is a superset of JavaScript, thus we should be able to use the same packages for both. Some of them are already written in TypeScript and expose their types for us to use.
When the package you want to implement is not written in TypeScript, you can look up for it on DefinitelyTyped and install it using: npm install --save-dev @types/your-package.
Note! Use flag
--save-dev(or-D) in order to save.d.tsas dev dependencies. They are only used at compile time.
If your package is not defined on DefinitelyTyped neither, you will have to create your own .d.ts file.
Compiler looks for type definition files in node_modules/@types by default. But we will want to help it find our own .d.ts files, in order to accomplish this we have to configure path mapping in our tsconfig.json.
In the tsconfig.json for this project you'll see the following:
"paths": {
"*": [
"node_modules/@types/*",
"types/*"
]
},This instructs TypeScript compiler to first looks in node_modules/@types and then, when it doesn't find one, look on our own .d.ts files located on the folder ./types.
Unless you are familiar with .d.ts files, it is recommended to use a tool to generate .d.ts files for this libraries. dts-gen is a tool that generates TypeScript definition files (.d.ts) from any JavaScript object.
This trade-off comes with a price -- you'll see a lot of anys in function parameters and return types. You may also see properties that are not intended for public use. dts-gen is meant to be a starting point for writing a high-quality definition file.
To log useful information of your program to the console you just need to import the logger located at app/logger. There are two possible types of logging: info and error. You should use them depending on the type of message you want to show.
Here is an example snippet:
const logger = require('/app/logger');
if (error) {
logger.error('There is an error');
} else {
logger.info('There is no error');
}To run your tests you first need to config your testing database by setting the env var DB_NAME_TEST. as explained
before in Database configuration. Also you need to run the migrations in this exclusive
testing database each time you have new ones, you can do this by running the command npm run migrations-test.
Once you have all the above done you can run your tests with the following command: npm test. For more information refeer to the documentation of Mocha and Chai.
In order to debug our Node.js application, we enable 'sourceMap' in tsconfig.json, this compiler option generates corresponding .map files from original Javascipt counterpart. This change is mandatory to attach a debugger, otherwise it wouldn't be able to match transpiled files with their originals.
In VSCode, you will need to add an ./.vscode/launch.json file in order to launch the debugger. You can use the following:
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/server.ts",
"preLaunchTask": "tsc: build - tsconfig.json",
"restart": true,
"outFiles": [
"${workspaceFolder}/dist/**/*.js"
]
}
]
}We can use a node console with npm run console. There your service objects are exposed as servicename + "Service". Let's suppose that we have a service users which has a function getAll. In your console you can call usersService.getAll() and see the result. Note that this works also with functions that return promises! To exit the console use .exit.
Documentation will be served at /docs. Remember using dictum.js package to automatically generate documentation for your endpoints. Check this link for further details.
Pushing the desired branch to heroku should be enough. For more information check: https://devcenter.heroku.com/articles/getting-started-with-nodejs#define-a-procfile.