Command Reference Documentation

This document provides a comprehensive reference for all commands and operations available in the v4-monorepo. It's designed to help developers of all experience levels understand, select, and use the appropriate commands for different tasks.

Table of Contents

1. Core Concepts
2. Build Commands
3. Test Commands
4. Linting and Formatting
5. Dependency Management
6. Project Management
7. Deployment Commands
8. Workspace Utilities
9. Common Errors and Solutions
10. Command Selection Guide

Core Concepts

NX Workspace Overview

The v4-monorepo uses NX as its build system and monorepo orchestration tool. NX provides:

• Dependency Graph: Automatic understanding of project dependencies
• Caching: Intelligent caching of task results for faster execution
• Affected Commands: Running tasks only on projects affected by changes
• Workspace Tools: Various tools for managing the monorepo

Key Command Types

Commands in this monorepo generally fall into these categories:

1. Root-level commands: Defined in the root package.json, run with yarn <command>
2. NX commands: Run with nx <command> or yarn nx <command>
3. Project-specific commands: Run with nx run <project>:<target> or yarn workspace <name> <command>

Command Execution Model

Commands in the monorepo typically follow these patterns:

• Direct commands: Simple commands executed directly
• Target-based commands: Commands defined as targets in project.json files
• Executor-based commands: Commands that use NX executors to perform actions
• Composition-based commands: Commands that compose multiple other commands

Build Commands

Basic Build Commands

Command	Description	Experience Level
yarn build	Build all projects	Beginner
nx build <project>	Build a specific project	Beginner
nx affected -t build	Build only affected projects	Intermediate
nx run-many -t build	Build multiple projects	Intermediate

Under the Hood

The build process typically:

1. Resolves dependencies between projects
2. Builds libraries first, then applications
3. Uses different build methods based on project type:
4. TypeScript libraries: TypeScript compiler (tsc)
5. Applications: Vite or other bundlers
6. Python projects: Poetry build

Advanced Build Commands

Command	Description	Experience Level
nx run <project>:build:retry	Build with retry mechanism	Intermediate
nx run <project>:build:actual	Run direct build without wrapper	Advanced
yarn build:tsc	Run TypeScript compiler directly	Advanced
yarn build:validate	Validate build configurations	Advanced
yarn build:enforce	Enforce build standards	Advanced

Example: Building a TypeScript Project With Retry

# Build a specific project with retry mechanism for flaky builds
nx run orderbook:build:retry

Common Errors and Solutions

Error	Solution
"Cannot find module"	Run yarn install to update dependencies
Out of memory	Use yarn build:retry which allocates more memory
TypeScript errors	Run nx run <project>:typecheck to identify issues
Dependency build failures	Build dependencies first: nx run <dependency>:build

Test Commands

Basic Test Commands

Command	Description	Experience Level
yarn nx:test	Run tests for all projects	Beginner
nx test <project>	Test a specific project	Beginner
nx affected -t test	Test only affected projects	Intermediate
nx run-many -t test	Test multiple projects	Intermediate

Under the Hood

The test process typically:

1. Builds the project (if not already built)
2. Runs the appropriate test runner:
3. Jest for TypeScript/JavaScript (unit tests)
4. Vitest for TypeScript/JavaScript (modern tests)
5. pytest for Python projects

Advanced Test Commands

Command	Description	Experience Level
nx test <project> --testFile=path/to/test.spec.ts	Run a specific test file	Intermediate
nx test <project> --config=jest.integration.config.ts	Run integration tests	Intermediate
yarn test:e2e:setup	Set up end-to-end test environment	Advanced
yarn anvil:up	Start Anvil chain for testing	Advanced
yarn docker:test	Run tests in Docker containers	Advanced

Example: Running Integration Tests

# Run integration tests for orderbook
nx test orderbook --config=jest.integration.config.ts

Common Errors and Solutions

Error	Solution
"Test timeout"	Increase timeout in test config or fix slow tests
"Cannot find test file"	Check file path and test configuration
"Database connection error"	Ensure test database is running with yarn docker:up
"Missing dependencies"	Run yarn install to update dependencies

Linting and Formatting

Basic Linting Commands

Command	Description	Experience Level
yarn lint	Lint all projects	Beginner
nx lint <project>	Lint a specific project	Beginner
nx affected -t lint	Lint only affected projects	Intermediate
yarn format	Format all files	Beginner
yarn format-only <project>	Format files in a specific project	Beginner

Under the Hood

The linting process typically:

1. Uses multiple linters in sequence:
2. ESLint for JavaScript/TypeScript
3. Biome for formatting and linting
4. oxlint for advanced JavaScript/TypeScript linting
5. ruff for Python linting

Advanced Linting Commands

