aronrepo

A monorepo ecosystem integrating first-class packages and build systems

Features

Monorepo

• Using a high-performance build system —— Turborepo
• Run the build, dev, test, lint commands across all workspaces
• Remember what you've built and skip the stuff that's already been computed
• Multiple workspaces work simultaneously, just like one workspace used to.

Packing

• An extremely fast bundler built on top of esbuild
• Output or watch multiple formats in one-linear command
• Support ESM, CJS, and IIFE JavaScript modules
• Support CSS bundle
• Generate .d.ts type declarations
• Extract options from package.json
• Prevent bundling dependencies and peerDependencies by package.json

Versioning

• Synchronize versions of packages in all workspaces
• Bump packages to a specific version by the .workspaces of package.json
• Bump versions by analyzing dependencies and peerDependencies of the workspace
• Prevent bumping versions for private: true packages

Getting Started

Add packages/** to .workspaces of the root ./package.json

{
    "workspaces": [
        "packages/**"
    ]
}

Install CLI and core packages by aronrepo:

npm i aronrepo -D

• Requires npm@>=7 when using npm
• Set auto-install-peers when using pnpm
• You can also manually install peerDependencies for fixed versions

To create your first package, you may automate the required steps to define a new workspace using npm init.

npm init -w ./packages/a

When the package is ready, including the dependencies setup, run npm i in the project root directory to install all dependencies, including the workspaces.

Pack

Bundling your TypeScript and CSS packages with zero configuration.

aron pack [entryPaths...]

Check out the available options here for now

aron pack analyzes the package.json entry point relative to input sources in the src directory for builds.

JavaScript packages

.
├── package.json
└── packages
    └─── a
         ├─── src
         │    ├─── index.ts
         │    └─── index.browser.ts
+        ├─── dist
+        │    ├─── index.cjs
+        │    ├─── index.mjs
+        │    ├─── index.d.ts
+        │    └─── index.browser.ts
         └─── package.json

Simultaneously output cjs, esm, iife, type declarations respectively according to main, module, browser, types of package.json

{
    "name": "a",
    "scripts": {
        "build": "aron pack",
        "dev": "npm run build -- --watch"
    },
    "main": "dist/cjs/index.js",
    "browser": "dist/index.browser.js",
    "module": "dist/esm/index.js",
    "types": "dist/index.d.ts",
    "jsnext:main": "dist/esm/index.js",
    "esnext": "dist/esm/index.js",
    "exports": {
        ".": {
            "require": "./dist/cjs/index.js",
            "import": "./dist/esm/index.js",
            "types": "./dist/index.d.ts"
        }
    },
    "files": [
        "dist"
    ]
}

If you only want to pack specific javascript modules, remove the corresponding entry point from package.json.

Run with the above configuration:

npm run build

Now import the above package a in your project or publish it.

import 'a'

CSS packages

.
├── package.json
└── packages
    └─── b
         ├─── src
         │    └─── index.css
+        ├─── dist
+        │    └─── index.css
         └─── package.json

Packaging CSS is more straightforward, configuring style and main entry points in package.json.

{
    "name": "b",
    "scripts": {
        "build": "aron pack",
        "dev": "npm run build -- --watch"
    },
    "main": "./dist/index.css",
    "style": "./dist/index.css",
    "files": [
        "dist"
    ]
}

Run with the above configuration:

npm run build

Now import the above package b in your project or publish it.

@import 'b'

Multiple entry points

aron pack <entryPaths...> supports glob patterns that let you specify multiple entry points at once, including the output of nested directories.

Specifying an entry point will cause the JavaScript output format to be preset to cjs,esm.

aron src/**/*.ts

.
├── package.json
└── packages
    └─── a
         ├─── src
         │    ├─── index.ts
         │    └─── utils
         │         └─── exec.ts
+        ├─── dist
+        │    ├─── index.cjs
+        │    ├─── index.mjs
+        │    └─── utils
+        │         ├─── exec.cjs
+        │         └─── exec.mjs
         └─── package.json

The same goes for multiple CSS entries:

aron src/**/*.css

.
├── package.json
└── packages
    └─── a
         ├─── src
         │    ├─── index.css
         │    └─── components
         │         ├─── card.css
         │         └─── button.css
+        ├─── dist
+        │    ├─── index.css
+        │    └─── components
+        │         ├─── card.css
+        │         └─── button.css
         └─── package.json

Usually, it would be best to bundle CSS packages through a main index.css and output other CSS files so developers can import on demand instead of the whole package. For example @master/keyframes.css

Exclude external dependencies

aron pack automatically excludes external dependencies to be bundled by the .dependencies and peerDependencies of package.json

src/index.ts

import '@master/css'
import '@master/css.webpack'
import '@master/style-element.react'

package.json

{
    "name": "externals",
    "main": "dist/cjs/index.js",
    "exports": {
        ".": {
            "require": "./dist/cjs/index.js"
        }
    },
    "files": [
        "dist"
    ],
    "dependencies": {
        "@master/css": "^2.0.0-beta.55"
    },
    "peerDependencies": {
        "@master/style-element.react": "^1.1.6"
    },
    "devDependencies": {
        "@master/css.webpack": "^2.0.0-beta.55"
    }
}

