As I already explained in my previous article, I finally ended up with a project setup of NPM, TypeScript, and Nest.js.

The Nest CLI provides you with great possibilities to quickly scaffold your new project and create boilerplate code. After selecting a package manager (one of npm, yarn, pnpm), the CLI generates a full-contained web application:

nest new nestjs-coreui-starter

will generate that structure for you:

That code contains one simple AppController, which gets an AppService injected - when you run npm run start:debug, you will see Hello World! printed as a response to http://localhost:3000.

Good to go for the start, but if you want to create a real web application, there is some stuff missing and in that blog post I'd like to guide you through my approach.

Editor Config

No matter if you are in a team or not. Before you start a project, agree on a configuration for your IDE Editor how to format your files. The open-source project EditorConfig provides a syntax that works fine across IDEs and programming languages.

I don't wanna get into the "2 vs 4 indent" or "tabs vs space"-flamewar. All is good as long as everyone on the project does the same.

In my case, the .editorconfig looks like this:

[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true

That file will later be picked up by our infrastructure to ensure that all files are formatted in the same way. You can already right away execute npm run format, and all your source files will be formatted accordingly.

I'd also recommend updating your package.json in the scripts tag to also format .jsonand.js files in the root directory:

"scripts": {
   "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\" \"*.json\" \"*.js\"",
}

Control dependencies

The Nest.js CLI generates a package.json which denotes dependencies like this:

  "dependencies": {
    "@nestjs/common": "^10.0.0",
    "@nestjs/core": "^10.0.0",
    "@nestjs/platform-express": "^10.0.0",
    "reflect-metadata": "^0.1.13",
    "rxjs": "^7.8.1"
  },

As I'm a Java guy, I asked myself what the ^ means, and thankfully we do have ChatGPT now that can help immediately.

In a package.json file, the ^ symbol preceding a version number indicates that npm (Node Package Manager) should install the specified package with a version that is compatible with the specified version, up to the next major version.

For example, if you specify "some-package": "^1.2.3", npm will install version 1.2.3 of "some-package" or the latest minor or patch version that is backward-compatible with 1.2.3. So, it might install versions like 1.2.4, 1.3.0, 1.4.0, etc., but it won't install version 2.0.0 or higher, as those might contain breaking changes.

This caret symbol is part of npm's semantic versioning (semver) scheme, which aims to provide a standardized way of declaring and managing dependencies in Node.js projects.

So I had a look in the package-lock.json and I found an entry like this:

"node_modules/@nestjs/common": {
   "version": "10.3.7",
   "resolved": "https://registry.npmjs.org/@nestjs/common/-/common-10.3.7.tgz",
   "integrity": "sha512-gKFtFzcJznrwsRYjtNZoPAvSOPYdNgxbTYoAyLTpoy393cIKgLmJTHu6ReH8/qIB9AaZLdGaFLkx98W/tFWFUw==",
   "dependencies": {
      "iterare": "1.2.1",
      "tslib": "2.6.2",
      "uid": "2.0.2"
   },
}

So the version ^10.0.0 in my package.json installed ^10.3.7. That also means that a subsequent call of npm install could install a new version of a dependency without any code change on my side.

To get reproducible builds on your CI server, you should therefore run npm ci instead of npm install, which will not install new dependencies but always take the ones from package-lock.json, but I still do have some bad feelings there.

Call me old-fashioned, but I want to have control over the exact version that is being installed, therefore I stripped all occurrences of ^ in my package.json. That requires a bit more manual work, but now dependency upgrades are a manual thing that gets into my daily routine when calling npm outdated.

If you are using Visual Studio Code, you get a nice popup over each dependency showing you the latest version:

So when you remove the ^, ensure that you replace the version number with the previously installed version.

Keep dependencies up-to-date

So let's ensure we have the latest version of all dependencies. I have seen so many projects in the past with really outdated and unsupported libraries that made it really hard to do any upgrades. If you work on that regularly, it's not a pain at all.

NPM provides a great command that tells you for which library there exists a newer version

npm outdated

Depending on the version of your Nest CLI you might get an output like this:

Package                           Current  Wanted  Latest  Location                                       Depended by
@typescript-eslint/eslint-plugin   6.21.0  6.21.0   7.6.0  node_modules/@typescript-eslint/eslint-plugin  nestjs-coreui-starter
@typescript-eslint/parser          6.21.0  6.21.0   7.6.0  node_modules/@typescript-eslint/parser         nestjs-coreui-starter
eslint                             8.57.0  8.57.0   9.0.0  node_modules/eslint                            nestjs-coreui-starter
reflect-metadata                   0.1.14  0.1.14   0.2.2  node_modules/reflect-metadata                  nestjs-coreui-starter

Update the versions in your package.json accordingly and run npm install, until the result of npm outdated is empty or there are any version upgrades that you don't want to or can't go.

So after doing all that, the dependencies and devDependencies section of my package.json looks like that (you can also explore the full git diff):

  "dependencies": {
    "@nestjs/common": "10.3.7",
    "@nestjs/core": "10.3.7",
    "@nestjs/platform-express": "10.3.7",
    "reflect-metadata": "0.2.2",
    "rxjs": "7.8.1"
  },
  "devDependencies": {
    "@nestjs/cli": "10.3.2",
    "@nestjs/schematics": "10.1.1",
    "@nestjs/testing": "10.3.7",
    "@types/express": "4.17.21",
    "@types/jest": "29.5.12",
    "@types/node": "20.12.7",
    "@types/supertest": "6.0.2",
    "@typescript-eslint/eslint-plugin": "7.6.0",
    "@typescript-eslint/parser": "7.6.0",
    "eslint": "8.57.0",
    "eslint-config-prettier": "9.1.0",
    "eslint-plugin-prettier": "5.1.3",
    "jest": "29.7.0",
    "prettier": "3.2.5",
    "source-map-support": "0.5.21",
    "supertest": "6.3.4",
    "ts-jest": "29.1.2",
    "ts-loader": "9.5.1",
    "ts-node": "10.9.2",
    "tsconfig-paths": "4.2.0",
    "typescript": "5.4.5"
  },

That way I immediately see my peers, and I don't need to crawl inside package-lock.json.

Linting

The Nest.js CLI provides you with initial support for linting your code with ESLint. That is a good starter, but the ruleset did not fulfill my needs, so I added some plugins and extends.

My old colleagues from Cloudflight are providing a great starting point with sample rules, and I also added another plugin to sort imports.

npm install --save-dev @cloudflight/eslint-plugin-node
npm install --save-dev eslint-plugin-simple-import-sort

And then adapt the plugins and extends section of your .eslintrc.js as follows:

  plugins: ['@typescript-eslint/eslint-plugin', 'simple-import-sort'],
  extends: [
    'plugin:@typescript-eslint/recommended',
    'plugin:prettier/recommended',
    'plugin:@cloudflight/node/recommended',
    'plugin:import/typescript'
  ],

If you now run npm run lint again, you will get a lot of errors. I have decided to disable some of those rules, let's go through them step by step:

C:\github\klu2\src\nestjs-coreui-starter\src\app.controller.spec.ts
  1:37  error  "@nestjs/testing" is not published      node/no-unpublished-import

This rule is complaining that we are importing @nestjs/testing here but don't publish it. True, because this is a devDependency and we only need it in Spec-Files. The best way I found is to disable this rule in all *.spec.ts files inside .eslintrc.js:

 overrides: [{
     files: ['**/*.spec.ts'],
     rules: {
         "node/no-unpublished-import": 'off'
     },
 }],

Then there are a couple of rules that don't make sense in Nest.js projects like @typescript-eslint/no-extraneous-class (it fails for each class without members, but this is how Nest.js modules are designed) and also some that I believe do make code unnecessarily bloated (like no-magic-numbers or @typescript-eslint/explicit-member-accessibility), so I deactivated those.

Run npm run lint again and you will find some more errors:

C:\github\klu2\src\nestjs-coreui-starter\src\app.controller.spec.ts
  0:1  error  This rule requires the `strictNullChecks` compiler option to be turned on to function correctly  @typescript-eslint/strict-boolean-expressions        
  0:1  error  This rule requires the `strictNullChecks` compiler option to be turned on to function correctly  @typescript-eslint/prefer-nullish-coalescing

We will temporarily turn off those rules as well now so that we can commit our changes, but we will fix that in a minute.

Adapting TypeScript configuration

The default tsconfig.json that comes with the Nest.js CLI is quite progressive in some areas, meaning it allows some code flaws that could make your code end up in serious crap. I used the default configuration for some weeks and had to tidy up the code and found a lot of bugs that could have been detected with a more strict configuration.

Specifically, the default configuration switches off the following checks:

 "strictNullChecks": false,
 "noImplicitAny": false,
 "strictBindCallApply": false,
 "forceConsistentCasingInFileNames": false,
 "noFallthroughCasesInSwitch": false

I'd recommend switching them all on from the very beginning. We may argue about noImplicitAny, because that could come in handy sometimes, but I don't see any reasons, why to switch off the other checks. They really help you a lot during development time, avoiding bugs from slipping into production. You can review the according commit here.

Specify Node version

The last thing you should do right from the start is to configure the minimum Node.js version that is required to run your application. This is important if your codebase is relying on native functionality that entered Node.js just recently, like the native fetch API which became stable in Node 21.

You can easily specify that in your package.json by adding the following block:

"engines": {
    "node": ">=21.0.0"
},

Code

If you are interested in the code, you can clone the whole repository from https://github.com/klu2/nestjs-coreui-starter. Please note that this repository will change over time as I will be using it for subsequent blog postings.

Summary

We are good to go now, we do have a clean project that goes beyond the default scaffold from the Nest.js CLI, including:

• EditorConfig

• Advanced Linting

• Clean dependency management

The next blog posts will then focus on a clean module setup including the view layer.

Disclaimer

As mentioned some times already, I'm an absolute beginner in the Node.js ecosystem. I gave my best to apply my 2 decades of Java knowledge to this new world, but for sure there are also more elegant ways.

If you have ideas on how to improve that setup, please send me a comment here or do a pull request on GitHub.

I am happy for every constructive input!

Almost everything is different here for me and that personal change also came along with a paradigm shift with regards to technology and software development. In this blog series, I want to take you a bit on my journey so far, sharing my technical experiences:

Where I'm coming from...

For more than 15 years, I led awesome teams at Cloudflight, where we leveraged the robustness of Spring, the elegance of Kotlin, and the reliability of the JVM to develop complex, scalable applications. Our processes were well-established, we had the best developers both on frontend and backend, and our portfolio was supported by a skilled ensemble of Requirements Engineers, UI/UX Designers, and Site Reliability Engineers. We operated on Kubernetes, ensuring high availability and seamless scalability for our products both on hyperscalers (Azure, AWS, GCP) and on-premise solutions like OpenShift.

While that is all still true for Cloudflight, I started again from scratch.

Arriving at greeny+, I was suddenly alone in that regard. We do have fantastic people for lots of other topics around product design, plant growth, marketing and sales, but I am (at least at the time of writing) the only IT guy. No one setting up server infrastructure, no one taking care of my deployment pipeline, no requirement engineers that build up and develop a clear backlog and talk to customers, no UX designers with all those so important skills to create the best possible user interfaces, no frontend developers with deep knowledge in HTML/SCSS/JS.

Just me.

And, as in most other startups as well: time and money are somehow limited.

Additionally, not to forget, there has not been too much practice time in software development in the last few years for me...

From custom to standard software

Still, when I joined greeny+ beginning of that year, I didn't start on empty ground. The team - also with some external help - had made a lot of valuable contributions already: HubSpot was being used as CRM and our new web page based on Shopify was about to go live. In between, we were rolling out UpPromote as affiliate solution.

I was trained for years to design tailor-made software systems that outperform standard solutions (but also cost a bunch of money upfront), so I had to change perspective and evaluate those existing tools, trying to get the maximum out of them.

So I looked through Shopify's backend and found out that it had adapted to the headless e-commerce hype which advocates to separate the presentation layer from its core logic. In Shopify, you don't have the flexibility like with Kontent.ai, Commercetools, Strapi or Medusa.js, but it's good enough to go for the start. We could customize the shop to our needs very quickly, integrating payment gateways thanks to Shopify Payments as well as interactive forms (like newsletter registration) with HubSpot, no blockers here.

HubSpot really positively surprised me when it comes to adaptability, it gives you an incredible amount of customization options, including a very mature and well-documented API and a built-in workflow engine.

Especially the latter raised my attention, it gives you a great mix of a Low/No-Code graphical editor along with the possibility to create custom code blocks. In the following screenshot you can see our workflow which connects new customers with the respective affiliate based on UTM parameters:

That works great already, that way we could connect HubSpot with UpPromote. Custom code inside HubSpot can be written in either Python or Node.js. I chose the latter, as JavaScript is much more familiar to a Java guy like myself.

And those few lines of JavaScript were actually the entrance to my new experience with Node.js.

Our challenges

Quite quickly it was clear, that our tooling landscape could not fulfill all of our needs. Just to give you a few examples:

• The official HubSpot integration with Shopify has some quite serious limitations in terms of privacy, i.e. we would have not been able to reduce the visibility of incoming orders in Shopify to only the affected salespeople in HubSpot.

• UpPromote cannot calculate commission fees fully as per our ruleset and also cannot generate invoices that fulfill our needs tax-wise.

• UpPromote only gives limited possibilities to provide affiliates with personally branded sales kits. We used Spreadly for that in the past, but the process of creating such digital business cards was manual, costly, and error-prone. We needed a solution for scale here.

So we knew we needed something dedicated for us. Time for custom software, again.

First choice: JVM again

As mentioned above, I did not have much time to bridge the gaps between Shopify, UpPromote and HubSpot, so my intuitive first choice was again my well-known JVM-stack with Spring Boot, Kotlin and Thymeleaf (I'm a lousy frontend developer, so I tried to avoid things like Angular, Vue.js or React).

But then some questions came up:

• How to develop code? After working with Intellij IDEA for 10 years, I gave VS.code a chance end of December. Very lightweight, good support for Python and Javascript, but JVM/Gradle integration has some serious flaws. So again purchase an Intellij license?

• How to connect to our three systems? There are REST APIs and partly OpenAPI specifications for HubSpot, Shopify and UpPromote, but no ready-to-use client libraries for the JVM. I could of course generate my own Kotlin clients just like we did in the past with other systems, but would again go my own way there.

• Where to finally run the code? Kubernetes and all kinds of Hyperscalers would have been an overkill for what I needed (actually one web server and a relational database). Of course, there are a couple of hosters out there that offer lightweight JVM hosting without the complexity of K8S (like Cloudfoundry or Platform.sh), although they are more costly than platforms like Vercel.

I could have done that all and for sure it would have worked well enough, but as there was so much change already, I thought:

Isn't that a good occasion to give Node.js a try?

I could reuse Javascript code from my HubSpot workflows as well then, and also would finally learn something new after so many years of Spring. If I would fail, I'd still have a plan B with good old Spring Boot.

So I gave myself 2 days...

My first Node.js application

If you google "web application node.js", you very quickly end up at Express.js. I went through some tutorials, and the Hello World is really straightforward (just as in any framework, btw...):

const express = require('express')
const app = express()
const port = 3000

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})

