Skip to content

Development Workflows

Common development workflows and best practices for working with the Petfolio monorepo.

Daily Development Flow

flowchart TD
    A[Pull latest main] --> B[Create feature branch]
    B --> C[Make changes]
    C --> D[Run affected tests]
    D --> E{Tests pass?}
    E -->|No| C
    E -->|Yes| F[Commit changes]
    F --> G[Push to remote]
    G --> H[Create PR]
    H --> I[CI Pipeline]
    I --> J{All checks pass?}
    J -->|No| C
    J -->|Yes| K[Code review]
    K --> L[Merge to main]

Getting Latest Changes

Always start with the latest code:

git checkout main
git pull origin main

Creating a Feature Branch

Use descriptive branch names:

# Feature
git checkout -b feature/add-user-profile

# Bug fix
git checkout -b fix/login-validation-error

# Refactor
git checkout -b refactor/simplify-theme-provider

# Documentation
git checkout -b docs/update-architecture-guide

Making Changes

Affected Commands

Nx intelligently detects affected projects:

# Test only affected
npx nx affected:test

# Lint only affected
npx nx affected:lint

# Build only affected
npx nx affected:build

# See what's affected
npx nx affected:graph

Running Individual Projects

# Serve app
npx nx serve petfolio-business

# Test specific library
npx nx test ui-component-library --watch

# Lint and fix
npx nx lint petfolio-business --fix

Testing Workflow

Unit Tests

# Run all tests
npx nx run-many --target=test --all

# Test with coverage
npx nx test ui-component-library --coverage

# Watch mode for development
npx nx test ui-component-library --watch

E2E Tests

# Run all e2e tests
npx nx e2e petfolio-ui-tests

# Run specific test file
npx nx e2e petfolio-ui-tests --spec=login.spec.ts

# Debug mode
npx nx e2e petfolio-ui-tests --debug

Visual Testing with Storybook

# Start Storybook
npx nx storybook ui-component-library

# Build static Storybook
npx nx build-storybook ui-component-library

Committing Changes

Commit Message Format

Follow Conventional Commits:

<type>(<scope>): <subject>

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation only
  • style: Code style (formatting, missing semi-colons)
  • refactor: Code change that neither fixes a bug nor adds a feature
  • perf: Performance improvement
  • test: Adding or updating tests
  • build: Build system or dependencies
  • ci: CI configuration changes
  • chore: Other changes that don't modify src or test files

Examples:

git commit -m "feat(ui): add Button component with variants"

git commit -m "fix(auth): resolve JWT token expiration issue"

git commit -m "docs: update installation guide with Python setup"

git commit -m "refactor(theme): simplify palette structure"

Pre-commit Checks

The repository may have pre-commit hooks that run:

  • Linting
  • Formatting
  • Type checking

If commits are blocked, fix the issues and try again.

Pull Request Workflow

Creating a PR

# Push your branch
git push origin feature/my-new-feature

# Create PR via GitHub CLI (optional)
gh pr create --title "Add new feature" --body "Description of changes"

PR Checklist

Before creating a PR, ensure:

  • All tests pass locally
  • Code is linted and formatted
  • No TypeScript errors
  • Added tests for new features
  • Updated documentation if needed
  • Followed module boundary rules

CI Pipeline

The CI pipeline automatically runs:

  1. Affected detection: Determines what changed
  2. Lint: ESLint checks
  3. Test: Jest unit tests
  4. Build: Production build
  5. E2E: Playwright tests (if app changed)
  6. Security: Trivy vulnerability scan
  7. Docker: Container build (if applicable)

PR Review Process

  1. Automated checks: Must pass before review
  2. Code review: Team member reviews code
  3. Feedback: Address review comments
  4. Approval: Get approval from reviewer
  5. Merge: Squash and merge to main

Working with Dependencies

Adding Dependencies

# Add to main app
npm install --save package-name

# Add dev dependency
npm install --save-dev package-name

# Add to specific project (not common in Nx)
npm install --save package-name --workspace=apps/petfolio-business

Updating Dependencies

# Check outdated packages
npm outdated

# Update all to latest (be careful!)
npm update

# Update specific package
npm update package-name

Working with Components

Creating a New Component

# Create directory
mkdir -p libs/ui-component-library/src/lib/atoms/NewComponent

# Create files
touch libs/ui-component-library/src/lib/atoms/NewComponent/NewComponent.tsx
touch libs/ui-component-library/src/lib/atoms/NewComponent/NewComponent.spec.tsx
touch libs/ui-component-library/src/lib/atoms/NewComponent/NewComponent.stories.tsx

Component Template

NewComponent.tsx
import { FC } from 'react';

export interface NewComponentProps {
  label: string;
  onClick?: () => void;
}

export const NewComponent: FC<NewComponentProps> = ({ label, onClick }) => {
  return <button onClick={onClick}>{label}</button>;
};

Export Component

Add to libs/ui-component-library/src/index.ts:

export * from './lib/atoms/NewComponent/NewComponent';

Using the Component

import { NewComponent } from '@ui-component-library';

export function MyPage() {
  return <NewComponent label="Click me" />;
}

Debugging

VS Code Configuration

Use the provided launch configurations:

  1. Open VS Code
  2. Go to Run and Debug (Ctrl+Shift+D)
  3. Select configuration:
    • "Next.js: debug server-side"
    • "Next.js: debug client-side"
    • "Next.js: debug full stack"

Browser DevTools

Access React DevTools for debugging:

# Install React DevTools extension
# Chrome: https://chrome.google.com/webstore/detail/react-developer-tools

Nx Console

Use Nx Console extension for VS Code:

  1. Install "Nx Console" extension
  2. View available commands in sidebar
  3. Run commands with UI

Hot Reload Issues

If hot reload stops working:

# Clear Nx cache
npx nx reset

# Restart dev server
npx nx serve petfolio-business

Performance Tips

Nx Caching

Nx caches computation results:

# View cache info
npx nx show project petfolio-business

# Clear cache if needed
npx nx reset

Parallel Execution

Run tasks in parallel:

# Lint all projects in parallel
npx nx run-many --target=lint --all --parallel=3

# Test in parallel
npx nx run-many --target=test --all --parallel=2

Troubleshooting

"Cannot find module" Errors

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Clear Nx cache
npx nx reset

TypeScript Errors

# Restart TypeScript server in VS Code
# Ctrl+Shift+P -> "TypeScript: Restart TS Server"

# Or rebuild
npx nx build petfolio-business

Port Already in Use

# Find process using port 4200
lsof -i :4200  # macOS/Linux
netstat -ano | findstr :4200  # Windows

# Kill process
kill -9 <PID>  # macOS/Linux
taskkill /PID <PID> /F  # Windows

Next Steps