mevn-auth-generator v1.3.1

mevn-auth-generator 1.3.1

Node/Express/Mongoose project generator with Vue3 PWA, Pinia, Docker and Electron.

Prerequisites

To use the generator, you will need to have node, npm and mongodb installed on your system. In case you want to use Docker, you should have it installed as well. The generator will set up a basic Docker configuration in the generated application, but it will not install any Docker packages.

Installation

To use this package, it is recommended not to use "npm i mevn-auth-generator" but rather, simply navigate to the folder where you want to initialize the project and run the following command:

npx mevn-auth-generator@latest

Given the command, the generator will prompt you to add an icon that will be used to generate all the necessary icons for your PWA. The easiest way to add the icon is to simply copy it directly into the folder where you intend to run the command. When prompted, you can just enter the name of the icon.

In case the entered icon is not found, the generator will ask if you want to proceed with the process. If you wish to continue, press 'y', and the generator will use a default icon.

IMPORTANT: The icon must be in PNG format.

Basic Use

These are the basic operations you will need to perform once the project has been initialized in order to use it. Modify the .env file located in the app/backend folder in this way:

• If you intend to start the application with Docker, uncomment the "mongo_uri" string and assign a name to your database:

  #with docker mongo connect
  MONGO_URI=mongodb://mongo:27017/db_name?replicaSet=rs0

• If you instead intend to use the app without Docker, uncomment the "without docker" string:

  # whitout docker mongo connect
  MONGO_URI=mongodb://127.0.0.1:27017/db_name?replicaSet=rs0

• If you do not wish to use Mongo as a replica set, remove '?replicaSet=rs0' from the MONGO_URI string.
• Generate an access_token and a refresh_token using, for example: openssl rand -base64 32
• Configure an email address to use it within the application and add it along with the password.
• If you want your application to use history routing mode, change the "VITE_ROUTING_MODE" string in the "frontend/.env" file to 'history'. Otherwise, leave it unchanged to use the hash mode.
• To start the backend from the "app/backend" folder, you can use the following command: npm run start.
• To start the frontend from the "app/frontend" folder, you can use the following command: npm run dev.

Docker Use

To create the necessary Docker images for launching the application, you will need to follow some steps:

• delete the "node_modules" folders and the "package-lock.json" files from both the backend and frontend folders.
• Open a terminal and navigate to the root of the project, then run the command:

  docker-compose up --build