I went on with more advanced examples, started to integrate the APIs of Shopify and HubSpot and showed the combined data in some really ugly HTML.

That was running within a few hours, so the next step was to get familiar with hosting.

Deployment to render.com

I knew render.com already from my OpenSource activities on GitHub, and as they offer a free plan for individuals, that was my first choice.

Just 15 minutes later, after pushing my prototype to GitHub, my application was running on render.com. Not only that, render.com offered me a dashboard including a deployment pipeline and automatic deployment after code changes on GitHub, log console view, the possibility to maintain my own production environment and so much more. I have huge customization possibilities there (i.e. which git branch to watch on, which npm scripts to run and so much more), the admin dashboard is clean and easy to understand.

I literally had to do nothing. It was working within some minutes. Really awesome, especially as I still had the much more complex Microsoft Azure Portal in mind.

Meanwhile, I am also running a Postgres database (including automatic backup) and a Redis cache as session store on render.com, also setting that up and integrating it was just a matter of a few clicks.

From JavaScript to TypeScript

After writing some more JavaScript files and letting my codebase grow, my headache grew and I remembered again why I like statically typed languages so much.

The logical solution was Typescript, also something I've never set up before, but thanks to Co-Pilot that worked quickly as well. I migrated all of my code, adjusted my NPM scripts accordingly, struggled a bit with the correct tsconfig.json (more on that later), and finally deployed my app again.

