heusalagroup/create-backend

NPM package creation template module for our TypeScript REST backends

Join our Discord to discuss our software!

@heusalagroup/create-backend

A command-line tool to easily create NodeJS REST backend projects with TypeScript in the style inspired by Java Spring Boot. For more information on our style of NodeJS backends, check out HG.fi.

Usage

To create a minimal backend project, run either of the following commands:

npm init @heusalagroup/backend ./foo-backend

...or..

npm install -g @heusalagroup/create-backend
create-backend ./foo-backend

This command also accepts any argument from the npm init command. For example, you can call it with --yes to answer "yes" to every question:

create-backend ./foo-backend --yes

To increase the log level for debugging, set the LOG_LEVEL environment variable:

LOG_LEVEL=DEBUG npm init @heusalagroup/backend ./foo-backend

Development

Fetching source code

To get started with development, clone the repository locally and install the git submodules:

git clone [email protected]:heusalagroup/create-backend.git create-backend
cd create-backend
git submodule update --init --recursive

Listing state of git modules

To see the state of the git modules, run this command:

./scripts/get-all-branches.sh

If you see states like this, run the set-branch-main.sh script:

$ ./scripts/get-all-branches.sh 
main    .
(HEAD detached at 34566e9)      src/fi/hg/core
(HEAD detached at 898988b)      src/fi/hg/create

When everything is correct, you should see this:

$ ./scripts/get-all-branches.sh 
main    .
main    src/fi/hg/core
main    src/fi/hg/create

Unless you want to use a different branch, of course.

Changing all git modules to the main branch

To switch all git modules to main, run this script:

./scripts/set-branch-main.sh

Updating git modules to the latest version

To update all git modules to the latest version, run this script:

./scripts/pull-all.sh

Building the project

This script will build a standalone version of the project and output it to ./dist/create-backend.js. It will be zero dep after that, meaning that only Node.js is required to run it, along with ./create.config.json and the files in ./templates.

npm run build

Testing locally

You can install your own locally changed version globally:

npm install -g .

Then use it to kickstart a backend project:

create-backend ./foo-backend

Development with GitHub Using SSH

To use SSH when working with submodules in this repository, you will need to configure your Git settings as follows:

git config --global url."[email protected]:heusalagroup/".insteadOf "https://github.com/heusalagroup/"

This configuration is necessary because the repository uses HTTPS links for read-only access. However, you may prefer to use SSH when pushing and pulling changes.

License

Copyright (c) 2022 Heusala Group. All rights reserved. Licensed under the MIT License (the "License").

create-backend's Issues

Multiple replacement strings not replaced

If a file, like README, contains multiple replacement strings, only first is changed.

Error: Could not resolve './fi/hg/core/RequestServer'

[!] Error: Could not resolve './fi/hg/core/RequestServer' from src/main.ts
Error: Could not resolve './fi/hg/core/RequestServer' from src/main.ts
    at error (/Users/jhh/tmp/foo-backend/node_modules/rollup/dist/shared/rollup.js:198:30)
    at ModuleLoader.handleResolveId (/Users/jhh/tmp/foo-backend/node_modules/rollup/dist/shared/rollup.js:22287:24)
    at /Users/jhh/tmp/foo-backend/node_modules/rollup/dist/shared/rollup.js:22250:26

Change controller to use standard class format instead of static classes

Backend takes over 10 seconds to shutdown

This is because of incorrect CMD format in Dockerfile.

See heusalagroup/fi.hg.core#78

Fix here: https://github.com/heusalagroup/create-backend/blob/main/templates/Dockerfile

RollupError: Node tried to load your configuration file as CommonJS even though it is likely an ES module.

(node:61485) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.
(Use `node --trace-warnings ...` to show where the warning was created)
[!] RollupError: Node tried to load your configuration file as CommonJS even though it is likely an ES module. To resolve this, change the extension of your configuration to ".mjs", set "type": "module" in your package.json file or pass the "--bundleConfigAsCjs" flag.

Original error: Cannot use import statement outside a module
https://rollupjs.org/guide/en/#--bundleconfigascjs

It seems that the installer is selecting rollup from version 3, when we currently relay on version 2.79.1.

Workaround for this is to change the rollup to use version 2.79.1 or newer before version 3.

Rollup dependency resolution error on installation

The following dependency resolution error was encountered while trying to checkout and install the backend and subsequent calls to npm run build fail due to rollup not being installed:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: @rollup/[email protected]
npm ERR! Found: [email protected]
npm ERR! node_modules/rollup
npm ERR!   rollup@"*" from the root project
npm ERR!   peerOptional rollup@"^1.20.0||^2.0.0||^3.0.0" from @rollup/[email protected]
npm ERR!   node_modules/@rollup/plugin-babel
npm ERR!     @rollup/plugin-babel@"*" from the root project
npm ERR!   5 more (@rollup/plugin-inject, @rollup/plugin-json, ...)
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peerOptional rollup@"^2.68.0||^3.0.0" from @rollup/[email protected]
npm ERR! node_modules/@rollup/plugin-commonjs
npm ERR!   @rollup/plugin-commonjs@"*" from the root project
npm ERR!
npm ERR! Conflicting peer dependency: [email protected]
npm ERR! node_modules/rollup
npm ERR!   peerOptional rollup@"^2.68.0||^3.0.0" from @rollup/[email protected]
npm ERR!   node_modules/@rollup/plugin-commonjs
npm ERR!     @rollup/plugin-commonjs@"*" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

Environment:

OS: MacOS Monterey
Node: 18.9.0
NPM: 9.2.0

Change to use Interface + Implementation format

Files should follow this format:

• BackendController -- The interface
• BackendControllerImpl -- The implementation

Depends on: #8

TypeError: n.replaceAll is not a function

TypeError: n.replaceAll is not a function
    at /Users/jhh/git/heusalagroup/create-backend/dist/create-backend.js:456:100
    at Array.forEach (<anonymous>)
    at Function.copyTextFileWithReplacements (/Users/jhh/git/heusalagroup/create-backend/dist/create-backend.js:456:73)
    at Function.copyTextFileWithReplacementsIfMissing (/Users/jhh/git/heusalagroup/create-backend/dist/create-backend.js:458:39)
    at /Users/jhh/git/heusalagroup/create-backend/dist/create-backend.js:917:64
    at Array.forEach (<anonymous>)
    at /Users/jhh/git/heusalagroup/create-backend/dist/create-backend.js:917:24
    at processTicksAndRejections (internal/process/task_queues.js:95:5)

$ node --version
v14.20.1

Fix to use HG ErrorDTO instead of inline error type

{readonly error: string} -> ErrorDTO

Check for newer dependencies

Project warns about vulnerabilities.

2 high severity vulnerabilities

1. We relay on some quite old tools (like uglifyjs), since newer ones didn't do all the tricks for transpiling and minimizing the source code. Newer tools should support for example removing blocks like if (false) {{ ... }}.

"hangovergames" as an organization name

Generated project will have hangovergames in constants/backend.ts which is our Game Company name. Should be "heusalagroup".