evocateur / pectin

Rollup-related tools for incremental transpilation of packages in Lerna-based monorepos

Pectin

Rollup-related tools for incremental transpilation of packages in Lerna-based monorepos

Getting Started

The easiest way to start using Pectin is to install the CLI and run it during an npm lifecycle, such as "prerelease":

npm i -D pectin

In your monorepo's root package.json (aka "manifest"):

{
    "scripts": {
        "clean": "git clean -fdx packages",
        "prerelease": "npm run clean && pectin",
        "release": "lerna publish",
        "lint": "eslint .",
        "pretest": "pectin && npm run lint",
        "test": "jest"
    }
}

Configured 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.

Once installed locally, you can experiment with the CLI via npx:

npx pectin -h

To watch packages and rebuild on source change, pass -w, just like Rollup's CLI:

npx pectin -w

Motivation

One 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.

Running 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.

For 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).

Pectin'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.

Contributing

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Packages

• @pectin/api
• @pectin/babelrc
• @pectin/core
• pectin
• rollup-config-pectin
• rollup-plugin-main-entry
• rollup-plugin-subpath-externals

Customizing Plugins

When calling the pectin CLI, there is no support for adding plugins beyond those already included. However, 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.

First, create a rollup.config.js in the root of your monorepo:

import * as path from 'path';
import { findConfigs } from '@pectin/api';
import visualizer from 'rollup-plugin-visualizer';

export default findConfigs().then(configs =>
    configs.map(cfg => {
        const {
            // format can be 'cjs', 'esm', or 'umd'
            format,
            // absolute directory from pkg.main,
            // e.g. '<root>/packages/<pkg>/dist'
            dir: outputDir,
        } = cfg.output[0];

        // plugins are assigned per-format, as certain
        // formats require different plugin configuration
        if (format === 'esm') {
            cfg.plugins.push(
                visualizer({
                    filename: path.join(outputDir, 'stats.html'),
                })
            );
        }

        return cfg;
    })
);

Then change any references to pectin in your npm scripts to rollup -c:

{
    "scripts": {
        "build": "rollup -c || echo 'no changed packages to build, probably?'",
        "watch": "rollup -c -w"
    }
}

The 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.

Ignoring Packages

If you have a package that you do not want Pectin to build, you can add the following to its package.json:

"rollup": {
    "skip": true
}

Related

• Lerna
• Rollup

pectin's Issues

Support for code splitting

With --experimentalCodeSplitting, rollup will output multiple files when you use dynamic import. Currently, the code splitting target has to be a separate package or it'll just get inlined.

Can that flag be enabled, or should it wait until rollup 1.0 lands?

I tested this locally and it does correctly create multiple files within a package. I'm not sure how it'll work in commonjs-land, but rollup 1.0 makes code splitting on by default so it'll have to work if we want to upgrade to that.

Needs better documentation

Or at the very least an example lerna project

`babel.config.js` is not supported

having a babel.config.js at the root of the monorepo like so

module.exports = function (api) {
  api.cache(true);

  const presets = [ ... ];
  const plugins = [ ... ];

  return {
    presets,
    plugins
  };
}

results in the following errors

Error: At least one preset (like @babel/preset-env) is required in ../../babel.config.js

pectin assumes that babel.config.js will be written as so

module.exports = {
	presets: [ ... ],
};

An option for outputing Rollup error

Is it possible to provide a argument flag that output errors from rollup instead of the
"pectin info skipping packages unchanged since last build" message.

I know there is a TODO on that piece of code, but just checking in case there is alternative.

Feature Request: source map option

Just documenting our conversation, but it would be nice as a consumer of pectin packages to have source maps available locally.

Support for babel `env option`

I'm in a case where tests and source code are both using imports (ES6 syntax). pectin wants modules to be set to false while mocha want them to be true.
Babel supports multiple envs in the babelrc config file, so supporting it in pectin would be great.

I'm currently using node v13.10.1, babel 6 and pectin ^3.6.1

PS: any other suggestions for me to do this in a "better" way are also welcome 😊

.babelrc file

{
  "env": {
    "test": {
      "presets": [
        [
          "env",
          {
            "targets": {
              "node": "current"
            }
          }
        ]
      ]
    },
    "build": {
      "presets": [
        [
          "env",
          {
            "modules": false,
            "targets": {
              "node": "current"
            }
          }
        ]
      ]
    }
  }
}

sample app.js

export function foo () {
    return 'bar'
}

sample test.spec.js

import { foo } from '../src/app'

describe('testing app', () => {
    it('should return bar', function () {
        expect(foo()).to.deep.equal('bar')
    })
})

mocha.opts

--require babel-core/register
--require babel-register
--require test/setup.js
--recursive

source: https://babeljs.io/docs/en/6.26.3/babelrc

Support for babel@7

Hi 👋,

Babel v7.0.0 (stable) just got released, it would be nice to support it.
You can find migration instructions here: https://babeljs.io/docs/en/v7-migration

Thank you!