To check what a shared npm workspace package will actually deliver, run its tests from the monorepo, pack the workspace, then install that tarball in a separate temporary consumer directory on your Mac. This catches problems hidden by npm’s local workspace symlink, such as missing built files or an incorrect package entry point. It does not publish anything to a registry.

1. Run the package’s own tests from the workspace root

Open Terminal and change to the monorepo root—the directory containing the root package.json. Confirm that the package appears in the root workspaces configuration and has its own package.json. npm installs configured workspaces as links in the root node_modules, so a test run there can resolve the live workspace source. The workspace option lets you target a package by its declared name or directory. npm Workspaces

Run the package’s test script by its workspace name, substituting the name from its package.json:

npm run test --workspace=@acme/math

If the package uses a different script name, use that name. If it has no test script, this command cannot test its behavior; run the checks the project actually defines, such as its build or lint scripts. Avoid relying only on a root-level test command: npm commands such as test operate on the root unless you select a workspace. npm Workspaces

2. Review and create the package tarball

A local workspace test does not prove that the files consumers need are included in the package. First preview the selected workspace’s package contents from the monorepo root:

npm pack --workspace=@acme/math --dry-run

Review the file list for the package entry point, built output, type declarations, and any other files the package promises. npm’s files, .npmignore, and .gitignore settings affect the contents; package.json and README and license files are among those npm includes by default. Check that main or exports points to files that will be in the archive. npm pack, package.json files and entry points

When the list looks right, create a real tarball in a temporary directory. The following commands use macOS’s default zsh-compatible quoting and keep the artifact outside your repository:

scratch="$(mktemp -d "${TMPDIR:-/tmp}/workspace-package-check.XXXXXX")"
npm pack --workspace=@acme/math --pack-destination="$scratch"

--dry-run only reports what npm would pack; it does not create the archive. The second command does create one, but does not upload it. npm’s documentation describes npm pack as creating a tarball and recognizes the workspace selector. npm pack

3. Install the archive in a clean consumer folder

Find the tarball path, make a separate consumer directory, and install the archive there. This example assumes only one tarball was packed into the temporary directory:

tarball="$(find "$scratch" -maxdepth 1 -name '*.tgz' -print -quit)"
consumer="$scratch/consumer"
mkdir -p "$consumer"
cd "$consumer"
npm init -y
npm install "$tarball"

Installing a .tgz tests the packed artifact. Installing a workspace folder or using the monorepo’s linked dependency can behave differently. npm install

Now exercise the package through its public entry point. Use the package’s actual name and a small consumer check suited to its API—for example, require or import it, then call a representative exported function. Run that check from the consumer directory, where the package resolves from the newly installed node_modules. If the project publishes compiled output, verify the build has run before packing; otherwise the archive may be missing files even though development-time tests passed.

4. Diagnose failures before publishing

If installation fails, check that the archive has a package.json with name and version, then inspect its file list and confirm the configured entry points exist in the tarball. If the import fails, compare the consumer’s module format with the package’s type, main, and exports settings. A package can pass workspace tests yet fail here because those tests may load source files directly or resolve undeclared dependencies from the monorepo.

If a dependency is another unpublished workspace, test the intended release arrangement too. A consumer installing one tarball will not automatically receive sibling workspace source through the monorepo link. Ensure sibling packages are published/available at compatible versions, or use a deliberate bundled or installable setup. This procedure verifies a local packed package in the current Mac/Node environment; it cannot establish behavior across every Node version, operating system, or registry configuration.

The useful stopping point is a passing workspace test, a plausible package file list, and a consumer check that installs and exercises the tarball from outside the monorepo. Keep the temporary directory if you need to inspect it, or remove it with rm -rf "$scratch" after confirming that the variable still refers to the generated temporary path.

Sources