🧐 What is mern-monorepo-starter?

mern-monorepo-starter is a GitHub template designed to kickstart your next TypeScript 5 project, offering an opinionated, ready-to-use monorepo structure that takes care of all the tricky configuration for you.

The following packages are implemented and at your disposal:

• app-node-express ^{[TS Compiler, NodeJS, Express API, MongoDB, Keycloak, Railway]}
• app-vite-react ^{[Vite, ReactJS, Railway]}
• lib-api-client ^{[TS Compiler, ts-rest]}
• lib-commons ^{[TS Compiler]}

TOC

• 🧐 What is mern-monorepo-starter?
• 🔧 Prerequisites
• 💻 Installation
  • GitHub repository setup
  • Keycloak installation
  • Keycloak realm configuration
  • Local installation
• 🚢 Deploy
  • Deploy with Railway
• 🧩 Recommended VSCode extensions

🔧 Prerequisites

• PNPM
• Node.js
• Git
• VS Code (Optional)

💻 Installation

GitHub repository setup

1. Create your repository

   ---

   Create your monorepo repository using this template.

   ---

2. Configure GitHub permissions

   ---

   Enable GitHub actions to create and approve pull requests.

   ---

   • Go to Settings > Actions > General > Workflow permissions
   • Enable the following settings:
     • ✅ Read and write permissions
     • ✅ Allow GitHub Actions to create and approve pull requests
   • Save changes.
3. Configure GitHub actions

   Run existing actions for the first time.

   • Go to Actions > typedoc-generator.yml
   • Click on the Run workflow button.
   • Repeat the process for all test- prefixed workflows.
   • After all workflows finish, navigate to Settings > Pages.
   • Select the gh-pages branch as the deployment source.
   • Save changes.
4. Configure GitHub ci

   Configure branch protection rules to prevent direct pushes to the main branch, require pull requests for merging, and all status checks to pass before merging.

   • Set the branch name pattern to main.
   • Enable the following settings:
     • ✅Require a pull request before merging
     • ✅Require status checks to pass before merging
     • ✅Require branches to be up to date before merging
   • Disable the setting:
     • ❌ Require approvals
   • Select the following workflows as required for all pull requests:
     • test-app-node-express
     • test-app-vite-react
     • test-lib-commons
     • test-lib-api-client
   • Save changes.

Keycloak installation

1. Download Keycloak binary

   Download links can be found here.

   ---

2. Unpack files to a desired destination
3. Run Keycloak in dev mode

   sh [PATH_TO_KC]/bin/kc.sh start-dev

   ---

Keycloak realm configuration

1. Add admin user (realm-level)

   • Open http://localhost:8080 to access Keycloak admin GUI
   • Enter your admin user credentials (which you use for your future logins)
   • Save and login to Keycloak admin GUI
2. Create a client for your app

   • Navigate to Clients > Create client
   • Enter client data
   • Client type: OpenID Connect
   • Client id: app-vite-react
   • Client authentication: Off
   • Authorization: Off
   • Authentication flow: Standard flow, Implicit flow & Direct access grants
   • Valid redirect URIs: *
   • Valid post logout redirect URIs: *
   • Web origins: *
   • Save client

   ---

3. Add roles to your app client

   • Open app-vite-react client
   • Navigate to Roles tab
   • Click on Create role
   • Add the following roles:
     • avr-admin
     • avr-user

   ---

4. Set role avr-admin on admin user

   • Open admin user details
   • Navigate to Role mapping tab
   • Click on Assign role and select avr-admin role

   ---

5. Configure admin-cli client

   • Open admin-cli client details
   • On Settings tab choose the same options as defined in 2nd step with exception of setting Client authentication to On and also checking the Service accounts roles checkbox
   • On Credentials tab choose Client Authenticator: Client Id and Secret and generate a Client Secret
   • Copy the secret, you will put it in project's .env file
   • Save changes

   ---

Local installation

1. Clone to local machine

   ---

   Clone previously created repository into your local machine.

   git clone https://github.com/YOUR_USER/YOUR_REPO.git

   ---

2. Install dependencies

   ---

   Install dependencies with pnpm.

   pnpm install

   ---

3. Configure environment variables

   ---

   Configure .env.development.local variables for app-node-express (see full env schema defined at @org/app-node-express/env)

   SERVER_SESSION_SECRET	Your server session secret string
   KEYCLOAK_ADMIN_CLI_SECRET	Your Keycloak admin-cli secret

   ---

4. Run a sample app locally

   ---

   You can now run your app-node-express with:

   pnpm run app-node-express:dev

   ---

🚢 Deploy

Deploy with Railway

1. Create new account on Railway

   ---

   You can create your Railway account here

   ---

2. Create new Railway project

   ---

   Create a new project through Railway's dashboard and connect it to your GitHub monorepo

   ---

3. Import template to your Railway project

   ---

   • Within the project, select + Create and choose From Template
   • Select mern-monorepo-starter
   • Follow through with setup (and environment variables)

   ---

4. Deploy

   ---

   Deploy all project changes by clicking Deploy button 🚀

   ---

🧩 Recommended VSCode extensions

• Auto Import - ES6, TS, JSX, TSX
• ESLint
• Markdown All in One
• Live Server
• Prettier - Code formatter
• Pretty TypeScript Errors