@anthonylzq/simba.js

Set up a modern backend app by running one command. This project has the goal to create a complete setup for a backend application using TypeScript and Express or Fastify. It will create many files that are usually created manually. Think about Simba.js like a CRA, but for backend development. Check the project structure for more information.

Installation

This package is meant to be installed globally in your computer by using:

npm i -g @anthonylzq/simba.js

Usage

As developer you have two main options to create your new project, one is by running:

simba -q

By doing this your prompt will ask you the following questions:

• Project name?, at least one character must be provided.
• Project description:, at least one character must be provided.
• Select your package manager, npm, yarn and pnpm are available.
• Author:, at least one character must be provided.
• Email:, a correct email address must be provided.
• Project version: the initial version of the project, 0.1.0 as default.
• License:, the license you have chosen for the project.
• License year (current year):, the year where your license starts, current year as default.
• Would you want to have a basic GitHub Action for the suit of tests and linting? [y/n]:.
• Express or Fastify?, only one of them is valid (lowercase).
• Will this project use GraphQL? [y/n]:, yes or no question, only y or n is accepted. This is not case sensitive.
• Which database do you want to use?, MongoDB, PostgreSQL, MySQL, MariaDB, Sqlite and Microsoft SQL Server are available.

The second option you have is by passing flags in one single command. If you need help, please run:

simba -h

This will generate the following output:

Simba.js, the easiest way to create your TypeScript APIs

Usage:
"simba [options]" or only "simba -q" if you want to be asked for the options one
by one.

Options:
  -N, --projectName              Project name.
  -D, --projectDescription       Project description.
  -a, --author                   Author of the project.
  -e, --email                    Email of the author.
  -l, --license                  Type of license for the project, it can be one
                                 of: MIT, Apache 2.0, MPL 2.0, LGPL 3.0, GPL 3.0
                                 and AGPL 3.0, in lowercase without its version.
                                                         [default: "unlicensed"]
  -v, --version                  Project initial version.     [default: "0.1.0"]
  -y, --licenseYear              Year when the license starts. [default: "2023"]
  -m, --manager                  Which package manager you want to use,
                                 available package managers are: npm, yarn and
                                 pnpm.                         [default: "pnpm"]
  -f, --mainFile                 Main file of the project.
                                                       [default: "src/index.ts"]
  -q, --questions                Whether or not you want to be asked to answer
                                 the questions related to the project one by
                                 one.                 [boolean] [default: false]
  -F, --fastify                  Whether or not you want to use Fastify for your
                                 project.             [boolean] [default: false]
  -g, --graphql                  Whether or not you want to use GraphQL for your
                                 project.             [boolean] [default: false]
      --ghat, --gh-action-tests  Whether or not you want to have a GitHub Action
                                 with a CI for your tests and linting. If this
                                 option is set to true, the tests flag must be
                                 set to true.                   [default: false]
  -d, --database                 Which database you want to use, available
                                 databases are: MongoDB (mongo), PostgreSQL
                                 (postgres), MySQL (mysql), MariaDB (mariadb),
                                 Sqlite (sqlite) and Microsoft SQL Server
                                 (sqlServer).                 [default: "mongo"]
  -h, --help                     Show help                             [boolean]

Examples:
  simba -N 'Project Name' -D 'Project description' -a Anthony -e
  [e-mail] -l mit -F -t -d mongo --ghat

Developed by AnthonyLzq

Examples

Let's suppose you want to build a project that will be deployed to Heroku, so should run:

simba -N myProject -D 'This is a test' -l mit -a myName -e [e-mail] -H

Here we are specifying that we want to create a new project called myProject using the MIT license, my name and my email are respectively: myName and [e-mail] and I want to use heroku to deploy this server.

As default, pnpm is selected as package manager, but if you don't want to use it, you can pass the flag -m or --manager as follows:

simba -N myProject -D 'This is a test' -l mit -a myName -e [e-mail] -H -m yarn

What if I want to use Fastify instead Express? Well, you only have to pass the -F flag:

simba -N myProject -D 'This is a test' -l mit -a myName -e [e-mail] -H -F

If I want to use a relational database instead MongoDB? Well, you only have to pass the -d flag:

simba -N myProject -D 'This is a test' -l mit -a myName -e [e-mail] -H -F -d postgres

The available databases are:

• MongoDB (mongo)
• PostgreSQL (postgres)
• MySQL (mysql)
• MariaDB (mariadb)
• Sqlite (sqlite)
• Microsoft SQL Server (sqlServer).

And how can I use GraphQL? Well, you only have to pass the -g flag:

simba -N myProject -D 'This is a test' -l mit -a myName -e [e-mail] -H -F -g

Finally, you may not want to use a license or one of the available licenses, don't worry, just don't pass the flag -l neither --license as follows:

simba -N myProject -D 'This is a test' -a myName -e [e-mail] -H

