Workspace Resolver

Utility for development on multiple library packages in a workspace. Creates aliases for library packages so you don't have to rebuild both packages to see changes. This can be considered an alternative to monorepos and npm-link.

Terminology

• <app>: Is your main application package. This package is responsible for bundling an asset for use with a server or as a static website. It imports one or more <library> packages.
• <library>: Is any of the packages that are imported by the <app> package. When releasing this package, it should transpile code into javascript that can be understood by the node version used in the <app> package (usually indicated by the package.json#engines property in the <library>/package.json).
• workspace: Refers the parent directory of the <app> and <library> packages.

└── workspace
    ├── library-1
    ├── library-2
    └── app

Basic Usage

Basic usage instructions for the main 2 utilities, spawn and resolve.

resolve

Creates an object map of <package#name>: <path-to-package-json> that you can use in an alias configuration, such as webpack#resolve.alias parameter.

See the resolve options section for details for any of these options. Below are their default values. For the most part, workspacePath, include and exclude will likely be the ones you want to play with.

import workspace from 'workspace-resolver'

workspace.resolve({
  deep: Infinity,
  exclude: [],
  include: [],
  lazyMatch: true,
  workspacePath: path.resolve('..'),
})

// {
//   'workspace-resolver': '/workspace/workspace-resolver',
//   'my-app': '/workspace/app',
// }

spawn

Spawns a process. See the spawn options section for details for any of these options.

import workspace from 'workspace-resolver'

workspace.spawn({
  pkgName: 'workspace-resolver',
  pkgPath: path.resolve(__dirname, '..', 'WorkspaceResolver'),
}, 'npm', ['run', 'watch'])

Together

If you are planning to spawn watch processes, you'll probably want to use these together:

import workspace from 'workspace-resolver'

const alias = workspace.resolve({workspacePath: path.resolve(__dirname, '..')})

// Run "npm run watch" in all alias
Object.entries(alias).forEach(([pkgName, pkgPath]) => {
  workspace.spawn({ pkgName, pkgPath}, 'npm', ['run', 'watch'])
})

// Run "make build --watch" in a single alias
workspace.spawn({
  pkgName: 'workspace-resolver',
  pkgPath: alias['workspace-resolver'],
}, 'make', ['build', '--watch'])

Options

resolve options

Field	Type	Default	Description
deep	number	Infinity	How many directories deep to search (from workspacePath). If there are multiple package.json files in workspace, be sure to set lazyMatch=false.
exclude	[string]	[]	Array of glob patterns or package names to exclude. '**/node_modules' is always excluded.
include	[string]	[]	Array of package names that must match in order to be aliased. When specified with exclude or aliasWatchPackagesOnly all rules must pass.
lazyMatch	boolean	true	Use the first matching package.json to indicate the alias directory for a given package.json#name. If false, matches will be greedy and the last match will be used for the package.json#name alias and watch path.
workspacePath	string	path.resolve('..')	Path to your workspace.

spawn options

Field	Type	Default	Description
pkg.pkgName	string	""	Npm package name (from package.json#name or package directory name in workspace dir)
pkg.pkgPath	string	""	Absolute path to package source root directory (the directory that contains package.json)
manager	string	"npm"	Executable that handles installing and packaging.
args	[string]	["run", "watch"]	Array of arguments to pass to the manager.
logWatchProcesses	boolean	true	Set to false to suppress output from watch sub processes.

Common Integration Tips

Below are suggested uses for integrating these utilities with other build tools. If you would like to create a plugin for any of these; 1. You are awesome! ❤️ 2. Please let us know by creating a ticket so we can reference your plugin in these docs.

• Webpack: [WorkspaceResolverWebpackPlugin] or manually with webpack#resolve.alias
• Rollup: @rollup/plugin-alias
• TypeScript: TypeScript alias guide
• Babel: babel-plugin-module-resolver
• Other: module-alias

Contributing

See CONTRIBUTING.

Security

See CONTRIBUTING#security-issue-notifications for more information.

License

This project is licensed under the Apache-2.0 License.