Run with the above setup:

aron pack --platform node

@master/css.webpack is bundled into dist/cjs/index.js, except for @master/css and @master/style-element.react.

So if there is an external package that needs to be bundled, you just install it to devDependencies via npm i <some-package> --save-dev, then aron pack will not exclude it.

Multiple outputs

aron pack defaults to pack multiple outputs with different formats and platforms according to exports bin in package.json.

.
├── package.json
└── packages
    └─── a
         ├─── src
         │    ├─── index.ts
         │    └─── utils
         │         └─── exec.ts
+        ├─── dist
+        │    ├─── index.cjs
+        │    ├─── index.mjs
+        │    └─── utils
+        │         ├─── exec.cjs
+        │         └─── exec.mjs
         └─── package.json

package.json

{
    "name": "externals",
    "exports": {
        ".": {
            "require": "./dist/cjs/index.js",
            "import": "./dist/esm/index.js"
        },
        "./utils/exec": {
            "require": "./dist/utils/exec.cjs",
            "import": "./dist/utils/exec.mjs"
        }
    }
}

Any nested conditions in exports like node, browser, default, require, and import will be mapped to ESBuild’s format and platform options.

Version

Smartly bump all workspace-dependent packages to specific versions.

aron version <version>

Check out the available options here for now

The command automatically bumps the version of all packages by scanning all workspaces and analyzing dependencies and peerDependencies of package.json

.
├── package.json
└── packages
    ├─── a
    |    └─── package.json
    ├─── b
    |    └─── package.json
    └─── c
         └─── package.json

This command scans all workspaces for dependencies with unspecified versions "" considered a project package, then replaces them with the next version.

Now bump all dependent and workspace packages to a specified version:

aron version 1.2.0

packages/a/package.json

{
    "name": "a",
+   "version": "^1.2.0",
    "dependencies": {
-       "b": "",
+       "b": "^1.2.0"
    }
}

packages/b/package.json

{
    "name": "b",
+   "version": "^1.2.0"
}

packages/c/package.json

{
    "name": "c",
+   "version": "^1.2.0",
    "peerDependencies": {
-       "a": "",
+       "b": "^1.2.0"
    }
}

For version range, check out the semver

Typically, you would use Aron's semantic release with CI to automate the version and release commands.

Build system for monorepo

Most workspace packages will pre-set script commands, such as build, test, and lint. Since features depend on each other, builds will be executed sequentially.

You can now use Turborepo to easily build complex systems and run commands in one-linear.

Set up the /turbo.json:

{
    "$schema": "https://turbo.build/schema.json",
    "pipeline": {
        "dev": {
            "cache": false,
            "dependsOn": ["^build"]
        },
        "build": {
            "dependsOn": ["^build"],
            "outputs": ["dist/**"]
        },
        "test": {
            "outputs": [],
            "inputs": [
                "src/**/*.tsx",
                "src/**/*.ts",
                "tests/**/*.ts"
            ]
        },
        "lint": {
            "outputs": []
        },
        "type-check": {
            "outputs": ["dist/**"]
        }
    }
}

Set up the scripts of /package.json:

{
    "scripts": {
        "dev": "turbo run dev",
        "build": "turbo run build",
        "test": "turbo run test --parallel",
        "lint": "turbo run lint --parallel",
        "type-check": "turbo run type-check --parallel"
    }
}

In most cases, dev and build cannot add the --parallel flag, which breaks their dependencies.

Typical workspace scripts for authoring a package:

{
    "scripts": {
        "build": "aron pack",
        "dev": "npm run build -- --watch",
        "test": "jest",
        "type-check": "tsc --noEmit",
        "lint": "eslint src"
    }
}

From now on, you only need to run the command in the project root after opening the project.

npm run dev

Build your application or package:

npm run build

Test your business logic or UI by running scripts:

npm run test

Find and fix problems in JavaScript code before building:

npm run lint

Improve reliability with TypeScript's type checking:

npm run type-check

Continuous Integration

With the well-configured build system, almost all commands can be automated through CI, taking GitHub Actions as an example:

Build automated tests on the beta, the main, and the pull request stream:

name: Test
on:
    push:
        branches:
            - main
            - beta
    pull_request_target:
        types:
            - opened
            - synchronize

jobs:
    version:
        timeout-minutes: 15
        runs-on: ubuntu-20.04
        strategy:
            matrix:
                node-version: [18.12.1]
        steps:
            - uses: actions/checkout@v3
            - uses: actions/setup-node@v3
              with:
                  node-version: ${{ matrix.node-version }}
                  cache: 'npm'
            - run: npm ci
            - run: npm run build
            - run: npm run test

The same goes for lint and type-check.

While the build command will work with deploy and release, aronrepo builds a complete package release workflow and the tools needed during it.

Next, check out the Aron's semantic release