Merge pull request #5 from brunotot/md-repository-refactor

Md repository refactor

.eslintrc

@@ -10,7 +10,7 @@
     "sourceType": "module"
   },
   "plugins": ["@typescript-eslint"],
-  "ignorePatterns": ["node_modules/", "dist/", "logger.js", "docs/", "updateDepDocs.js"],
+  "ignorePatterns": ["node_modules/", "dist/", "logger.js", "docs/", "updateDepDocs.js", "npx"],
   "rules": {
     "@typescript-eslint/consistent-type-imports": "error",
     "@typescript-eslint/ban-ts-comment": "off"

INSTALL.md

@@ -1,4 +1,5 @@
-- [1. Fork repositorya](#1-fork-repositorya)
+- [Installation](#installation)
+- [1. Fork repository](#1-fork-repository)
   - [1.1. Fork main branch](#11-fork-main-branch)
   - [1.2. Enable workflows](#12-enable-workflows)
   - [1.3. Configure workflow permissions](#13-configure-workflow-permissions)
@@ -10,7 +11,22 @@
   - [2.4. Setup Backend service (Express app)](#24-setup-backend-service-express-app)
   - [2.5. Setup Frontend service (React app)](#25-setup-frontend-service-react-app)
 
-## 1. Fork repositorya
+## Installation
+
+1. Clone repo
+   ```sh
+   git clone https://github.com/brunotot/monorepo-mern-railway-starter.git MY_APP
+   ```
+2. Enter repo directory
+   ```sh
+   cd MY_APP
+   ```
+3. Reinitialize git
+   ```sh
+   rm -rf .git && git init -b main
+   ```
+
+## 1. Fork repository
 
 ### 1.1. Fork main branch
 
@@ -38,8 +54,7 @@ Currently, you have only one workflow at your disposal - **typedoc.yml**. There
 
 - run **typedoc.yml** workflow by navigating to **Actions -> Workflows -> Publish TypeDoc-generated docs** and clicking on `Run workflow` button
 - make sure to wait for initial workflows to finish
-- once finished, navigate to **Settings -> Pages** and select `gh-pages` branch (which was generated by our TypeDoc workflow) as the deployment branch
-- save the new configuration
+- once finished, navigate to **Settings -> Pages** and select `gh-pages` branch (which was generated by our Typehttps://railway.app/login
 
 ## 2. Setup Railway for deployment
 

md/features.md

@@ -0,0 +1 @@
+## Features

md/installation.md

@@ -0,0 +1,90 @@
+## Installation
+
+### GitHub repository setup
+
+1. Create new repository from `@mern-monorepo-starter` template [here](https://github.com/new?template_name=monorepo-mern-railway-starter&template_owner=brunotot).
+
+2. Navigate to **Repo > Settings > Actions - General** and save the following Workflow-related options:
+
+   1. `Read and write permissions` checked
+   2. `Allow GitHub Actions to create and approve pull requests` checked
+
+3. Now GitHub actions are ready for usage. Let's now re-run the autogenerated TypeDoc workflow so it generates the `gh-pages` branch. Navigate to **Repo > Actions > MERN Sample App - TypeDoc** and click on **Run workflow**
+
+4. After the `gh-pages` branch is generated, navigate to **Repo > Settings > Pages** and save the `gh-pages` branch as the deployment branch.
+
+5. That's it! Now your GitHub repository is ready to be used for deployment
+
+### Local installation
+
+1. Clone the previously created repository to your local machine
+
+   ```sh
+   git clone https://github.com/REPO_USER/REPO_NAME.git
+   ```
+
+2. Change directory to the cloned one from Step **#1**
+
+   ```sh
+   cd REPO_NAME
+   ```
+
+3. Install local packages and run prepare scripts
+
+   ```sh
+   pnpm install
+   ```
+
+4. That's it! Now you may open the project in **VSCode**
+   ```sh
+   code .
+   ```
+
+### Railway setup
+
+1. Create an account on Railway [here](https://railway.app/login)
+
+2. Install `@railway/cli` if you don't have it already
+
+   ```sh
+   npm i -g @railway/cli
+   ```
+
+3. Now you have access to the **railway** command. See [Railway CLI documentation](https://docs.railway.app/reference/cli-api)
+
+   ```sh
+   railway --help
+   ```
+
+4. Login to Railway CLI
+
+   ```sh
+   railway login
+   ```
+
+5. Create a new Railway project
+
+   ```sh
+   railway init
+   ```
+
+6. Setup created project through Railway's website (the link will be printed to the console)
+   <!--   > [!WARNING]
+      > To gain access to Railway Deployments you should upgrade your Railway account to at least a Hobby tier ($5.00 / month). -->
+
+   - setup **MongoDB** service
+     1. create MongoDB service by clicking on **New > Database > Add MongoDB**
+     2. under **MongoDB Service > Data** create `test` database
+     3. under **MongoDB Service > Data** create `production` database
+     4. under **MongoDB Service > Data** create `development` database
+     5. under **MongoDB Service > Variables** section, find and store the value of `MONGO_URL` locally
+   - setup **Backend** service - **Express app**
+
+     > [!WARNING]
+     > Incoming steps require at least a `Hobby` plan on the Railway account (lowest priced at $5/month)
+
+     1. create Backend service by clicking on **New > GitHub Repo**
+     2. connect your repository to your Railway project
+     3. edit service name to `Backend`
+
+   - setup **Frontend** service - **React app**

md/scripts/mergeMds.js

@@ -51,6 +51,7 @@ const markdownFiles = [
   //`${pathFromDir("./../overview.md")}`,
   `${pathFromDir("./../banner.md")}`,
   `${pathFromDir("./../project-name-meaning.md")}`,
+  `${pathFromDir("./../installation.md")}`,
 ];
 const outputFilePath = `${pathFromDir("./output.md")}`;
 

md/scripts/output.md

@@ -15,6 +15,10 @@
 TOC
 
 - [Understanding the repository name](#understanding-the-repository-name)
+- [Installation](#installation)
+  - [GitHub repository setup](#github-repository-setup)
+  - [Local installation](#local-installation)
+  - [Railway setup](#railway-setup)
 
 ## Understanding the repository name
 
@@ -31,3 +35,86 @@ TOC
 - A **starter** repository is designed to be a starting point for new projects. It includes essential configurations, structures, and code examples to jump-start development without having to set up everything from scratch. This repo is tailored to provide developers with a ready-to-use, comprehensive setup that embodies best practices and modern development standards.
 
 Each element of the repository name has been carefully chosen to reflect the core aspects and intended usage of the project, ensuring that developers can quickly grasp the utility and focus of this monorepo.
+
+## Installation
+
+### GitHub repository setup
+
+1. Create new repository from `@mern-monorepo-starter` template [here](https://github.com/new?template_name=monorepo-mern-railway-starter&template_owner=brunotot).
+
+2. Navigate to **Settings > Actions - General** and save the following Workflow-related options:
+
+   1. `Read and write permissions` checked
+   2. `Allow GitHub Actions to create and approve pull requests` checked
+
+3. Now GitHub actions are ready for usage. Let's now re-run the autogenerated TypeDoc workflow so it generates the `gh-pages` branch. Navigate to **Actions > MERN Sample App - TypeDoc** and click on **Run workflow**
+
+4. After the `gh-pages` branch is generated, navigate to **Settings > Pages** and save the `gh-pages` branch as the deployment branch.
+
+5. That's it! Now your GitHub repository is ready to be used for deployment
+
+### Local installation
+
+1. Clone the previously created repository to your local machine
+
+   ```sh
+   git clone https://github.com/REPO_USER/REPO_NAME.git
+   ```
+
+2. Change directory to the cloned one from Step **#1**
+
+   ```sh
+   cd REPO_NAME
+   ```
+
+3. Install local packages and run prepare scripts
+
+   ```sh
+   pnpm install
+   ```
+
+4. That's it! Now you may open the project in **VSCode**
+   ```sh
+   code .
+   ```
+
+### Railway setup
+
+1. Create an account on Railway [here](https://railway.app/login)
+
+2. Install `@railway/cli` if you don't have it already
+
+   ```sh
+   npm i -g @railway/cli
+   ```
+
+3. Now you have access to the **railway** command. See [Railway CLI documentation](https://docs.railway.app/reference/cli-api)
+
+   ```sh
+   railway --help
+   ```
+
+4. Login to Railway CLI
+
+   ```sh
+   railway login
+   ```
+
+5. Create a new Railway project
+
+   ```sh
+   railway init
+   ```
+
+6. Setup created project through Railway's website (the link will be printed to the console)
+   <!--   > [!WARNING]
+      > To gain access to Railway Deployments you should upgrade your Railway account to at least a Hobby tier ($5.00 / month). -->
+   - setup **MongoDB** service
+     1. create MongoDB service by clicking on **New > Database > Add MongoDB**
+     2. under **MongoDB Service > Data** create `test` database
+     3. under **MongoDB Service > Data** create `production` database
+     4. under **MongoDB Service > Data** create `development` database
+     5. under **MongoDB Service > Variables** section, find and store the value of `MONGO_URL` locally
+   - setup **Backend** service - **Express app**
+     1. create Backend service by clicking on **New > GitHub Repo**
+   - setup **Frontend** service - **React app**

npx/create-mern-monorepo/index.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import "zx/globals";
+import inquirer from "inquirer";
+
+const TEMPLATE_REPO = "brunotot/monorepo-mern-railway-starter";
+
+const { ownerHandle, repoHandle, repoVisibility, repoDescription } = await inquirer.prompt([
+  {
+    name: "ownerHandle",
+    message: "[1/4] Your GitHub username:",
+    default: "brunotot",
+  },
+  {
+    name: "repoHandle",
+    message: "[2/4] Repository name:",
+    default: "my-mern-monorepo",
+  },
+  {
+    name: "repoVisibility",
+    message: "[3/4] Repository visibility:",
+    choices: ["Public", "Private", "Internal"],
+    type: "list",
+  },
+  {
+    name: "repoDescription",
+    message: "[4/4] Repository description:",
+    default: "",
+  },
+]);
+
+try {
+  const res =
+    await $`gh repo create ${repoHandle} --template ${TEMPLATE_REPO} --${repoVisibility.toLowerCase()} --description ${repoDescription ?? " "}`;
+  console.log(res.stdout);
+} catch (error) {
+  console.log(error);
+}

npx/create-mern-monorepo/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "create-mern-monorepo",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.mjs",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "bin": {
+    "create-mern-monorepo": "index.mjs"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "inquirer": "^9.2.21",
+    "zx": "^8.1.0"
+  }
+}

packages/backend/src/config/index.ts

@@ -1,14 +1,14 @@
-/* @org/backend/config/managers */
-export * from "./managers/InjectorMetadataManager";
-export * from "./managers/JwtManager"
-
 /* @org/backend/config/singletons */
-export * from "./singletons/ServiceRegistry";
 export * from "./singletons/Environment";
+export * from "./singletons/ServiceRegistry";
 export * from "./singletons/Logger";
-export * from "./singletons/MongoClient";
 export * from "./singletons/RouterCollection";
 
+/* @org/backend/config/managers */
+export * from "./managers/InjectorMetadataManager";
+export * from "./managers/JwtManager"
+export * from "./managers/DatabaseManager"
+
 /* @org/backend/config/setup */
 import "./setup";
 

packages/backend/src/config/managers/DatabaseManager.ts

@@ -0,0 +1,35 @@
+import { Environment } from "@org/backend/config/singletons/Environment";
+import { type Db } from "mongodb";
+import { type ZodSchema, type z } from "zod";
+import server from "@org/backend/server";
+
+export class DatabaseManager {
+  private static instance: DatabaseManager;
+
+  static getInstance() {
+    this.instance ??= new DatabaseManager();
+    return this.instance;
+  }
+
+  #client: Db;
+
+  private constructor() {
+    // NOOP
+  }
+
+  get client() {
+    if (this.#client) return this.#client;
+    this.#client = server.mongoClient.db(Environment.getInstance().vars.MONGO_DATABASE);
+    return this.#client;
+  }
+
+  collection<const T extends ZodSchema>(zodSchema: T) {
+    const documentName = zodSchema.description;
+    if (!documentName) throw new Error("No document name provided.");
+    const lowerCaseName = documentName.toLowerCase();
+    const suffix = "s";
+    const computedSuffix = lowerCaseName.endsWith(suffix) ? "" : suffix;
+    const name = lowerCaseName + computedSuffix;
+    return this.client.collection<z.infer<T>>(name);
+  }
+}