From 0a5ded38984d0f208e0e0479a5691575e1ace3b6 Mon Sep 17 00:00:00 2001
From: bc-victor <140021227+bc-victor@users.noreply.github.com>
Date: Tue, 31 Oct 2023 12:00:06 -0600
Subject: [PATCH] feat(BUN-1699): Readme improvements (#819)
* feat(BUN-1699): readme improvements
* feat(BUN-1699): installation of software
* feat(BUN-1699): table of contents
* feat(BUN-1699): adding missing env var
* feat(BUN-1699): support email
---
README.md | 150 +++++++++++++++++++++++++++++++++---------------------
1 file changed, 91 insertions(+), 59 deletions(-)
diff --git a/README.md b/README.md
index 72ce5137..b8f7403c 100644
--- a/README.md
+++ b/README.md
@@ -1,54 +1,79 @@
-# B3-FE-Turbo
-
-The bundleB2B frontend monorepo with [Turborep](https://turborepo.org/), TypeScript and React are the core technologies.
-
-This turborepo uses [Yarn](https://classic.yarnpkg.com/lang/en/) as a package manager. It includes the following packages/apps:
-
-## Apps and Packages
-
-- `/apps/storefront`: the new BundleB2B storefront aplication, [React 18](https://reactjs.org/) app using [vite](http://vitejs.dev/) as the building tool.
-
-- `/packages/eslint-config-b3`: the shared eslint config.
-
-- `/packages/tsconfig`: the shared tsconfig.
-
-- `/packages/ui`: to put all the UI which created by B3.
-
-## What's inside?
-
-This turborepo has the tools and packages already setup:
-
-- [TypeScript](https://www.typescriptlang.org/) for static type checking.
-- [ESLint](https://eslint.org/) for code linting.
-- [commitlint]([https://commitlint.js.org/#/) for the git commit message linting.
-- ([Husky - Git hooks](https://typicode.github.io/husky/#/)) and [lint-staged](https://github.com/okonet/lint-staged) for git hooks.
-- [MUI 5](https://mui.com/) as the basic UI library.
-- [React Router 6](https://reactrouter.com/) as the frontend router.
-
-## Setup
-
-1. Run `yarn install`
-2. Copy `apps/storefront/.env-example` and paste it as `.env`
-3. Update the `VITE_STORE_HASH` value on `.env` file
-4. Update the `VITE_CATPCHA_SETKEY` value on `.env` file
-5. Update the `VITE_B2B_CLIENT_ID`value on `.env`file
-6. Run `yarn dev`
-
-## How to run project locally
-
-1. Activate store channel in the Channels Manager
-
-2. To have the login feature of the b3-fe-turbo project working we need to add a header and footer scripts to our store using the script manager.
-
- - Go to the Channels Manager -> Scripts
-
- - We need to add two scripts to inject our code to storefront, select the names you prefer, e.g. Bundleb2b-header, Bundleb2b-footer
-
- - Before saving, validate the correct values of the port used for running localhost and modify the urls in the scripts.
-
- - Header script:
-
- ```
+# B2B Buyer Portal
+
+A monorepo frontend application designed for the BigCommerce B2B Edition Buyer portal. It's built using Turborepo, TypeScript, and React.
+
+## Index
+
+- [Core Technologies](#-core-technologies)
+- [Workspaces](#-workspaces)
+- [Tools and Libraries](#-tools-and-libraries)
+- [System Setup](#-system-setup)
+- [Local Development](#-local-development)
+- [Running Project Locally](#running-project-locally)
+- [Contribution](#-contribution)
+- [Contact & Support](#-contact--support)
+
+## 🚀 Core Technologies
+
+- **Monorepo Management:** Turborepo
+- **Type System:** TypeScript
+- **Frontend Library:** React 18
+- **Build Tool:** Vite
+
+## 📦 Workspaces
+
+- **Application:** `/apps/storefront` - A next-gen B2B Edition storefront application.
+ - You can run multiple apps concurrently via turborepo [tasks](https://turbo.build/repo/docs/core-concepts/monorepos/running-tasks).
+
+- **Packages:**
+ - `/packages/eslint-config-b3` - Shared ESLint configurations.
+ - `/packages/tsconfig` - Shared TypeScript configurations.
+ - `/packages/ui` - A collection of UI components built by B3.
+ - `/packages/store` - A collection of shared store logic.
+ - `/packages/b3global` - A collection of shared global logic.
+
+## 🛠 Tools and Libraries
+
+- **Linting:** ESLint
+- **Commit Standards:** commitlint
+- **Git Workflow Tools:** Husky, lint-staged
+- **UI Framework:** MUI 5
+- **Routing:** React Router 6
+
+## 🛠 System Setup
+
+- **Node:** Ensure you have Node.js version >=18.0.0.
+- **Package Manager:** This project uses Yarn v1.22.17.
+
+## ⚙ Local Development
+
+1. Installation of Node and Yarn.
+ - For Node, we recommend using [nvm](https://github.com/nvm-sh/nvm).
+ - Once Node is installed, you can install Yarn by using `npm i -g yarn`. If you'd rather use `pnpm`, visit this [guide](https://dev.to/andreychernykh/yarn-npm-to-pnpm-migration-guide-2n04).
+2. Clone the repository.
+3. Install dependencies using `yarn`.
+4. Copy environment variables: `cp apps/storefront/.env-example apps/storefront/.env`.
+5. Update the following values in `.env`:
+ - `VITE_B2B_URL`: The URL of the B2B Edition API.
+ - `VITE_B2B_SOCKET_URL`: The URL of the B2B Edition WebSocket API.
+ - `VITE_TRANSLATION_SERVICE_URL`: The URL of the translation service API.
+ - `VITE_CHANNEL_ID`: The ID of the channel to use for the storefront.
+ - `VITE_STORE_HASH`: The hash of the store to use for the storefront.
+ - `VITE_CATPCHA_SETKEY`: The reCAPTCHA site key (optional).
+ - `VITE_B2B_CLIENT_ID`: The client ID of the BigCommerce App from the [developer portal](https://devtools.bigcommerce.com/).
+ - `VITE_LOCAL_DEBUG`: Set to "FALSE". This is for connecting our local development with the B2B Edition GraphQL API.
+6. Start the development server: `yarn RUN dev`.
+
+## Running Project Locally
+
+1. Activate store channel in the Channels Manager.
+2. Configure header and footer scripts:
+
+ - Navigate to Channels Manager -> Scripts.
+ - Add two scripts (e.g., B2BEdition-header, B2BEdition-footer). Ensure you set the correct port for your localhost in the script URLs.
+ - Edit the header script:
+
+ ```html
```
+ - Edit the footer script:
- - Footer script:
-
- ```
+ ```html
```
-3. Make sure you have added the correct values to the env file in the project. Is important to add the client_id of the draft app since it is used in the codebase while retrieving the jwt token. Otherwise there will appear some error messages related to invalid signatures.
+3. Verify correct values in the .env file, especially the client_id for the draft app.
+
+4. For local debugging, set VITE_LOCAL_DEBUG to false in .env.
+
+5. Visit the storefront and attempt to sign in.
+
+6. For cross-origin issues, update URL variables in .env to use the tunnel URL with HTTPS.
+
+Note: If linters aren't functional, run `yarn prepare` first.
-4. In the file `.env` set up the `VITE_LOCAL_DEBUG` to false.
+## 🤝 Contribution
-5. Go to the storefront and try to sign in.
+For developers wishing to contribute, ensure all PRs meet the linting and commit message standards.
-6. If any issue related cross origin change the value of the variables related to urls in the env file with the one set up as the tunnel url using https.
+## 📞 Contact & Support
-> Note: please run `yarn prepare` first if the linters are not working.
+For queries, issues, or support, reach out to us at b2b@bigcommerce.com or open an issue in this repository.