workspace-resolver
v0.0.4
Published
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
Downloads
4
Readme
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 thepackage.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.