aronrepo

A monorepo ecosystem integrating first-class packages and conventional workflows

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

Versing

• 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/index.cjs",
    "browser": "dist/index.browser.js",
    "module": "dist/index.mjs",
    "types": "dist/index.d.ts",
    "jsnext:main": "dist/index.mjs",
    "esnext": "dist/index.mjs",
    "exports": {
        ".": {
            "require": "./dist/index.cjs",
            "import": "./dist/index.mjs",
            "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
+        │    ├─── index.d.ts
+        │    └─── utils
+        │         ├─── exec.cjs
+        │         ├─── exec.mjs
+        │         └─── exec.d.ts
         └─── 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/index.cjs",
    "exports": {
        ".": {
            "require": "./dist/index.cjs"
        }
    },
    "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/index.cjs, 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.

Version

Smartly bump packages to specific versions by the .workspaces of the root package.json.

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 identifies whether it is a package in the workspace by scanning packages of the workspace and its dependencies that don't specify a version "", and replaces "" 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"
    }
}

Typically, you would use semantic-release-aron 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.

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

npm run dev

npm run build

npm run test

npm run lint

npm run type-check

Automation