@teambit/flows

teambit.bit/flows

Run tasks on components and their dependents.

• Provides a bit run command to execute tasks on components in worksapce.
• Provides an API to create network of components and execute tasks.
• Used as a low-level API for other Bit commands like compile, test and watch.

Description

Inside a Bit project all components are linked to each other in a network according to their dependency graph. When you make a change, you can see the downstream effets when running component tasks. This means that all tasks run in the right order and if several components don't directly depend on each other, Flows parallelizes their tasks (and shows live console output in a readable order).

Usage

Command sinopsys

bit run <flow-name> [components...] [-v | --verbose] [--concurrency]

Examples

# runs 'build' flow on all components that have 'build' task defined.
bit run build

# runs 'build' flow for a specific component.
bit run build logo

# same as before with verbose output
bit run build logo --verbose

# setting concurrency
bit run build logo --concurrency 4 --verbose

Configuration

Use bit.jsonc configuration docs to understand how to configure bit.

// workspace configuration with default values for 'concurrency' and 'verbose'

{
  "teambit.bit/flows": {
    "concurrency": 4,
    "verbose": false,
    "tasks": {
      // the structure of a module task id: = `\`#${PackageName}:${PathToModule}\``
      "build": ["@bit/bit.evangalist.extensions.react-ts:transpile"],
    }
  }
}

You may also use the variants configuring option to override tasks of a specific component(s). The structure allows only for the task entry in that use case.

{
  "variants": {
    "ui/*":{
      "teambit.bit/flows": {
        "tasks": {
          "build": ["some_build_task"]
        }
      }
    }
  }
}

Consult with the docs to learn more about variants.

Flows API

Flows API is document in flows.ts module. Here are two examples:

import {Flows, flattenReplaySubject} from 'teambit.bit/flows'

const flows = new Flows(workspace)
const execution = flows.run(seeders)

// rxjs example
flattenReplaySubject(execution)
  .subscribe((result) => console.log('result is:', result))

// promise example
const result = await flows.runToPromise(seeders)
console.log('result is', result)

Recommended WorkFlows

Flows prefers convention over configuration for managing team's workflow to scale their development. It's philosophy is that when teams agree on the kind of actions they support it's easier to onboard developers to various projects in the organization. This is mainly becasue it helps developers avoid the details of each component build and treat it as the "same" action.

For example:

• build - run all compilation/testing/lint
• ci - flow to run bit CI system
• dev - compiling with source map and what not.
• personal - personal workflow team doesn't know of, to test things.

How to implement a task

A task is a module which exports a default function (or module.exports) with the following signature:

export type Task = () => any | () => Promise<any>

• Tasks should be tracked and exported as components to a remote Bit scope.
• Tasks defined as devDependencies for components consuming them.
• Each task stdout, stderr is reported.
• Each task should return a value (which is truthy) which will be reported to Bit's main process.

Design

The Flows API solves the problem of reporting the execution of dynamic activities across a graph of isolated components. The problem becomes complex in use cases like TypeScript API where dependent/dependency components build order needs to be respected.

Flows solves this problem by providing:

• Unified UX
• Aggressive caching
• Topological execution order.

Entities

• Capsule - Isolated representation of a component in filesystem.
• Network - A graph of component capsules.
• Flow - A collection of tasks to execute in a capsule.
• Task - a runnable activity in a capsule defined by bash or javascript task.

For each main term there is a module in the flows implementation.

Additional modules

• Cache - Caches capsule execution in ~/Library/Caches/Bit/capsules
• Run - Holds run command as a component.
• util - fake-capsule creation, rxjs helper etc.

Changelog

[0.0.945] - 2022-12-27

New Features

