To build and run this app locally you will need a few things:
- Install Node.js
- Install Postgresql
- Install VS Code
or
- Docker
- Clone the repository
git clone https://github.com/kir-dev/tanulo-next.git <project_name>
- Install dependencies
cd <project_name>
yarn install
- Configure your postgresql server
sudo su postgres
psql -c 'create user "tanulo" with superuser password '\''tanulo'\'';'
psql -c 'create database "tanulo";'
-
Set up a
.env
file based on.env.example
with real values. -
Run migrations
yarn run migrate
- Optional: Set up seed in database
yarn run seed
- Build and run the project
yarn run build
yarn start
Finally, navigate to http://localhost:3000
and you should see the site being served and rendered locally!
Run yarn watch
to run reload the server on file changes. Note: this deletes the session, so you'll have to login again.
- Set up a
.env
file based on.env.example
with real values.
docker-compose build
docker-compose up
While the containers are running, execute the following:
docker-compose run tanulo bash -c "yarn run migrate"
Debugging TypeScript is exactly like debugging JavaScript with one caveat, you need source maps.
Source maps allow you to drop break points in your TypeScript source code and have that break point be hit by the JavaScript that is being executed at runtime.
Note! - Source maps aren't specific to TypeScript. Anytime JavaScript is transformed (transpiled, compiled, optimized, minified, etc) you need source maps so that the code that is executed at runtime can be mapped back to the source that generated it.
The best part of source maps is when configured correctly, you don't even know they exist! So let's take a look at how we do that in this project.
First you need to make sure your tsconfig.json
has source map generation enabled:
"compilerOptions" {
"sourceMap": true
}
With this option enabled, next to every .js
file that the TypeScript compiler outputs there will be a .map.js
file as well.
This .map.js
file provides the information necessary to map back to the source .ts
file while debugging.
Note! - It is also possible to generate "inline" source maps using
"inlineSourceMap": true
. This is more common when writing client side code because some bundlers need inline source maps to preserve the mapping through the bundle. Because we are writing Node.js code, we don't have to worry about this.
Debugging is one of the places where VS Code really shines over other editors. Node.js debugging in VS Code is easy to setup and even easier to use. This project comes pre-configured with everything you need to get started.
When you hit F5
in VS Code, it looks for a top level .vscode
folder with a launch.json
file.
In this file, you can tell VS Code exactly what you want to do:
{
"type": "node",
"request": "attach",
"name": "Attach by Process ID",
"processId": "${command:PickProcess}",
"protocol": "inspector"
}
This is mostly identical to the "Node.js: Attach by Process ID" template with one minor change.
We added "protocol": "inspector"
which tells VS Code that we're using the latest version of Node which uses a new debug protocol.
With this file in place, you can hit F5
to attach a debugger.
You will probably have multiple node processes running, so you need to find the one that shows node dist/server.js
.
Now just set your breakpoints and go!
For this project, we use Cypress for end-to-end testing.
Running yarn run test
will open the Cypress GUI. From there you can run each test individually or all of them at once. These tests will also run through GitHub Actions when you push changes to this repository.
ESLint is a code linter which mainly helps catch quickly minor code quality and style issues.
Like most linters, ESLint has a wide set of configurable rules as well as support for custom rule sets.
All rules are configured through .eslintrc
configuration file.
In this project, we are using a fairly basic set of rules with no additional custom rules.
Like the rest of our build steps, we use yarn scripts to invoke ESLint. To run ESLint you can call the main build script or just the ESLint task.
yarn run build // runs full build including ESLint
yarn run lint // runs only ESLint
Notice that ESLint is not a part of the main watch task.
If you are interested in seeing ESLint feedback as soon as possible, I strongly recommend the VS Code ESLint extension.
Copyright (c) Kir-Dev. Licensed under the MIT License.