diff --git a/README.md b/README.md index 2beb6831..0ebf2b03 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,17 @@

+## 🧐 What is `typescript-monorepo-starter`? + +`typescript-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](https://github.com/brunotot/typescript-monorepo-starter/tree/main/packages) are implemented and at your disposal: + +- [app-node-express](https://expressjs.com/) [[TS Compiler](https://www.typescriptlang.org/), [NodeJS](https://nodejs.org/en/about), [Express API](https://expressjs.com/en/starter/hello-world.html), [MongoDB](https://www.mongodb.com/company/what-is-mongodb), [Keycloak](https://www.keycloak.org/), [Railway](https://railway.app/)] +- [app-vite-react](https://reactjs.org/) [[Vite](https://vitejs.dev/guide/why.html), [ReactJS](https://react.dev/), [Railway](https://railway.app/)] +- [lib-api-client](https://www.typescriptlang.org/) [[TS Compiler](https://www.typescriptlang.org/), [ts-rest](https://ts-rest.com/)] +- [lib-commons](https://www.typescriptlang.org/) [[TS Compiler](https://www.typescriptlang.org/)] +

MongoDB badge Express badge @@ -16,82 +27,57 @@ TOC -- [What is `typescript-monorepo-starter`?](#what-is-typescript-monorepo-starter) -- [Prerequisites](#prerequisites) -- [Installation](#installation) +- [🧐 What is `typescript-monorepo-starter`?](#-what-is-typescript-monorepo-starter) +- [🔧 Prerequisites](#-prerequisites) +- [💻 Installation](#-installation) - [GitHub repository setup](#github-repository-setup) - [Local installation](#local-installation) -- [Deploy](#deploy) +- [🚢 Deploy](#-deploy) - [Deploy with Railway](#deploy-with-railway) -- [Recommended VSCode extensions](#recommended-vscode-extensions) +- [🧩 Recommended VSCode extensions](#-recommended-vscode-extensions) -## What is `typescript-monorepo-starter`? - -`typescript-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](https://github.com/brunotot/typescript-monorepo-starter/tree/main/packages) are implemented and at your disposal: - -- [app-node-express](https://expressjs.com/) [[TS Compiler](https://www.typescriptlang.org/), [NodeJS](https://nodejs.org/en/about), [Express API](https://expressjs.com/en/starter/hello-world.html), [MongoDB](https://www.mongodb.com/company/what-is-mongodb), [Keycloak](https://www.keycloak.org/), [Railway](https://railway.app/)] -- [app-vite-react](https://reactjs.org/) [[Vite](https://vitejs.dev/guide/why.html), [ReactJS](https://react.dev/), [Railway](https://railway.app/)] -- [lib-api-client](https://www.typescriptlang.org/) [[TS Compiler](https://www.typescriptlang.org/), [ts-rest](https://ts-rest.com/)] -- [lib-commons](https://www.typescriptlang.org/) [[TS Compiler](https://www.typescriptlang.org/)] - -## Prerequisites +## 🔧 Prerequisites - **PNPM** - **Node.js** - **Git** - **VS Code** (Optional) -## Installation +## 💻 Installation ### GitHub repository setup -1. create your repository from [this](https://github.com/new?template_name=mern-monorepo-starter&template_owner=brunotot) template -2. configure your GitHub workflow permissions - - navigate to **Settings** / **Actions** / **General** / **Workflow permissions** - - enable setting `Read and write permissions` - - enable setting `Allow GitHub Actions to create and approve pull requests` - - save configuration -3. configure [Typedoc](https://typedoc.org/) deployment to [GitHub Pages](https://pages.github.com/) - - navigate to **Actions** / **typedoc-generator.yml** - - click on `Run workflow` button - - when typedoc finishes, make sure to do the same for all test workflows - - after all workflows finish, navigate to **Settings** / **Pages** - - select `gh-pages` branch as the deployment branch - - save configuration -4. configure GitHub CI - - navigate to **Settings** / **Branches** / **Add classic branch protection rule** - - set branch name pattern to `main` - - enable setting ✅ `Require a pull request before merging` - - disable setting ❌ `Require approvals` - - enable setting ✅ `Require status checks to pass before merging` - - enable setting ✅ `Require branches to be up to date before merging` - - select following actions as status checks: - - **test-app-node-express** - - **test-app-vite-react** - - **test-lib-commons** - - **test-lib-api-client** - - save configuration +1.

Create your repository
Create your monorepo repository using this template.
+ +2.
Configure GitHub permissions
Enable GitHub actions to create and approve pull requests.
+ +3.
Configure GitHub actionsRun existing actions for the first time.
+ +4.
Configure GitHub ciConfigure branch protection rules to prevent direct pushes to the main branch, require pull requests for merging, and all status checks to pass before merging.
### Local installation -1. clone previously created repository into your local machine -2. install dependencies with `pnpm install` -3. configure `.env.development.local` variables for **app-node-express** (see env schema defined at [env.setup.ts](https://github.com/brunotot/mern-monorepo-starter/blob/main/packages/app-node-express/src/setup/env.setup.ts#L13)) -4. you can now run your **app-node-express** with `pnpm run app-node-express:dev` +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 env schema defined at env.setup.ts
+ +4.
Run a sample app locally
You can now run your app-node-express with:
pnpm run app-node-express:dev

-## Deploy +## 🚢 Deploy ### Deploy with Railway -1. create an account on Railway [here](https://railway.app/login) -2. create a new project on Railway's dashboard and connect to your GitHub monorepo -3. within the project, select `+ Create` and choose `From Template` -4. select **`typescript-monorepo-starter`** template -5. finally, deploy changes 🚀 +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

+ +4.
Deploy
Deploy all project changes by clicking Deploy button 🚀
-## Recommended VSCode extensions +## 🧩 Recommended VSCode extensions - [Auto Import - ES6, TS, JSX, TSX](https://marketplace.visualstudio.com/items?itemName=NuclleaR.vscode-extension-auto-import) - [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) @@ -99,4 +85,3 @@ The following [packages](https://github.com/brunotot/typescript-monorepo-starter - [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) - [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - [Pretty TypeScript Errors](https://marketplace.visualstudio.com/items?itemName=yoavbls.pretty-ts-errors) -- [Tailwind Fold](https://marketplace.visualstudio.com/items?itemName=stivo.tailwind-fold)