Command	Description	Experience Level
yarn format:check	Check formatting without fixing	Intermediate
yarn prettier:write	Run Prettier directly	Intermediate
nx run <project>:lint:unsafe	Run linting with unsafe fixes	Advanced
yarn format:check-pretty	Check formatting with detailed report	Advanced

Example: Fixing Formatting Issues

# Format all files in the repository
yarn format

# Format only files in a specific project
yarn format-only orderbook

Common Errors and Solutions

Error	Solution
"Conflicting configurations"	Review .eslintrc and biome.json for conflicts
"Parsing error"	Fix syntax errors in the file before linting
"Too many formatting errors"	Run formatting with --unsafe flag for automated fixes
"Unknown rule"	Update linting dependencies with yarn install

Dependency Management

Basic Dependency Commands

Command	Description	Experience Level
yarn install	Install all dependencies	Beginner
yarn add <package>	Add a dependency	Beginner
yarn workspace <name> add <package>	Add dependency to specific project	Beginner
yarn nx:fix	Fix workspace dependency issues	Intermediate

Under the Hood

Dependency management in the monorepo involves:

1. Yarn workspaces for JavaScript/TypeScript package management
2. Poetry for Python package management
3. NX for understanding project interdependencies

Advanced Dependency Commands

Command	Description	Experience Level
yarn deps:check	Check for outdated dependencies	Intermediate
yarn update-deps	Update dependencies interactively	Intermediate
yarn peer-deps:check	Check peer dependency issues	Advanced
yarn install:skip-builds	Install without building native modules	Advanced
nx run <python-project>:add --name <dep>	Add Python dependency	Intermediate

Example: Managing Python Dependencies

# Add a Python dependency to the funding project
nx run funding:add --name fastapi

# Add a local Python dependency
nx run funding:add --name commons --local

Common Errors and Solutions

Error	Solution
"Duplicate workspace name"	Run yarn workspace:fix-conflicts
"Cannot find module"	Re-run yarn install
"Native module build failed"	Use yarn install:skip-builds then yarn rebuild:write
"Peer dependency conflict"	Check with yarn peer-deps:check and resolve manually

Project Management

Basic Project Commands

Command	Description	Experience Level
nx show projects	List all projects	Beginner
nx show project <name> --targets	Show project targets	Beginner
nx graph	Visualize project dependencies	Beginner
nx run <project>:<target>	Run a specific project target	Beginner

Under the Hood

Project management in NX involves:

1. Project configuration in project.json files
2. Target definitions that specify commands and options
3. Dependency resolution through the project graph

Advanced Project Commands

Command	Description	Experience Level
nx affected --graph	Show graph of affected projects	Intermediate
nx run-many -t <target> --parallel	Run target on multiple projects in parallel	Intermediate
nx run <project>:<target> --skip-nx-cache	Run without cache	Advanced
yarn nx:validate	Validate all projects	Advanced

Example: Running a Target on Multiple Projects

# Run tests on all TypeScript projects
nx run-many -t test --projects=tag:language:typescript

Common Errors and Solutions

Error	Solution
"Project not found"	Check project name with nx show projects
"Target not found"	Check targets with nx show project <name> --targets
"Cannot resolve dependency"	Check dependency graph with nx graph
"Project cycle detected"	Fix circular dependencies in project references

Deployment Commands

Package Publishing Commands

Command	Description	Experience Level
yarn publish:commons	Publish commons-ts package (patch)	Intermediate
yarn publish:commons:minor	Publish commons-ts package (minor)	Intermediate
yarn publish:commons:major	Publish commons-ts package (major)	Intermediate
yarn publish:connections	Publish connections-ts package	Intermediate
yarn publish:tools	Publish tools package	Intermediate

Under the Hood

The package publishing process:

1. Increments version in package.json
2. Builds the package
3. Resolves workspace dependencies
4. Temporarily changes package scope to match GitHub organization
5. Publishes to GitHub Packages
6. Creates git tag and commits version bump

Example: Publishing a Package

# Publish a patch version of the commons-ts package
yarn publish:commons

# Publish a minor version update
yarn publish:commons:minor

Common Errors and Solutions

Error	Solution
"Authentication required"	Set up GitHub token with yarn publish:set-token
"Version already exists"	Check current version and increment appropriately
"Build failed"	Fix build issues before publishing
"Dependency resolution failed"	Ensure all dependencies are correctly resolved

Workspace Utilities

Development Environment Commands

Command	Description	Experience Level
yarn docker:up	Start Docker development environment	Beginner
yarn docker:down	Stop Docker environment	Beginner
yarn docker:build	Build Docker images	Intermediate
yarn docker:cleanup	Clean up Docker resources	Intermediate
yarn anvil:up	Start Anvil blockchain for testing	Intermediate
yarn anvil:down	Stop Anvil blockchain	Intermediate