Project structure

If you want to check the content of the files, please check the example folder, there you will an example for both, Express and Fastify (REST and GraphQL versions). Regardless of the option chosen, a new folder will be generated with the name of the project.

Also, if you are interested in the folder structure of each case, please take a look at:

• Express
• Express-GraphQL
• Express-Mongo
• Express-Mongo-GraphQL
• Fastify
• Fastify-GraphQL
• Fastify-Mongo
• Fastify-Mongo-GraphQL

Some considerations

• You are able to run a server that has one main route, home (/), user (api/user or api/user/:id) and docs (api/docs), in case you are not using GraphQL.

• In case you are using GraphQL, there are 3 mutations (store, update, and deleteById) and 1 query available (getById), you can find them in the playground under the route /api.

• To connect your server with your database, you need to provide your database url in the .env, except if you choose sqlite. By default, Simba will try to connect to a local database. The content of the .env file is:

  DATABASE_URL = mongodb://mongo:mongo@mongo:27017/${projectName} # in case you choose mongo
  # or
  DATABASE_URL = postgres://postgres:postgres@postgres:5432/${projectName} # in case you choose postgres

  Where ${projectName} will be replaced by the name of the project you provided in lowercase.

• Once you have done that, now you can perform the following HTTP REQUEST: GET, POST, PATCH and DELETE.

• In order to use global variables, just add the one you need in the src/@types/index.d.ts file, and add a new var with its type to the global interface, as follows:

  // src/@types/index.d.ts
  
  // Some code...
  declare global {
    var globalStringVariable: string
    // Some more code...
  }
  // Some more code...
  
  // another file
  global.globalStringVariable = 'Hi mom, I am global'
  console.log({ globalStringVariable })

• The provided project structure is inspired in my personal experience as Node.js developer and the Nest framework. It follows a layered architecture:

  1. Presentation layer (network layer): it is represented by the network and schemas folders, which contains the routes and the schemas necessary for each route.
  2. Business layer (services layer): it is represented by the services folder, which contains all the code related to the business logic of your application.
  3. Persistance layer (database layer): it is represented by the database folder, which contains the database connection, models and queries (that will be used by the services). Multiple database connection are possible and should be implemented here.

• The server is fully tested and has no errors (at least for now), feel free to report one here.

• Support for windows and linux platforms is available.

• To check the content of the files generated, please check the example folder.

• If you provide a project name that contains spaces, something like 'My awesome Project', every space will be replaced with a hyphen. So at the end your project name will be 'My-awesome-project', but in its README.md file, the hyphens will be removed and the project name will be parsed to title case (My Awesome Project).

• Finally, git will be initialized and a list of libraries will be installed. Check the notes.

• Relative imports is already configured, you do not need to import a file using ../../../some/very/nested/stuff/in/other/folder, you can use some/very/nested/stuff/in/other/folder assuming that your folder is under the src folder.

Who uses Simba.js?

Chazki	Mein	Securitec

What is new?

Please check the changelog.md file. Also, if you want to check what is coming, check the road map.

Notes

Here is the list of the packages that are being installed, as dependencies:

• debug
• zod
• http-errors
• @prisma/client

As devDependencies:

• @jest/types
• @types/debug
• @types/http-errors
• @types/jest
• @types/node
• @typescript-eslint/eslint-plugin
• @typescript-eslint/parser
• axios
• dotenv
• eslint
• eslint-config-prettier
• eslint-config-standard
• eslint-plugin-import
• eslint-plugin-jest
• eslint-plugin-n (in case you are using yarn as package manager)
• eslint-plugin-node
• eslint-plugin-prettier
• eslint-plugin-promise
• jest
• jest-unit
• nodemon
• prettier
• prisma
• standard-version
• ts-loader
• ts-node
• tsconfig-paths
• ts-jest
• typescript

In case you are using GraphQL

As dependencies:

• @apollo/server
• class-validator
• graphql
• reflect-metadata
• type-graphql

Express case

As dependencies:

• cors
• express
• swagger-ui-express

As devDependencies:

• @types/express
• @types/cors
• @types/swagger-ui-express

Fastify case

As dependencies:

• fastify
• @fastify/swagger
• @fastify/swagger-ui
• @fastify/cors
• fastify-type-provider-zod

In case you are using GraphQL

As dependencies:

• @as-integrations/fastify

PostgreSQL case

As dependencies:

• pg
• pg-hstore

MySql case

As dependencies:

• mysql2

MariaDB case

As dependencies:

• mariadb

Sqlite case

As dependencies:

• sqlite3

SQLServer case

As dependencies:

• tedious

Feel free to contribute to this project. Every contribution will be appreciated.

Author

• Anthony Luzquiños - Initial Work - Documentation - AnthonyLzq.

Contributors

• Andree Anchi - Bug reports - andreewaD.