# Installation

# Introduction

To get started with ExpressWebJs, you will need to install Node.js >= v14.15.1 and npm >= 6.0.0

Because we want it to be as easy as possible getting started with ExpressWebJs, that's while we have a command line tool to help you install ExpressWebJs.

To start your project, you can use npx expresswebcli new command, followed by your project name and --ts or --typescript.

--ts or --typescript flag enables Expresswebjs to generate the typescript version.

⚠️ It is advised to use Bash command-line when working with ExpressWebJs. Powershell is a task-based command-line interface, specifically designed for system admins and is based on the . Net Framework. Bash is a command-line and scripting language for most Unix/Linux-based operating systems.
 npx expresswebcli new myProjectName --typescript

Or you can use ts inplace of typescript

 npx expresswebcli new myProjectName --ts

You can decide to install expresswebcli globally via npm like so:

npm install -g expresswebcli

Then run the below command to create your project.

  expresswebcli new myProject --ts

Make sure to add the npm system-wide node_modules/.bin directory to your $PATH to be able to access the installed binary.

Once that is done, move into your project directory or use the command below in your terminal.

 cd myProjectName

Once you do that, you can now install all dependencies by running npm install.

 npm install

In version 2 upwards, MAKER command line interface is included in ExpressWebJs. Maker exists at the root of your application as the maker script and provides a number of helpful commands that can assist you while you build your application.

Run the following code once you have created your new project to see all maker commands.

  ts-node maker -h

# Database Setup

ExpressWebJs makes interacting with SQL and NOSQL databases extremely easy across a variety of supported database.

  • MySql
  • MariaDB
  • PostgreSQL
  • Amazon Redshift
  • SQLite3
  • Oracle
  • MicroSoft SQL
  • MongoDB

Befor we continue, if you've not created your .env file, quickly do that by copying example.env to .env file or you can run the following command in your terminal:

   cp example.env .env

Now that our .env file is ready, the configuration for ExpressWebJs database is located in πŸ“˜ Config/database.ts file. In this file, you may define all of your database connections, as well as specify which connection should be used by default. Most of the configuration options within this file are driven by the values of your application's environment variables.

# SQL Database configuration

You can easily configure your environment variables to point to your database by placing the connection values in the .env file. Let's connect to mysql database by updating these values:

DB_SHOULD_CONNECT = true;
DB_CONNECTION = mysql;
DB_HOST = localhost;
DB_PORT = 3306;
DB_USER = database_user;
DB_PASSWORD = database_password;
DB_DATABASE = database;
DB_USENEWURLPARSER = true;
DB_USEUNIFIEDTOPOLOGY = true;
DB_USECREATEINDEX = true;

# NOSQL Database configuration

You can configure your nosql database environment variables to point to your database by placing the connection values in the .env file. Let's connect to mongoDB by updating these values.

DB_SHOULD_CONNECT = true;
DB_CONNECTION = mongoose;
DB_HOST = localhost;
DB_PORT = 27017;
DB_USER = database_user;
DB_PASSWORD = database_password;
DB_DATABASE = database;
DB_USENEWURLPARSER = true;
DB_USEUNIFIEDTOPOLOGY = true;
DB_USECREATEINDEX = true;

Once that is done, you can now run your application with:

  npm run dev

# Performanace

By default, ExpressWebJs makes use of Express but it also provides compatibility with other libraries such as Restana which is a blazing fast, tiny and minimalist connect-like web framework for building REST micro-services.

You can check Restana fast performance benchmark against fastify, express and other frameworks : Check the benchmark (opens new window)

ExpressWebJs achieves this framework independence by implementing a framework platform whose primary function is to proxy middleware and handlers to appropriate library-specific implementations.

# Switching to platform

You can easly switch platforms in ExpressWebJs with just two steps. Let's switch from Express to Restana:

  • In our app.ts file in Config directory, we've added a property called platform
  /*
    |--------------------------------------------------------------------------
    | Application platform
    |--------------------------------------------------------------------------
    |
    | This value is the platform your application will run on. ExpressWebJs currently
    | supports Express and Restana. Express is the default platform. You can switch
    | to Restana which is blazing fast
    |
    */

  platform: env("PLATFORM", platform.Express),   πŸ‘ˆ change platform.Express to platform.Restana
  • Updtae route request and response type in http.ts file in Config directory:
export { Request, Response, NextFunction } from "Elucidate/HttpContext/Platform/Express"; πŸ‘ˆchange
Elucidate/HttpContext/Platform/Express to Elucidate/HttpContext/Platform/Restana

With this few updates, you are ready to go.

# Initial Configuration

ExpressWebJs configuration files are stored in the config directory πŸ“˜Config located in the root directory. Each option is documented, so feel free to look through the files and get familiar with the options available to you.

You are free to get started developing! However, you may wish to review the πŸ“˜Config/app.ts file and its documentation. It contains several options you may wish to change according to your application.