Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
419 lines (285 loc) · 9.97 KB

DEVELOPMENT.md

File metadata and controls

419 lines (285 loc) · 9.97 KB

Development Guide

This guide is for internal developers working on the @remoteoss/remote-flows package.

Table of Contents

Getting Started

Prerequisites

  • Node.js 20 or higher, (CI uses 24 to have 2FA)
  • npm

Setup

  1. Clone the repository:
git clone https://github.com/remoteoss/remote-flows.git
cd remote-flows
  1. Install dependencies:
npm install
  1. Link the package for local development:
npm link
npm run dev
  1. Set up the example app:
cd example
npm install
npm link @remoteoss/remote-flows
  1. Create .env file in the example directory:
VITE_CLIENT_ID=your_client_id
VITE_CLIENT_SECRET=your_client_secret
VITE_REFRESH_TOKEN=your_refresh_token
VITE_REMOTE_GATEWAY=partners # for sandbox
# VITE_REMOTE_GATEWAY=production # for production
  1. Start the example app:
npm run dev

The example app will be available at http://localhost:3001.

Development Workflow

Available Scripts

  • npm run dev - Build the package in watch mode
  • npm run build - Build the package for production
  • npm test - Run tests
  • npm run type-check - Run TypeScript type checking
  • npm run format - Format code with Prettier
  • npm run size - Analyze bundle size
  • npm run size:check - Check if bundle size is within limits
  • npm run size:badge - Generate badge and history data

Code Structure

remote-flows/
├── src/
│   ├── flows/           # Flow components (CostCalculator, Termination, etc.)
│   ├── components/      # Shared components
│   ├── hooks/           # Custom React hooks
│   └── utils/           # Utility functions
├── example/             # Example application
├── scripts/             # Build and analysis scripts
└── .github/             # CI/CD workflows

Testing

Run the test suite:

npm test

Run type checking:

npm run type-check

Bundle Size Management

We have automated bundle size tracking to ensure the package stays performant.

Size Limits

Size limits are defined in .sizelimit.json:

{
  "limits": {
    "total": 524288, // 512 KB (raw)
    "totalGzip": 131072, // 128 KB (gzip)
    "css": 20480, // 20 KB (raw)
    "cssGzip": 10240, // 10 KB (gzip)
    "maxChunkSize": 262144, // 256 KB (raw)
    "maxChunkSizeGzip": 65536 // 64 KB (gzip)
  }
}

Analyzing Bundle Size

To analyze the current bundle size:

npm run size

This will output:

  • Total bundle size (raw and gzipped)
  • JavaScript breakdown
  • CSS breakdown
  • Top 10 largest files
  • JSON report in out/bundle-analysis.json

Checking Size Limits

To verify the bundle is within limits:

npm run size:check

This command will fail if any limits are exceeded.

Size Comparison

The comparison script compares two bundle analyses:

npx tsx scripts/compare-sizes.ts out/base-bundle.json out/current-bundle.json

This generates a detailed markdown report showing:

  • Size changes (current vs previous)
  • Percentage changes
  • Limit violations
  • File-by-file comparison

CI/CD

Workflows

CI Workflow (.github/workflows/ci.yml)

Runs on every push and pull request:

  • Type checking
  • Tests
  • Build
  • Format check

Size Check Workflow (.github/workflows/size-check.yml)

Runs on pull requests to main:

  • Analyzes bundle size for both PR and base branch
  • Posts comparison report as PR comment
  • Fails if size limits are exceeded
  • Shows current size when comparison isn't available (e.g., when adding new features)

Release Workflow (.github/workflows/release.yml)

Runs when a release PR is merged:

  • Publishes package to npm
  • Creates GitHub release

Bundle Size Reporting

When you open a PR, the size-check workflow will automatically:

  1. Build and analyze your PR's bundle
  2. Build and analyze the base branch bundle
  3. Compare the two and post a detailed report

The report includes:

  • Size changes with percentage differences
  • Current size vs limits
  • Violations (if any)
  • Largest files with changes
  • Full file breakdown in collapsible section

If the comparison script doesn't exist in the base branch (e.g., when adding this feature), it will show the current PR's bundle size instead.

Bundle Size Badge

The repository includes an automated bundle size badge in the README that updates on every push to main.

Badge Setup: See Bundle Size Badge Setup Guide for complete setup instructions.

The badge workflow (.github/workflows/update-badge.yml):

  • Builds and analyzes the bundle on every push to main
  • Updates a GitHub Gist with current size and historical data
  • Powers a shields.io badge in the README
  • Tracks the last 50 size measurements for trend analysis