• New tab for exploring component's API reference (#6444)
• Responsive top bar navigation in component page (#6709)
• Add component ID and package name in component overview (#6698)
• Keep workspace command history .bit/command-history (#6658)
• Ability to view contents of non-binary artifact files (#6597, #6623)
• Extract component Typescript schema (#6578, #6624, #6620)
• Ability for 3-way merge of aspects config (#6791)
• Support setting default bit registry in global config (#6807)
• Introduce --internal flag to see the private commands (#6725)
• Ability to version component on remote and control what to update (#6676, #6602, #6672)
• Ability to check whether a lane is up to date (#6666)
• Ability to checkout --entire-lane to get new components on a lane (#6661)
• Support tracking files that starts with . (#6757)
• Allow to skip compilation step when installing dependencies (#6687)
• Ability to remove dependency of a specific type (#6625)
• Support latest for checking-out the "tip" of component version history (#6619)
• Ability to toposort components according to dependencies build order (#6701)
• Ability to create and delete lanes from GQL (#6656)
• Get lane diff via API (#6759)

Changes

• fix(tag): use pre-release for auto-tag as well instead of patch (#6763)
• Show all changes when comparing between lanes (#6817)
• When no diff is visible, suggest --verbose option (#6752)
• Update typescript to 4.7.4 (#6603)
• Update core teambit.react/react to set allowJs: true by default (#6734)
• Tester watch on start is set to false by default (#6747)
• Print install and import duration, suppress object-count on ci (#6726)
• Support --json output option for merge-lane flow (#6654)
• List remote lanes (#6736)
• Mocha tester to support typescript (#6621)
• Add hash to the create-lane API (#6815)
• Ability to skip UI build on bit start (#6634)

Bug Fixes

• Better handling when fetching artifacts (#6751, #6776)
• Add guard rails for bit dep set when adding a missing dependency (#6702)
• Fix case when direct dependencies got duplicated (#6711)
• Fix converting graph to ComponentGraph for handle runtime edges correctly (#6833)
• Remove previous env even when not in the .bitmap (#6828)
• Fix component id resolution from URL (#6821)
• Ignore removed components when checking for MissingManuallyConfiguredPackages (#6814)
• Better error when a command is running outside a workspace (#6806)
• Avoid removing deps that were set before tag/snap (#6805)
• Avoid showing duplicate MissingManuallyConfiguredPackages entries (#6812)
• Recompile components with build-status failed (#6786)
• Update links to command outputs to docs (#6605)
• Load extensions only once after merging from different sources (#6769)
• Handle log cases where missing entry were not imported (#6697)
• Fix cases where import didn't pay attention to current lane (#6801)
• UI fixes for viewing lanes (#6714)
• Dist directories should not be removed after install (#6662)
• UI fixes for usebox (#6783)
• Bug fixes and edge cases around lanes merge (#6692, #6831, #6829, #6826, #6823, #6822, #6767, #6793, #6794, #6803, #6735, #6667)
• Remove the undefined in bit-list header when using --scope flag (#6627)
• bit rename --refactor to change only packages that have an exact match (#6618)
• Fix a typos in command descriptions (#6640)
• Fix rendering of lane selector when viewed lane changes (#6724)
• Fix determine whether a component is new based also on .bitmap record (#6655)
• Avoid overriding dependencies set before tag/snap (#6696)
• bit status should not show missing deps incorrectly (#6710)
• Remove stagedConfig for all exported components (#6732)
• Avoid showing mocha tests output during bit-start (#6680)
• Fix reset when the component is diverged on lane and has no head on main (#6678)
• Avoid sending historical Version objects during export on lane (#6690)
• pass pnpUnpluggedFolder to fix error on yarn install (#6834)
• Filter out soft-removed from --entire-lane flag (#6713)
• Avoid creating two instances of scope.repository after bit-cc (#6718)
• Hoisting should not override linked components (#6788)
• Don't rerun install for the same manifests again (#6755)
• Fix missing scope-name in flattened-edge prop (#6774)
• Resolve env-id correctly (#6632)
• EnvNotConfiguredForComponent error to suggest running bit env set (#6601)

Performance

• Improve import performance by fetching only the requested version (#6639)
• Avoid fetching flattened dependencies (#6705)
• Improve lane diff performance (#6799)
• Yarn should use a content-addressable store (#6730)
• Make history traversal faster by caching them in the fs (#6606)
• Improve build-graph-from-fs performance by not trying to import existing deps (#6612)
• Support Yarn global cache (#6717, #6729)
• Avoid fetching flattened-deps when possible (#6785)
• Get env preview data on load (#6616)

Internal

• Prepare and stabilize rootComponents (#6750, #6782, #6631, #6675, #6691, #6688)
• Prepare and stabilize envs as plugins (#6745, #6644, #6739, #6811, #6703, #6816, #6780, #6766, #6742, #6693)
• Prepare and stabilize lane-compare (#6704, #6777, #6733. #6677, #6657, #6651)
• Utilize the deps graph when possible (#6775)
• Update babel packages to latest (#6604)
• Upgrade pino (#6797)
• Remove prodGraph prop from get-flattened-dependencies (#6728)
• Utilize pino transport (Worker Thread) (#6798)
• Update harmony version (#6781)
• add default export to core aspects (#6694, #6779)
• updated component highlighter not to use z-indexs component (#6808)
• remove unnecessary code from component overview (#6699)
• Update lint and prettier rules (#6741, #6740)
• Avoid running mutliple on-start hooks in parallel (#6795)
• Use BitError and not legacy error handler for VersionNotFound (#6638)
• Remove export-metadata, it is not needed anymore (#6758)
• Sync deps for component compare (#6773)
• Avoid loading cli aspect twice (#6719)
• Handle failures inside Mocha hooks (#6753)
• Filter teambit/legacy from root policy (#6649)
• Express route priority type (#6636)
• Get the tsconfig from getCompiler API when possible (#6663)
• Support variant config policy as array of object with name, version, hidden, force (#6810)
• Handle loading aspect-root without a version (#6765)
• Better logs around the removal of staged-config during export (#6715)
• Use named export from aspect when generating link file for webpack (#6754)