{"id":16646519,"url":"https://github.com/evocateur/pectin","last_synced_at":"2025-03-16T22:31:53.723Z","repository":{"id":32935141,"uuid":"146944533","full_name":"evocateur/pectin","owner":"evocateur","description":"Rollup-related tools for incremental transpilation of packages in Lerna-based monorepos","archived":false,"fork":false,"pushed_at":"2023-01-04T21:38:42.000Z","size":6031,"stargazers_count":58,"open_issues_count":20,"forks_count":7,"subscribers_count":1,"default_branch":"latest","last_synced_at":"2024-10-19T04:44:11.486Z","etag":null,"topics":["cli","lerna","monorepo","rollup","rollup-plugin"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evocateur.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-08-31T21:38:28.000Z","updated_at":"2024-04-26T18:30:05.000Z","dependencies_parsed_at":"2023-01-14T22:45:30.803Z","dependency_job_id":null,"html_url":"https://github.com/evocateur/pectin","commit_stats":null,"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evocateur%2Fpectin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evocateur%2Fpectin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evocateur%2Fpectin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evocateur%2Fpectin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evocateur","download_url":"https://codeload.github.com/evocateur/pectin/tar.gz/refs/heads/latest","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221668784,"owners_count":16860728,"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":["cli","lerna","monorepo","rollup","rollup-plugin"],"created_at":"2024-10-12T08:27:56.061Z","updated_at":"2024-10-27T11:29:40.024Z","avatar_url":"https://github.com/evocateur.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pectin\n\n\u003e [Rollup][]-related tools for incremental transpilation of packages in [Lerna][]-based monorepos\n\n[![npm version](https://img.shields.io/npm/v/pectin.svg)](https://www.npmjs.com/package/pectin)\n[![Build Status](https://travis-ci.org/evocateur/pectin.svg?branch=latest)](https://travis-ci.org/evocateur/pectin)\n\n## Getting Started\n\nThe easiest way to start using Pectin is to install the CLI and run it during an npm lifecycle, such as `\"prerelease\"`:\n\n```sh\nnpm i -D pectin\n```\n\nIn your monorepo's root `package.json` (aka \"manifest\"):\n\n```json\n{\n    \"scripts\": {\n        \"clean\": \"git clean -fdx packages\",\n        \"prerelease\": \"npm run clean \u0026\u0026 pectin\",\n        \"release\": \"lerna publish\",\n        \"lint\": \"eslint .\",\n        \"pretest\": \"pectin \u0026\u0026 npm run lint\",\n        \"test\": \"jest\"\n    }\n}\n```\n\nConfigured this way, you can always ensure your packages have the latest build output whenever anyone executes `npm run release` _or_ incrementally build recent changes before `npm test`.\n\nOnce installed locally, you can experiment with the CLI via `npx`:\n\n```sh\nnpx pectin -h\n```\n\nTo watch packages and rebuild on source change, pass `-w`, just like Rollup's CLI:\n\n```sh\nnpx pectin -w\n```\n\n## Motivation\n\nOne advantage of a [Lerna][] monorepo is that you can reduce the amount of repetition between modules by running all development-related tasks (build, lint, test, and so on) from the root of the repository instead of each package one-by-one. This works fine for tools that are capable of running over many packages simultaneously without breaking a sweat, like `jest` and `eslint`.\n\nRunning Rollup builds over many different package roots, however, is a much trickier business. Pectin was built to facilitate running Rollup builds for all packages in a monorepo, with special consideration for unique monorepo circumstances such as incremental builds, npm lifecycle behavior, and per-package options.\n\nFor example, it isn't always the case that _every_ package in a monorepo actually needs to be rebuilt every time the build is run. Consider running `jest --watch` in a monorepo with 15 packages, but you're only working on one. The naïve approach finds all the packages and passes all of them to Rollup, which means Rollup builds for every package. Pectin optimizes this by testing the \"freshness\" of the built output against the source tree and only building when a file in the source tree has a more recent change (a higher `mtime`, for filesystem wizards).\n\nPectin's CLI was written to seamlessly wrap `rollup`. It helps avoid, among other things, Rollup's CLI emitting a warning and exiting non-zero when you pass an empty array (that is, no changes since the last build) to Rollup via the default export of `rollup.config.js`. Pectin's CLI supports all options supported by Rollup's CLI.\n\n## Contributing\n\nPlease note that this project is released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.md).\nBy participating in this project you agree to abide by its terms.\n\n## Packages\n\n-   [`@pectin/api`](./packages/pectin-api#readme)\n-   [`@pectin/babelrc`](./packages/pectin-babelrc#readme)\n-   [`@pectin/core`](./packages/pectin-core#readme)\n-   [`pectin`](./packages/pectin#readme)\n-   [`rollup-config-pectin`](./packages/rollup-config-pectin#readme)\n-   [`rollup-plugin-main-entry`](./packages/rollup-plugin-main-entry#readme)\n-   [`rollup-plugin-subpath-externals`](./packages/rollup-plugin-subpath-externals#readme)\n\n## Customizing Plugins\n\nWhen calling the `pectin` CLI, there is no support for adding plugins beyond those already included.\nHowever, as `pectin` is _mostly_ just a fancy wrapper around the `rollup` CLI, it is possible to generate Rollup config programmatically and simulate the \"lazy build\" behavior of `pectin`.\n\nFirst, create a `rollup.config.js` in the root of your monorepo:\n\n```js\nimport * as path from 'path';\nimport { findConfigs } from '@pectin/api';\nimport visualizer from 'rollup-plugin-visualizer';\n\nexport default findConfigs().then(configs =\u003e\n    configs.map(cfg =\u003e {\n        const {\n            // format can be 'cjs', 'esm', or 'umd'\n            format,\n            // absolute directory from pkg.main,\n            // e.g. '\u003croot\u003e/packages/\u003cpkg\u003e/dist'\n            dir: outputDir,\n        } = cfg.output[0];\n\n        // plugins are assigned per-format, as certain\n        // formats require different plugin configuration\n        if (format === 'esm') {\n            cfg.plugins.push(\n                visualizer({\n                    filename: path.join(outputDir, 'stats.html'),\n                })\n            );\n        }\n\n        return cfg;\n    })\n);\n```\n\nThen change any references to `pectin` in your npm scripts to `rollup -c`:\n\n```json\n{\n    \"scripts\": {\n        \"build\": \"rollup -c || echo 'no changed packages to build, probably?'\",\n        \"watch\": \"rollup -c -w\"\n    }\n}\n```\n\nThe caveat highlighted by the `||` alternation above is that `rollup` will complain if the array generated by `findConfigs()` is empty, and exits non-zero. Unless caught by the `||`, `npm run build` would exit with an error.\n\n## Ignoring Packages\n\nIf you have a package that you do not want Pectin to build, you can add the following to its `package.json`:\n\n```json\n\"rollup\": {\n    \"skip\": true\n}\n```\n\n## Related\n\n-   [Lerna][]\n-   [Rollup][]\n\n[lerna]: https://github.com/lerna/lerna#readme\n[rollup]: https://github.com/rollup/rollup#readme\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevocateur%2Fpectin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevocateur%2Fpectin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevocateur%2Fpectin/lists"}