Getting Started with Wrkbelt

This guide will walk you through setting up the Wrkbelt platform for local development. You'll learn how to clone the repository, configure your environment, and run both the UI and API services.

Video Walkthrough

Watch this quick demonstration of the setup process before diving into the step-by-step instructions:

Prerequisites

Before you begin, ensure you have the following installed:

Tool	Required Version
Node.js	v20.19.5
pnpm	v10.2.0
Git	Latest version
MongoDB	Local instance with replicas or access to cloud MongoDB

Step 1: Clone the Repository

First, clone the Wrkbelt repository and navigate to the project directory:

git clone https://github.com/spencermarx/wrkbelt.git
cd wrkbelt

This creates a local copy of the codebase on your machine and positions you in the project's root directory.

Step 2: Install Dependencies

Wrkbelt uses pnpm for package management and NX for monorepo orchestration. Install all dependencies with:

pnpm install

This command installs all the necessary packages defined in the package.json files across the monorepo. It may take a few minutes to complete as it sets up all the required dependencies for both the UI and API applications.

Step 3: Configure Environment Variables

Wrkbelt requires environment configuration for both the UI and API applications:

API Environment Setup

1. Copy the example environment file:

cp apps/api/.env.example apps/api/.env

2. Open apps/api/.env in your editor and update the configuration:

# Required: MongoDB connection string
MONGO_DB_URL="mongodb+srv://db-user:db-password@wrkbelt-production.w2cp3.mongodb.net/local-<your-name>?retryWrites=true&w=majority&appName=Wrkbelt-Local-<Your-Name>"

# Other configuration variables will be provided by your team lead

Personalize Your Database

Replace <your-name> in the MongoDB connection string with your name (e.g., local-john). This ensures you have your own isolated development database.

UI Environment Setup

1. Copy the example environment file:

cp apps/ui/.env.example apps/ui/.env

2. Open apps/ui/.env in your editor:

# The UI environment variables will be provided by your team lead
NEXT_PUBLIC_API_URL=http://localhost:4000

Getting Complete Environment Files

For the complete set of environment variables, contact Spencer Marx. Some variables are not included in the example files for security reasons.

Step 4: Start Development Servers

Wrkbelt uses NX to manage the monorepo. You'll need to start both the UI and API services:

Start in Development Mode

Open two terminal windows:

Terminal 1 - Start the UI:

nx run ui:serve

This command starts the Next.js development server for the UI application. It will automatically reload when you make changes to the UI code.

Terminal 2 - Start the API:

nx run api:serve

This command starts the NestJS development server for the API application. Like the UI server, it supports hot reloading when you modify API code.

Verify Everything is Running

After starting both servers, you should be able to access:

• UI Application: http://localhost:4200
• API Service: http://localhost:4000
• API Documentation: http://localhost:4000/api

Step 5: Run Tests

Wrkbelt has a comprehensive test suite. To run the tests:

# Run all tests across the monorepo
nx run-many --target=test --all

# Run UI tests only
nx run ui:test

# Run API tests only
nx run api:test

# Run tests in watch mode (useful during development)
nx run ui:test --watch

Tests are an integral part of our development workflow. Always ensure your changes pass all tests before submitting a pull request.

Exploring the Codebase

Wrkbelt uses an NX monorepo structure with multiple applications and libraries:

wrkbelt/
├── apps/
│   ├── api/            # NestJS API application
│   ├── ui/             # Next.js UI application
│   └── dev-docs/       # This documentation site
├── libs/
│   ├── api/            # API-specific libraries
│   ├── ui/             # UI-specific libraries
│   └── shared/         # Shared libraries used by multiple apps
├── plugins/            # Nx plugins for development tools
└── infra/              # Infrastructure and build tools

Take some time to explore each application:

• API (NestJS): Examine the modules, controllers, and services to understand the backend functionality
• UI (Next.js): Look through the pages, components, and hooks to understand the frontend structure
• Shared Libraries: Explore the shared types, utilities, and components used across applications

Development Workflow

Once your environment is set up, follow our Development Guide for information about our:

• Git workflow and branching strategy
• Pull request process
• Code review guidelines
• Feature flag usage

Troubleshooting

Common Issues

MongoDB Connection Errors

If you encounter MongoDB connection errors:

1. Verify your connection string is correctly formatted
2. Ensure you've replaced <your-name> with your actual name
3. Check if your IP address is allowed in the MongoDB Atlas network settings (contact Spencer if needed)

Port Already in Use

If port 4000 or 4200 is already in use:

1. Find the process using the port: lsof -i :4000 or lsof -i :4200
2. Kill the process: kill -9 [PID]
3. Or change the port in the appropriate configuration file

Package Installation Issues

If you encounter issues during pnpm install:

1. Clear pnpm cache: pnpm store prune
2. Try installing with verbose logging: pnpm install --verbose
3. Ensure you're using the required Node.js version (v20+)

Additional Support

Need Help?

If you encounter any issues not covered here:

1. Check our internal documentation for more troubleshooting tips
2. Reach out to Spencer Marx or the Wrkbelt team on Slack
3. Consult the NX documentation or NestJS documentation for platform-specific issues

Next Steps

Now that you have Wrkbelt running locally, here are some suggested next steps:

1. Review our Architecture Guide to understand the system design
2. Explore the API documentation at http://localhost:4000/api
3. Make a simple change to the UI or API to test your development flow
4. Set up your Flagsmith account for working with feature flags (contact Spencer for an invite)

Congratulations! You're now ready to start developing with Wrkbelt.