Badge Colors:

  • 🟢 Green: < 120 KB gzipped
  • 🟡 Yellow: 120-150 KB gzipped
  • 🔴 Red: > 150 KB gzipped

Testing badge generation locally:

First, generate the bundle analysis and badge data:

npm run build
npm run size -- --output out/bundle-analysis.json
npm run size:badge out/bundle-analysis.json

This creates out/size-data.json with the shields.io endpoint format:

{
  "schemaVersion": 1,
  "label": "bundle size",
  "message": "150.57 KB",
  "color": "brightgreen"
}

This format is ready to be uploaded directly to the GitHub Gist for use with the shields.io endpoint badge.

Manually updating the badge:

If you need to manually update the GitHub Gist with the latest badge data:

./scripts/update-gist.sh YOUR_GIST_TOKEN

Or set the token as an environment variable:

export GIST_TOKEN=your_token
./scripts/update-gist.sh

This is useful when testing badge changes or when you need to update the badge without pushing to main.

Release Process

We use an automated release workflow with two different processes depending on the type of release.

Normal Release (from main)

For regular releases with new features and fixes:

  1. Install gh CLI: brew install gh
  2. Authenticate: gh auth login
  3. Run release script: npm run release
  4. Review and merge the PR
  5. GitHub will automatically publish to npm

Hotfix Release (from a specific version)

For urgent fixes that need to be released from a previous version without including unreleased changes from main.

When to Use Hotfixes

  • Critical bugs in production that can't wait for the next regular release
  • Security vulnerabilities that need immediate patching
  • Breaking issues affecting users on a specific version

Note: Hotfixes always bump the patch version only (e.g., 1.2.2 → 1.2.3), never minor or major versions.

Step 1: Create Hotfix Branch

Start from the version tag you want to hotfix:

# Example: Create hotfix for v1.2.2
git checkout -b hotfix-branch v1.2.2

Step 2: Make Your Fix

Make your changes and commit them using conventional commits:

# Make your changes
git add .
git commit -m "fix: description of the hotfix"

Step 3: Prepare Version and Changelog

Run the hotfix release script:

npm run release:fix

This script will:

  • Show the current version (e.g., 1.2.2)
  • Prompt you to enter the hotfix description (e.g., "- Fix authentication timeout issue")
  • Bump to the next patch version (e.g., 1.2.3)
  • Update CHANGELOG.md with your description
  • Create a release branch (e.g., release/1.2.3)
  • Push the branch and create a PR

Step 4: Review and Merge PR

Review the automatically created PR

Step 5: Trigger Release Workflow

  1. Go to Actions → Release workflow
  2. Click "Run workflow"
  3. Select branch: release/1.2.3 (or your release branch name)
  4. Click "Run workflow"

The workflow will:

  • Build and test from your release branch
  • Automatically detect that this is an older version and publish to npm with --tag legacy
  • Create a git tag (e.g., v1.2.3)
  • Create a GitHub release with changelog content

Note: The workflow now automatically detects when publishing an older version and applies the appropriate npm dist-tag, so hotfixes won't conflict with the latest tag.

Step 6: Backport to Main (if needed)

If the fix should also be in main, make the necessary changes and do a normal release.

Version Numbering

Follow semantic versioning:

  • Patch (0.0.x): Bug fixes, security patches (used for hotfixes)
  • Minor (0.x.0): New features, backward-compatible changes
  • Major (x.0.0): Breaking changes

Tips & Best Practices

Keep Bundle Size Small

  • Tree-shake unused code
  • Lazy load heavy components
  • Monitor the size report on every PR
  • Consider alternatives before adding large dependencies

Code Quality

  • Run npm run format before committing
  • Ensure npm run type-check passes
  • Write tests for new features
  • Update flow-specific READMEs when changing APIs

Working with Flows

Each flow has its own README:

When modifying a flow, update its README accordingly.

Troubleshooting

Bundle size check failing in CI

  1. Run npm run size:check locally to see violations
  2. Run npm run size to see detailed breakdown
  3. Identify large files or new dependencies
  4. Optimize or split code as needed
  5. If the increase is justified, update limits in .sizelimit.json

Example app not updating

  1. Ensure you've linked the package: npm link @remoteoss/remote-flows
  2. Restart both the package dev server and example dev server
  3. Check for build errors in both terminals

Type errors in development

  1. Run npm run type-check to see all errors
  2. Ensure dependencies are up to date
  3. Check for TypeScript version compatibility