Merge pull request #273 from Outblock:272-feature-update-readme

chore: update .env.example and README for improved development setup

.env.example

@@ -4,9 +4,10 @@ GD_FOLDER=""
 GD_AES_KEY=""
 GD_IV=""
 GOOGLE_API=""
+
+# Firebase
 FB_TOKEN=""
-# firebase
-FB_APIKEY=""
+FB_API_KEY=""
 FB_AUTH_DOMAIN="url.firebaseapp.com"
 FB_DATABASE_URL="https://url.firebasedatabase.app"
 FB_PROJECTID=""
@@ -15,7 +16,17 @@ FB_MESSAGING_SENDER_ID=""
 FB_APP_ID=""
 FB_MEASUREMENT_ID=""
 FB_FUNCTIONS=""
-# manifest
+
+# Manifest
 OAUTH2_CLIENT_ID=""
 OAUTH2_SCOPES=""
 WC_PROJECTID=""
+MANIFEST_KEY=""
+
+# Development
+DEV_PASSWORD=""
+MIXPANEL_TOKEN=""
+
+# API URLs (optional - defaults exist in code)
+INITIAL_OPENAPI_URL=""
+WEB_NEXT_URL=""

README.md

@@ -1,29 +1,120 @@
 ## Contribution
 
-### Install dependency
+If you'd like to contribute to the extension, you'll need to install Node.js, pnpm, and get access to the development environment.
 
-1. Install Node.js version v22.11 or later
-2. Install pnpm `npm install -g pnpm`
+### Install Node & Dependencies
+
+1. Install Node.js version v22.11 or later using a [package manager](https://nodejs.org/en/download/package-manager)
+2. Install pnpm `corepack enable pnpm`
 3. Run `pnpm i` to install dependencies
 
-### Configure google-services.json
+Mac / Linux
+
+```
+# install nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+# Install Node.js version v22.11 or later
+nvm install 22
+
+# Use the version of Node.js specifcied in .nvmrc
+nvm use 22
+# install pnpm
+corepack enable pnpm
+
+# checkout dev branch
+git checkout dev
+
+# install dependencies
+pnpm i
+```
+
+Windows
+
+```
+# installs fnm (Fast Node Manager)
+winget install Schniz.fnm
+
+# configure fnm environment
+fnm env --use-on-cd | Out-String | Invoke-Expression
 
-The google services.json file is required to enable Firebase services such as Firebase Authentication and Firebase Cloud Messaging. To use these services, you need obtain the service.json file through firebase and fill in the information in .env.example.
+# download and install Node.js
+fnm use --install-if-missing 22
 
-You should have three different versions of the .env file: one for debug, one for development, and one for release. Please place them in the following directories:
+# install pnpm
+corepack enable pnpm
+
+# install dependencies
+pnpm i
+```
+
+### Configure Environment Variables
+
+Environment variables are needed to interact with certain services. There are two versions of the .env file: one for development, one for release.
 
-- .env
 - .env.dev
 - .env.prd
 
-### Development
+You should only ever need the development version of the .env file as the release version is built using GitHub Actions. The best thing to do is get a copy of the .env.dev file from a developer and add it to the project but **be sure to remove the `DEV_PASSWORD` variable from the file before sharing it.** Never commit the .env.dev file to the repository.
+
+The .env.example file includes all the variables that are needed for the extension to work.
+
+### Building for Development
+
+- (Optional) Run `pnpm react-devtools` to open the React DevTools in your browser. If this is running when you start the development build, the extension will include the React DevTools code. The code is downloaded statically and built into the extension as extensions cannot load external scripts.
+- Run `pnpm build:dev` on Mac / Linux, `pnpm winBuild:dev` on Windows. This will build the extension with file watching and console logging.
+- Open Chrome, go to `chrome://extensions`, enable "Developer mode", click "Load unpacked", and select the `dist` folder.
+
+### Wallets
 
-Run `pnpm build:dev` or `pnpm winBuild:dev` for Windows environment to develop with file watching and development log.
+During development, you'll often be unlocking the wallet. As Chrome extensions cannot use many password managers, we have included a way for developers to set a default password for wallets. This password will be pre-filled in the wallet unlock popup when in development mode.
 
-Run `pnpm build:pro` or `pnpm winBuild:pro` for Windows environment to build a production package, the output extension package is located in the dist folder.
+In .env.dev, set the `DEV_PASSWORD` variable to the password you want to use. This can be any password you want but it must pass the password policy. DO NOT SHARE THIS PASSWORD WITH ANYONE.
+
+You can then create a wallet or import an existing wallet to start using the extension. If you go to the settings page in the extension, you can turn on Developer Mode which will allow you to switch between mainnet and testnet chains.
+
+### Testing & development
+
+- `pnpm test` will run the tests in watch mode.
+- As you code, VS Code or Cursor will automatically lint and format your code when you save files.
+- When you check in code using git, the linter will run to check and format your code.
+
+_NOTE: We are working to create a test environment for the extension. This will allow you to test the with emulated transactions and wallets._
+
+### Folder Structure
+
+- `src/` contains the source code for the extension.
+- `_raw/` contains the raw files for the extension.
+- `dist/` contains the built extension.
+- `_locales/` contains the locale files for the extension.
+- `build/` contains the webpack build files for the extension.
+- `__tests__/` contains tests
+
+The source code is written in TypeScript and uses React on the UI. We have separated the code into the following folders:
+
+- `src/ui/` contains the UI code for the extension popup.
+- `src/background/` contains the background code for the extension service worker.
+- `src/content-script/` contains the content scripts for the extension.
+- `src/shared/` contains the shared utils and types between the different parts of the extension.
+
+There are lint rules in place to ensure, the background code never includes any UI code, and that the service worker doesn't directly interact with globals such as `window` or `document`.
+
+The UI communicates with the background service worker using the `chrome.runtime.sendMessage` and `chrome.runtime.onMessage` APIs. There is a WalletController class that handles the communication with the background service worker. This is the main way the UI interacts with the background service worker. The WalletController proxies the wallet methods in the background service worker using messaging to act as controller for the UI.
+
+### Workflow
+
+We work on the `dev` branch of the repository. Before you start working on the extension, create a branch for the feature you're working on from the `dev` branch. We then have a Github project that co-ordinates features between the iOS, Android, and web extension teams. Please link the issue to the Flow Wallet project and update status as you work on the feature.
+
+1. Always create a new branch from the `dev` branch.
+2. When you're ready to merge your branch into `dev`, create a pull request from your branch to the `dev` branch.
+3. When the pull request is approved, merge it into the `dev` branch.
+4. When you're ready to release a new version of the extension, create a pull request from the `dev` branch to the `master` branch.
+5. When the pull request is approved, merge it into the `master` branch.
+6. When the release is ready to be built, the `master` branch will be built and released to the Chrome Web Store.
 
 ### Language
 
+The extension supports multiple languages. The language files are stored in the `_raw/_locales/` folder. You should put any new strings into these files.
+
 1. Copy `_raw/_locales/en/messages.json` to `_raw/_locales/${localCode}/messages.json` (Find your locale code in [https://en.wikipedia.org/wiki/Language_localisation#Language_tags_and_codes](https://en.wikipedia.org/wiki/Language_localisation#Language_tags_and_codes))
 2. Replace content in `message` property to appropriate locale language