@iyio/package-hub v1.1.0

pkhub

A tool to simplify typescript package sharing in mono-repos and packages outside of a project's root directory

What does pkhub do?

pkhub allows you to develop npm packages while using them in other projects. pkhub is similar to npm link but does not rely on symlinks. With pkhub you can use code outside of the root of a projects directory and preserve code navigation and hot-reloading.

How does pkhub work?

pkhub performs 2 primary actions.

1. Watches source packages for changes - By default pkhub uses ts-node in watch mode to continuously build source packages.

2. Links source package to target projects - When a target project is said to use a package the dist output of the used package is copied to the node_modules of the target project. A backup copy of original package folder in node_modules is make an restored when pkhub exists.

Since pkhub directly manipulates the node_modules of the target project no additional configuration is needed and make pkhub compatible with nearly all build systems including ReactNative and metro.

Symlinks can optionally be used instead of coping output files. But in most casing dist output coping is more reliable although more resource intensive.

Examples

The examples below deminstrate how you can use pkhub to develop a React website and 2 supporting npm library packages at the same time. The supporting libraries live outside of the main React website and are npm packages. While pkhub is running the both the supporting and main website can be edited and hot-reloading and code navigation work as if the supporting libraries were part of the main React website code base.

Example File Structure

One react website and 2 typescript libraries

example
  |
  + - cool-web-site ( React website )
  |     |
  |     + - package.json
  |
  + - packages
        |
        + - math ( typescript library )
        |     |
        |     + - package.json
        |
        + - strings ( typescript library )
              |
              + - package.json

Using a config file

This example uses a config file named example-config.json

example-config.json

{
    "verbose":true,
    "deleteCache":true,
    "hubs":[
        "./example"
    ],
    "targets":[
        "./example/cool-web-site/"
    ],
    "use":[
        "@iyio/example-project-math",
        "@iyio/example-project-strings"
    ]
}

npx pkhub example-config.json

Using cli arguments

This example uses cli arguments as a script to run pkhub. The command below is equivalent to using pkhub with the example-config.json file.

npx pkhub -verbose -delete-cache \
    -hub ./example \
    -target ./example/cool-web-site/ \
    -use @iyio/example-project-math @iyio/example-project-strings

Using pkhub as a library

pkhub can also be used as a function in other projects. The example below is equivalent to using pkhub with the example-config.json file.

import { runPackageHub } from '@iyio/package-hub';

runPackageHub({
    verbose:true,
    deleteCache:true,
    hubs:[
        "./example"
    ],
    targets:[
        "./example/cool-web-site/"
    ],
    use:[
        "@iyio/example-project-math",
        "@iyio/example-project-strings"
    ]
})

Configuration

pkhub can be configured with a combinations of command line arguments and config files. Config files are converted to a sequence of command line arguments.

Config file properties

interface PackageHubConfig {

    /**
     * Sets the current session name
     */
    session?:string;

    /**
     * Instructs the pkhub process to exit with the given code
     */
    exit?:number;

    /**
     * Enables verbose console output
     */
    verbose?:boolean;

    /**
     * Instructs pkhub to delete the npm cache of target projects when exiting
     */
    deleteCache?:boolean;

    /**
     * An array of config files that will only have their packages loaded. Loading a config file
     * as a hub allows you to reuse existing config files buy only load the packages they define.
     * this prevents un-needed targets and other configurations from being loaded.
     */
    hubs?:string[];

    /**
     * Defines a any array of targets. Do not use in combination with target. A target defines
     * an npm package that will be linked to loaded packages. Use the use property to define
     * the packages the target will be linked to.
     */
    targets?:string[];

    /**
     * Defines a single target. Do not use in combination with targets
     */
    target?:string;

    /**
     * An array of package names to be used by the targets of the config
     */
    use?:string[];

    /**
     * An array of script args to run after the args generated by the config
     */
    args?:string[];

    /**
     * An array of script args to run before the args generated by the config
     */
    preArgs?:string[];

    /**
     * An array of config files to load
     */
    include?:string[];

    /**
     * If true the targets and hubs of the config will be cleaned. If set to a value of 'all'
     * then all targets defined in the ~/.pkhub/db directory will be cleaned. When a target
     * is cleaned it is restored to its state before pkhub started. This is useful for cases
     * when pkhub is not shutdown gracefully and leaves behind temp files and dead package links
     */
    clean?:boolean|'all';

    /**
     * Causes execution to pause for the given number of milliseconds
     */
    sleep?:number;

    /**
     * An array of scoped configs that are loaded in their defined ordered. Scopes are useful for
     * when you want to load targets with different package usages.
     */
    scopes?:PackageHubConfig[];

    /**
     * Prints the current parsed arguments. When a config object is loaded it is converted into a 
     * series of arguments that at as a script. Using printArgs allows you to see how a given
     * config is converted into args.
     */
    printArgs?:boolean;

    /**
     * If true pkhub will only print information about what it intends to do for a given config
     */
    dryRun?:boolean;

    /**
     * Array of packages to run. Running packages will be available to targets to link to
     */
    packages?:PackageConfig[];
}

interface PackageConfig
{
    /**
     * Name of the package. Will be inherited by the project's name in package.json if not defined
     */
    name?:string;

    /**
     * Tags that can be used to target the project
     */
    tags?:string[];

    /**
     * Path to a project directory or package.json
     */
    path:string;

    /**
     * Build directory relative to the project's root
     */
    outDir?:string;

    /**
     * Name of a npm script to run to run the package in watch mode. If false no watch script will
     * be ran. Default value = "watch". If no watch script is defined and the project contains
     * a tsconfig.json file and the tsconfig file defines an outDir then
     * "tsc --watch --outDir {tsconfig.outDir}" will be used.
     */
    watch?:string|false;
}

Command line arguments

( ) = optional

= required

Argument order is IMPORTANT. Since the arguments passed to pkhub act as a script the order the are passed in maters.

Hubs

Hubs are config files that define the location of packages. Hub config files can also define other properties that same as a standard pkhub config file, but when a config file is loaded as a hub only the packages property is used.

{
    "packages":[
        {
            "path":"packages/math"
        },
        {
            "path":"packages/strings"
        }
    ]
}

Clean up

Durning normal operation pkhub preforms clean up automatically when exiting but if pkhub does not shutdown gracefully target projects can be left in a non operational state. To fix this you can run pkhub in clean up mode by using the -clean flag. Make sure the first argument is the -clean flag. The order of the arguments are important.

# clean projects based on the local config file
npx pkhub -clean

# clean projects based on a specific config file
npx pkhub -clean -config some-other-config.json

# clean projects based on a previous arguments.
# This command is identical to the "Using cli arguments" example with the exception that the first
# argument is -clean.
npx pkhub -clean -verbose -delete-cache \
    -hub ./example \
    -target ./example/cool-web-site/ \
    -use @iyio/example-project-math @iyio/example-project-strings