JSPM – techor@2.1.15

Package Exports

techor

Readme

Author technology like a top leader

Features

Support multi-format JavaScript module configuration import like master.css.{js,mjs,cjs,ts}
Ability to import ESM or Typescript modules in a CommonJS environment
Support for deep configuration extensions
Independent compilation options and user configuration

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

npm i techor

First, define your Options and Config:

import type { Options as TechorOptions } from 'techor'

interface Options extends TechorOptions<Config> {
    ...
}

interface Config {
    ...
}

Usage

import Techor from 'techor'

Create a techor instance

const techor = new Techor<Options, Config>()

Extend the Techor

const defaultOptions = {}

class MyTech extends Techor<Options, Config> {
    constructor (
        options: Options
    ) {
        super(defaultOptions, options)
    }
    ...
}

Properties

Read user config file by `options.config`

readConfig(): Config

Get user config path

get configPath(): string

Get resolved user config path

get resolvedConfigPath(): string

Setup

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

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

Install CLI and core packages by techor:

npm i techor -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.

techor pack [entryPaths...]

Check out the available options here for now

techor 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.js
+        │    ├─── 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": "tsx ../techor/src/bin 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": "tsx ../techor/src/bin 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

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

techor src/**/*.ts

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

The same goes for multiple CSS entries:

techor 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

techor 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": "^2.0.0-beta.7"
    },
    "devDependencies": {
        "@master/css.webpack": "^2.0.0-beta.55"
    }
}

Run with the above setup:

techor 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 techor pack will not exclude it.

Multiple outputs

techor 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.js
+        │    ├─── 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.

techor 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:

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

turborepo-excalidraw

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": "tsx ../techor/src/bin 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, techor builds a complete package release workflow and the tools needed during it.

Next, check out the Aron's semantic release

techor