Skip to main content

Development Environment Setup

To get a new engineer from a fresh laptop to a running local instance of the application.

Document Metadata
FieldValue
Version1.2.0
Last UpdatedJanuary 19, 2025
Ownero.yasser@getzeal.io
Status✅ Current
TypeGuide

Prerequisites​

Before you begin, ensure you have the following tools installed on your system:

ToolVersion/RequirementInstallation Guide
GitLatest stableOfficial Git Installation
Node.js22.19.0 (via nvm recommended)Node.js Installation or nvm Installation
YarnLatest (via Corepack recommended)Yarn Installation Guide
Cursor IDELatestDownload Cursor
Using nvm

We recommend using nvm (Node Version Manager) to manage Node.js versions. The project includes an .nvmrc file that automatically sets the correct version when you run nvm use in the project directory.

A extensions.json file is included in the .vscode directory to recommend these extensions automatically when you open the project in Cursor:

ExtensionPurpose
ES7+ React/Redux/React-Native snippetsReact code snippets
ESLintCode linting
GitLensEnhanced Git capabilities
PrettierCode formatting

Project Setup​

Now let's get the project code and install its dependencies.

Clone the Repository​

We maintain two main repositories for frontend development:

RepositoryDescriptionLink
webmonoMonorepo containing our dashboards (Merchant Dashboard, Admin Dashboard, Acquirer Dashboard, etc.)github.com/zeal-io/webmono
whitelabel-websiteWhitelabel (generic) website that serves as an ordering/booking website for merchantsgithub.com/zeal-io/whitelabel-website

Which repository should you clone?

Your work scope follows your squad's scope. Check with your lead or senior engineer to determine which repository you'll be working on. It's good to know where each project exists, and you may need to read both repositories depending on your work.

Once you know which repository to use:

# Clone the repository (replace with the appropriate URL)
git clone https://github.com/zeal-io/<repository-name>

# Navigate into the project
cd <repository-name>

Project Overview​

webmono is our monorepo containing multiple dashboards:

  • Merchant Dashboard
  • Admin Dashboard
  • Acquirer Dashboard
  • And other dashboard applications

whitelabel-website is our generic website solution that serves as an ordering/booking website for merchants.

Scope and Responsibilities

Your work scope follows your squad's scope. Refer to your lead or senior engineer for more information about your specific scope and which repositories you'll be working with. It's beneficial to familiarize yourself with both repositories to understand the broader context of our frontend architecture.

Set Up Environment Variables​

For webmono​

Environment variables are already included in the repository. See the webmono repository for details.

For whitelabel-website​

You'll need to get the QA environment variables from Vault. See the whitelabel-website repository for more information.

  1. Open Vault at https://vault.zeal-members.com/
  2. Navigate to the Whitelabel project secrets
  3. Copy the environment variables
  4. Create a .env.local file in the project root
  5. Paste the variables
Security

Never commit .env.local to version control. It should already be in .gitignore.

Install Dependencies​

yarn install

This will install all project dependencies defined in package.json.

Running the Application​

You're all set! Let's see it in action.

Start the Development Server​

# For QA environment
yarn dev.vndr.qa

Verify It's Working​

  1. Open your browser
  2. Navigate to http://localhost:3000
  3. You should see the Zeal login page

🎉 Congratulations! Your environment is set up.

Run Tests​

To make sure everything is working correctly, run the test suite in a separate terminal window:

yarn test.unit

Tech Stack​

Here's an overview of the technologies we use:

CategoryTechnology
FrameworkNext.js
LanguageTypeScript
StylingTailwind CSS / Styled Components
State ManagementReact Query / Zustand
TestingJest / React Testing Library
Package ManagerYarn
Version ControlGit

Troubleshooting​

Common Issues​

Node version mismatch error

Problem: You see an error about incompatible Node.js version.

Solution:

  • Ensure you have Node.js version 22.19.0 installed
  • If using nvm, run nvm use in the project directory (it will read the .nvmrc file)
  • Verify with node --version - it should output v22.19.0
  • Refer to the nvm documentation for installation and usage instructions
Yarn not found

Problem: Command yarn is not recognized.

Solution:

  • Enable Corepack: corepack enable (recommended)
  • Or install Yarn globally: npm install -g yarn
  • Refer to the Yarn installation guide for platform-specific instructions
Port 3000 already in use

Problem: Another process is using port 3000.

Solution:

  • Find and stop the process using port 3000 (platform-specific commands vary)
  • Or use a different port by setting the PORT environment variable: 
    PORT=3001 yarn dev.vndr.qa

Next Steps​

Once your environment is set up:

  1. ✅ Read the Welcome Guide
  2. ✅ Understand our FE/BE Communication Process
  3. ✅ Pick up your first ticket!
Need Help?

If you run into issues not covered here, reach out in #frontend-team on Slack. We're happy to help!

Change Log​

VersionDateChangesAuthor
1.2.02025-01-15Added repository links (webmono and whitelabel-website), added project overview section, updated environment variables section with repository referencesDocumentation Team
1.1.02025-01-15Refactored to be platform-agnostic, removed macOS/Homebrew-specific instructions, added external documentation links for prerequisitesDocumentation Team
1.0.02025-01-15Initial versiono.yasser@getzeal.io