{"id":13727142,"url":"https://github.com/acao/yarn-compose","last_synced_at":"2025-04-14T17:48:28.489Z","repository":{"id":34902470,"uuid":"187795050","full_name":"acao/yarn-compose","owner":"acao","description":"🦑 orchestrate node projects and linkages without a monorepo","archived":false,"fork":false,"pushed_at":"2023-01-03T22:53:35.000Z","size":1177,"stargazers_count":20,"open_issues_count":30,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-14T17:48:10.778Z","etag":null,"topics":["git","lerna","node-js","nodejs-modules","npm","yarn"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acao.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["acao"]}},"created_at":"2019-05-21T08:30:13.000Z","updated_at":"2024-11-06T21:57:03.000Z","dependencies_parsed_at":"2023-01-15T10:07:39.818Z","dependency_job_id":null,"html_url":"https://github.com/acao/yarn-compose","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acao%2Fyarn-compose","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acao%2Fyarn-compose/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acao%2Fyarn-compose/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acao%2Fyarn-compose/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acao","download_url":"https://codeload.github.com/acao/yarn-compose/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248930785,"owners_count":21185084,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["git","lerna","node-js","nodejs-modules","npm","yarn"],"created_at":"2024-08-03T01:03:41.363Z","updated_at":"2025-04-14T17:48:28.434Z","avatar_url":"https://github.com/acao.png","language":"TypeScript","funding_links":["https://github.com/sponsors/acao"],"categories":["TypeScript"],"sub_categories":[],"readme":"[![npm version](https://badge.fury.io/js/yarn-compose.svg)](https://badge.fury.io/js/yarn-compose)\n[![Build Status](https://travis-ci.com/acao/yarn-compose.svg?branch=master)](https://travis-ci.com/acao/yarn-compose?branch=master)\n[![Coverage Status](https://codecov.io/gh/acao/yarn-compose/branch/master/graph/badge.svg)](https://codecov.io/gh/acao/yarn-compose)\n\n# 🦑 polyrepo development for the rest of us 🦑\n\nA simple utility to orchestrate node projects using git and yarn link.\n\nHandy for multi-repo projects that require development with disparate branches.\n\nFor orchestrating npm/yarn monorepos, see lerna or yarn workspaces.\n\nMany more features coming soon. This takes care of the annoying parts for me.\n\nThis was primarily created to make it easier for me to iterate on language features for the graphql ecosystem. I hope it serves you well. Be sure to create a github issue if you need anything!\n\n# System Requirements\n\n- git (windows git bash will probably work, create an issue if it doesnt please!)\n- yarn (eventually will support a mix of npm/yarn projects)\n- node 10 or higher\n# Setup\n\n`yarn global add yarn-compose`\n\n# Usage\n\n1. create a projects.yml file\n1. run `yarn-compose setup` in the same directory\n1. or, run `yarn-compose setup -c path/to/config.yml`\n1. also, you can override `baseDir` with `--target` or `-t`\n1. other commands are `rebuild` and `relink` with the same arguments (see below)\n1. `--help` works for each command\n\n# Config File\nYou'll want to provide a yml file with at least some basic configuration for linking your projects.\n\n- `baseDir`: (optional, string) this can be provided via CLI or in the config file. you must provide it one way or the other.\n\n- `typeDefs`: (optional) is an object with string keys that are used by the `types` array for each project. used for DefinatelyTyped but could also be used for flow-typed. if you have a one off repo with types, that might be easier to use below.\n  - `remote`: (required, string) git or https url to the remote that contains typings\n  - `branch`: (required, string) the branch or ref of the repo you want\n  - `typesPath`: (required, string) path to the types you want. `types/\u003ctypename\u003e` for DefinatelyTyped, for example\n  - `depth`: (optional, integer) - default: `1` - the clone depth you want. because DefinatelyTyped is YUGE\n\n- `projects` (required) is an array of:\n  - `package`: (required, string) the name of the npm package\n  - `remote`: (required, string) the git or https url to the remote (https://github.com/acao/graphql-import)\n  - `branch`: (required, string) the name of the branch (or other ref, `tag/v0.x`, commit hashes etc should work here too)\n  - `types`: (optional, string[]) - matches the typeDef keys, for creating symlinks\n  - `links`: (optional, string[]) - an array of packages that this project should be linked to. you will probably need this for most projects\n  - `lerna`: (optional, boolean) - default: false - whether this is a lerna project. if so, `lerna build` will be run instead of `yarn build`, and linkages will be handled for all subprojects using `lerna exec -- yarn link \u003cprojects\u003e`\n  - `buildScript`: (optional, string) - default: `build` custom value for the script used before linking.\n  - `npmClient`: (optional, default: `yarn`) - specify a different npmClient (`yarn`, `npm` or `cnpm`) for this project's script execution. \n    - Note: in my experience, linking between npm/yarn projects is messy. good luck!\n  - `linkFrom:`: (optional, string) - path to link from, if not the project root. this was needed for graphql-js\n\nNOTE: the order of the projects array determines execution for building/linkages/etc. \n\nThe example below demonstrates the descending order of dependencies. The lowest level dependents should go first, with their dependees following.\n\nEventually these will work like docker-compose services, where the order of operations will be determined by the `links` array. Until then, this CLI is intended to be really unintelligent on purpose.\n\n# Commands\n\n## Global Options\n\nThese are available to all commands\n\n`--config-path`, `-c`\n\nthe explicit path to the config file\n\n`--base-dir`, `-t`\n\nthe path to the base directory\n\n## `setup`\nsets up project workspace, clones and installs projects, type definitions, builds and links dependencies\n\n### Usage\n\nexpects projects.yml by default\n\n```$ yarn-compose setup```\n\nor, specify a path to a config file\n\n```$ yarn-compose setup -c path/to/config.yml```\n\n### Options\n`--force`, `-f`\n\nforce install\n\n## `rebuild`\nre-builds all projects in order\n\n### Usage\n```$ yarn-compose rebuild -c path/to/config.yml```\n\n## `relink`\nre-links all projects in order, assuming symlinks have already been built\n\n### Usage\n```$ yarn-compose relink -c path/to/config.yml```\n\n# Config Example\n\n```yml\nbaseDir: './lab'\n\ntypedefs:\n  graphql:\n    remote: git@github.com:acao/DefinitelyTyped.git\n    branch: graphql-inputUnion\n    typesPath: types/graphql\n\nprojects:\n  - package: graphql\n    remote: https://github.com/tgriesser/graphql-js\n    branch: inputUnion\n\n  - package: graphql-import\n    remote: https://github.com/acao/graphql-import\n    branch: inputUnion\n    buildScript: build\n    types:\n      - graphql\n    links:\n      - graphql\n\n  - package: graphql-config\n    remote: https://github.com/prisma/graphql-config\n    branch: master\n    types:\n      - graphql\n    links:\n      - graphql\n      - graphql-import\n\n  - package: graphql-language-service\n    lerna: true\n    remote: https://github.com/acao/graphql-language-service\n    branch: inputUnion\n    links:\n      - graphql\n      - graphql-config\n      - graphql-import\n      - graphql-language-service-parser\n      - graphql-language-service-interface\n      - graphql-language-service-types\n      - graphql-language-service-utils\n\n  - package: codemirror-graphql\n    branch: inputUnion\n    remote: https://github.com/acao/codemirror-graphql\n    links:\n      - graphql\n      - graphql-language-service-parser\n      - graphql-language-service-interface\n      - graphql-language-service-types\n      - graphql-language-service-utils\n      - graphql-config\n      - graphql-import\n\n  - package: graphiql\n    branch: inputUnion\n    remote: https://github.com/acao/graphiql\n    links:\n      - graphql\n      - codemirror-graphql\n      - graphql-language-service-parser\n      - graphql-language-service-interface\n      - graphql-language-service-types\n      - graphql-language-service-utils\n      - graphql-config\n      - graphql-import\n```\n\n# FAQ\n\n### Why not use lerna or yarn workspaces?\n\nThis is more for orchestrating development environments than anything. Not for building permanent ecosystems like a monorepo would be. That said, lerna could still be used for ephemeral demos, etc, however using npm or yarn for managing fully working git repositories is almost impossible! This takes care of setting up a development environment with the assumption that you might need to work from git forks and feature branches across an entire ecosystem of projects.\n\n### Some of the errors look messy\n\nYes, currently I'm just throwing/logging out the formatted stderr from `execa`. Thinking maybe a --verbose flag could provide more detail if needed.\n\n### Should this be used in production?\n\nNo! Symlinking in production environments can be very insecure with node. This should be used for local development only. It could also be used in CI to, say, build a series of complex feature branches before the dist is deployed. This is not designed for setting up a production environment.\n\n### Is this project related to `docker-compose`?\n\nYes, the config file format is inspired by docker compose, as well as the obsession with linkages. It's not nearly as smart as docker compose though.\n\n# TODO\n- [ ] more examples! (please contribute in gh issues if you can!)\n- [X] support npm, cnpm, etc? \n- [ ] meteor, bower even? if folks want?\n- [ ] allow a `--projects` flag to target specific project(s) for each command\n- [ ] support configuring multiple remotes per project\n- [ ] support changing remotes, branches, etc more readily/passively\n- [ ] other features users ask for?\n- [ ] \"discover\" lerna, npmClient, etc\n- [ ] support other config formats\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facao%2Fyarn-compose","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facao%2Fyarn-compose","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facao%2Fyarn-compose/lists"}