Good, typesafe now.

My big recommendation: If you're doing Node.js and take it seriously, start with TypeScript from day 1. Also lint your code strongly from day 1. I will give some hints on that later as well.

From Express.js to Nest.js

If you're coming from Spring and write your first Express.js application, you will miss one fundamental concept quite early: Dependency Injection.

If Express.js is the equivalent of Apache Tomcat, then Nest.js gives you what you know from Spring.

So, let's take the Hello World from above, with Nest.js you would write:

import { Controller, Get } from '@nestjs/common';

@Controller()
export class HelloController {
  @Get()
  getHello(): string {
    return 'Hello World!';
  }
}

A bit more of code initially, but especially if you're coming from Spring, you'll be familiar with that syntax immediately. You can inject your services and make your components much more testable.

Additionally, Nest.js offers really great documentation, check it out directly at the source, there is no need to copy code samples over here.

That was enough for me to proceed that path with Node.js. There were some more challenges like database connection or the view layer, but I could find decent solutions for all of that, and so I decided to stick with that stack.

Conclusion

I didn't regret my technological choice. Just two months later, we now have a web application that serves as a one-stop shop for more than 300 sales partners of greeny+, offering:

• A responsive WebUI based on CoreUI, showing customers, orders and commission fees of our sales partners.

• Full integration and synchronization of data between Shopify, UpPromote and HubSpot, 100% as per our needs, including an admin user interface to validate data synchronization.