• The execution of the command, in case you have maintained the MongoDB replica_set, will generate an error(if you have removed the replica_set from the MongoDB connection string, the following steps in this point will not be necessary nd your application will be immediately available at the address: http://localhost:8080/). Leave the current shell open and open a new one. In the new shell, run the following command:

  docker container ls -a

• Check the name assigned to your MongoDB container and run the command:

  docker exec -it  name_mongo_container bash

• At this point, you can start the mongoshell and enable MongoDB as a replica_set. To do this, execute the following commands sequentially (note: in the "use" command, use the database name set previously in the env file):

  mongosh
  use your_database_name
  rs.initiate()

• Exit the MongoDB shell with Ctrl + D and close the shell. Return to the shell where you have Docker running and stop the process with Ctrl + C.
• Now execute the following command, and your application will be available at http://localhost:8080/

  docker-compose up

If you have no interest in using Docker, you can remove all the reference files, which are:

• docker-compose.yml
• mongo/ *
• frontend/Dockerfile
• frontend/default.config
• backend/Dockerfile

Electron Use

If you intend to use the application with Electron, you will find a basic configuration in the "frontend/electron-src" folder. When using Electron, you should keep the Vue router configuration set to hash mode, so make sure that the "VITE_ROUTING_MODE" string in the "frontend/.env" file is set to 'hash'.

To start the Electron application in development, you can simply run the command npm run electron:dev. To build the application, use npm run electron:build, and you will find the built application in "frontend/dist_electron".

If you are not interested in using Electron, you can delete the "electron_src" folder and remove the following properties from "frontend/package.json":

• scriptselectron:dev
• scriptselectron:build
• devDependencieselectron
• devDependencieselectron-builder
• main
• build

At this point, I recommend deleting the entire "frontend/node_modules" folder and the "frontend/package-lock.json" file. Afterward, inside the "frontend/" folder, run the command npm i to reinstall the dependencies.

Features

mevn-auth-generator aims to provide a foundation for a complete application developed with the MEVN stack, utilizing the bare minimum of external dependencies, in order to make your projects more customizable and maintainable, in this regard, it provides a set of basic components ready for you to extend and modify according to your needs and the project you will be developing. You can find these components inside the folder app/frontend/src/components/, and the components' names will have the "Base" prefix. You can see the pre-made components in action at the routes /dashboard/components-example and /dashboard/form-example.

NOTE: The Base components are written using the integrated mini CSS library, which we will discuss in the next section. If you decide to remove it, you will need to completely revise the styling of the components as well.

Extra

For those who don't want to rely on a CSS framework like Bootstrap or Tailwind, the application provides a small and lightweight CSS library to make styling more manageable. You can find the file in app/frontend/src/assets/css/style.min.css. You can also modify the variables in app/frontend/src/assets/css/_variables.css to better adapt the style to your preferences. If you don't want to use it, you can simply delete the two specified files and the corresponding import in the app/frontend/src/main.js file.

The available classes are as follows:

Breackpoint

// xs
@media (min-width: 576px) { ... }

// sm 
@media (min-width: 768px) { ... }

// md
@media (min-width: 992px) { ... }

// lg
@media (min-width: 1200px) { ... }

// xl
@media (min-width: 1400px) { ... }

Spacing

Spaces are defined by prefixes p (padding) & m (margin), combined with sevens abbreviations that identify the position:

• a(all): top, right, bottom, left
• x: right, left
• y: top, bottom
• t: top
• r: right
• b: bottom
• l: left

And numbers from 1 to 5 to define the quantity. The sizes of margins and paddings are defined in the file app/frontend/src/assets/css/_variable.css.

They can also be set for various breakpoints using the abbreviations:

• xs
• sm
• md
• ls
• xl

Example:

.pa-2
.px-3-sm

Grid

We can use Bootstrap-like classes to define the grid. We have .container, which will be responsive for various breakpoints, and .container-fluid, which will always have a width of 100%.

Then we have .row, which introduces the display: flex and flex-wrap properties to accommodate our columns.

And finally, we have the columns distributed in a 12-column grid, as in the example:

.col-2
.col-xs-3
.col.lg-5

We can also define an offset from 0 to 12 for each breakpoint:

.offset-0
.offset-xs-6

Position

For positioning, we use classes with the prefix pos-. The available types of positions are:

• relative
• absolute
• fixed
• sticky

.pos-fixed

There are also additional classes that allow us to position an element according to certain parameters. In addition to "expand," which you will have an example of here, the others are easily understandable:

.pos-expand{
    top: 0;
    right: 0;
    bottom: 0;
    left: 0;
}
.pos-center
.posX-center
.posY-center
.pos-top-left
.pos-top-right
.pos-bottom-left
.pos-bottom-right

All pos- classes are available for all breakpoints:

.posY-center-xs
.pos-absolute-lg

Text align

Classes for text alignment are also available for every breakpoint:

.text-center
.text-right-lg
.text-left-sm

Flexbox

Flexbox classes are available for every breakpoint as well. Here is a list of all the flex classes you can use:

.flex-column{
    flex-direction: column;
}
.flex-row{
    flex-direction: row;
}
.flex-wrap{
    flex-wrap: wrap;
}
.flex-no-wrap{
    flex-wrap: nowrap;
}
.justify-between {
    justify-content: space-between;
}
.justify-start{
    justify-content: flex-start;
}
.justify-end{
    justify-content: flex-end;
}
.justify-center {
    justify-content: center;
}
.align-center {
    align-items: center;
}
.align-start{
    align-items: flex-start;
}
.align-end{
    align-items: flex-end;
}

//example for breackpoint
.justify-center-xs {
    justify-content: center;
}

Display

There are 4 display classes available for every breakpoint, with the prefix d-:

.d-none
.d-block
.d-flex 
.d-inline-block

//example for breackpoint
.d-flex-sm

Dimension

For each breakpoint, there are also w-number and h-number classes available to set width and height in percentage.

The available numbers are: 0, 25, 50, 75, 100.

.w-25
.h-25-xs

In addition to these, we have the classes .w-max-content and .w-fit-content available for all breakpoints as well.

For dimensions that are based on viewport width and viewport height, we have .w-100-vw and .h-100-vh.

Finally, we can set both the minimum and maximum height and width to 100% with classes like .max-h-100 and .min-w-100, etc.

Colors

Colors can be customized in the app/frontend/src/assets/css/_variables.css file, and for each color, we have the classes color- and bg-color, along with 4 additional classes for white and black colors:

.color-10-1
.bg-color-2
.color-black
.bg-color-white

Extra Class

By default, the library sets the imported font-family from the _variables file for the entire app, the default font-size defined in the --size-default variable, and the default color set in --color-default.

It sets the font sizes for the h1, h2, h3, etc. tags based on those defined in the corresponding variables --size-h1, --size-h2, --size-h3, and provides a class for each of them (e.g., .h1, .h2, etc.).

All the other available classes are listed below:

.list-unstyled{
    list-style: none;
}
.uppercase{
    text-transform: uppercase;
}
.lowercase{
    text-transform: lowercase;
}
.capitalize{
    text-transform: capitalize;
}
.pointer{
    cursor: pointer;
}
.font2{
    font-family: var(--font-family-secondary);
}
.bold-500{
    font-weight: 500;
}
.bold-600{
    font-weight: 600;
}
.bold-700{
    font-weight: 700;
}
.small{
    font-size: var(--size-small);
}
.extra-small{
    font-size: var(--size-extra-small);
}
.medium{
    font-size: var(--size-medium);
}
.large{
    font-size: var(--size-large);
}  

Box-sizing, padding, and margin are set as follows for all elements:

* {
    box-sizing: border-box;
    padding: 0;
    margin: 0;
}

ENJOY!!!