Under the Hood

These commands:

1. Manage Docker containers for services like MySQL, Redis
2. Set up local blockchain environments for testing
3. Configure development environments for services

Workspace Maintenance Commands

Command	Description	Experience Level
yarn clean	Clean up workspace	Intermediate
yarn backup	Backup critical files	Intermediate
yarn secrets:check	Check for leaked secrets	Intermediate
yarn clean:reset	Reset workspace completely	Advanced
yarn docs:create-adr	Create architecture decision record	Intermediate
yarn repo:generate-report	Generate repository report	Advanced

Example: Cleaning Workspace

# Check what would be cleaned
yarn clean:check

# Clean workspace
yarn clean

Common Errors and Solutions

Error	Solution
"No space left on device"	Run yarn docker:cleanup to free up space
"Too many open files"	Restart system or increase file descriptor limits
"Cache corruption"	Run yarn nx:fix to repair NX cache
"Git conflicts"	Resolve git conflicts manually

Type Checking Commands

Basic Type Checking Commands

Command	Description	Experience Level
nx run <project>:typecheck	Type check a TypeScript project	Beginner
yarn nx:typescript	Type check all TypeScript projects	Beginner
yarn nx:python	Type check all Python projects	Beginner

Under the Hood

Type checking involves:

1. For TypeScript: Running tsc with --noEmit flag
2. For Python: Running pyright with appropriate configuration

Advanced Type Checking Commands

Command	Description	Experience Level
yarn ts:strictness:check	Check TypeScript strictness	Intermediate
yarn ts:strictness:fix	Fix TypeScript strictness issues	Intermediate
yarn ts:excess-props:check	Check for excess properties	Advanced
yarn ts:unused:check	Check for unused code	Advanced

Example: Fixing TypeScript Issues

# Check for TypeScript strictness issues
yarn ts:strictness:check

# Fix TypeScript strictness issues
yarn ts:strictness:fix

Common Errors and Solutions

Error	Solution
"Type errors"	Address each type error or use appropriate type annotations
"No matching overload"	Check function parameter types and constraints
"Cannot find module"	Ensure the module is installed and properly referenced
"Property does not exist"	Fix property access or add appropriate type definitions

Common Errors and Solutions

Build Errors

Error	Solution
"Cannot read properties of null (reading 'unlock')"	Run nx reset to clear NX cache
"Out of memory"	Use retry builds with nx run [project]:build:retry
"ESBuild failed"	Check for syntax errors in the code
"Module not found"	Ensure dependencies are installed and correctly referenced

Test Errors

Error	Solution
"Test timeout"	Increase timeout in test configuration
"Connection refused"	Ensure required services are running (Docker, databases)
"No tests found"	Check test file patterns in configuration
"Jest worker crashed"	Increase memory allocation for tests

Dependency Errors

Error	Solution
"Duplicate workspace name"	Run yarn workspace:fix-conflicts
"Conflicting peer dependencies"	Resolve version conflicts manually
"Native module build failed"	Use yarn install:skip-builds then install platform-specific binaries
"Poetry lock failed"	Run yarn nx run <project>:lock to regenerate lock file

TypeScript Errors

Error	Solution
"Type error"	Fix type issues or add appropriate type annotations
"Excessive property checks"	Run yarn ts:excess-props:check to identify and fix
"Unused variables"	Run yarn ts:unused:check to find and remove
"Declaration file errors"	Fix interface definitions or update typings

Command Selection Guide

Selecting the Right Build Command

Choose the appropriate build command based on your needs:

• Building everything: yarn build
• Building one project: nx build <project>
• Building affected projects: nx affected -t build
• Building with more memory: nx run <project>:build:retry
• Building for production: nx run <project>:build:production

Selecting the Right Test Command

Choose the appropriate test command based on your needs:

• Testing everything: yarn nx:test
• Testing one project: nx test <project>
• Testing affected projects: nx affected -t test
• Running integration tests: nx test <project> --config=jest.integration.config.ts
• Testing with Docker: yarn docker:test

Selecting the Right Lint Command

Choose the appropriate lint command based on your needs:

• Linting everything: yarn lint
• Linting one project: nx lint <project>
• Formatting everything: yarn format
• Checking formatting only: yarn format:check
• Formatting one project: yarn format-only <project>

When to Use Direct vs. NX Commands

• Use direct commands (yarn <command>) when:

• Working with repository-wide operations

• Using utility scripts

• Running predefined workflows

• Use NX commands (nx <command>) when:

• Working with specific projects

• Leveraging caching and dependency analysis

• Using project-specific targets

• Use workspace commands (yarn workspace <name> <command>) when:

• Working with package-specific scripts
• Managing dependencies for a specific package
• Running commands scoped to a single project