Skip to main content

Quick Start Guide

This guide will help you get started with the Intuition platform development environment.

Prerequisites​

  • Node.js >= 18.0 (v20+ recommended)
  • pnpm 9.0.6
  • Git

Installation​

  1. Clone the Repository

    git clone [email protected]:0xIntuition/intuition-ts.git
    cd intuition-ts

  2. Install Dependencies

    pnpm install

  3. Set Up Environment Variables

    cp .env.example .env.local

Configure your environment variables according to your needs:

  • Development: .env.local
  • Testing: .env.test
  • Production: .env.production

Development Workflow

Starting the Development Server​

  1. Portal Application

    pnpm portal:dev

  2. Component Library Development

    pnpm 1ui:build
    pnpm storybook

Test Structure​

Each package in the monorepo maintains its own test suite:

  1. Unit Tests
    • Located in __tests__ directories
    • Tests individual components and functions
    • Uses Jest with React Testing Library
    • Focuses on isolated functionality
  2. Integration Tests
    • Tests interactions between components
    • Validates data flow and state management
    • Uses React Testing Library for component integration
    • Ensures proper communication between modules
  3. End-to-End Tests
    • Uses Playwright for browser testing
    • Tests complete user workflows
    • Validates real-world scenarios
    • Runs against deployed environments

Test Coverage​

  • Each package maintains its own coverage requirements
  • Coverage reports are generated using Jest
  • Critical paths require higher coverage thresholds
  • UI components require visual regression testing

Testing Utilities​

  • Jest: Primary test runner
  • React Testing Library: Component testing
  • Playwright: E2E testing
  • Vitest: Unit testing with Vite integration
  • Testing Library User Event: User interaction simulation

Testing Best Practices​

  1. Naming Conventions
    • Test files end with .test.ts or .spec.ts
    • Test suites describe component/function purpose
    • Test cases describe expected behavior
  2. Mocking Strategy
    • External services are mocked by default
    • Network requests use MSW (Mock Service Worker)
    • Time-based operations use Jest timers
  3. Test Data
    • Fixtures stored in __fixtures__ directories
    • Factory functions for common test data
    • Separate test and development databases
  4. Continuous Integration
    • Tests run on every pull request
    • Coverage reports generated automatically
    • Visual regression tests for UI changes
    • Performance benchmarks for critical paths

Troubleshooting​

Common Issues​

  1. Package Resolution Issues

    pnpm clean
    pnpm install

  2. Type Errors

    • Ensure all dependencies are installed
    • Run pnpm typecheck
    • Check for missing type definitions

  3. Build Failures

    • Check for linting errors: pnpm lint
    • Verify TypeScript compilation: pnpm typecheck
    • Clear build cache: pnpm clean

Getting Help​

  • Check the GitHub Issues
  • Review package-specific README files
  • Join our developer community

Next Steps​

  1. Explore the API Documentation
  2. Review the Component Library
  3. Check out our [Problem Internal Link]
  4. Join our Developer Community

Version Control​

  • We use conventional commits for version control
  • Each package is versioned independently
  • Release tags follow the pattern: release/{projectName}/{version}