• Custom-built PDF invoice generation for all affiliates including mail delivery.

• Automatically generated digital business cards for all affiliates including personal branded marketing PDFs. If you're curious, look at mine (German only).

And there are many more ideas to be implemented...

Disclaimer

Important to say: I'm sure I could not have done all that without generative AI in such a short amount of time. GitHub Co-Pilot and ChatGPT really helped me a lot. You cannot take everything for granted what those tools tell you, but if you use them wisely, they give you real super-power.

That mix of AI, lightweight frameworks, easy-to-use SaaS solutions, some years of experience how to build software, and last but not least: the urge to learn new things and never settle, made all that possible.

Still, you can't compare that solution with something you would get from a whole team with experts in all areas (especially on the UI side...). Right now, I also do have my doubts how solid that architecture is on the long run, especially if the code base grows further and multiple people would work on it in parallel. I also don't have any results yet how the system behaves under high load - I didn't optimize it in that direction yet. To be fair, I also bypassed some quailty gates (i.e. there could be much more unit tests), and probably I will need to do some refactorings in near future.

It's still good enough for what we require right now.

Next Steps

This was only the first part of a series of blog entries, digging more into each topic from the technical side, also offering code samples for the project setup, my package.json with support for unit testing with Jest including code coverage, SCSS, webpack, and the integration with all 3rd party systems.

By the way: Shopify, UpPromote, and HubSpot were not the only external services that we integrated. I will give you more insights on that as well.

If you're interested, follow me here on HashNode and stay tuned!