Modern JavaScript Package Publishing & Monorepo Management
Practical, production-focused guides for building, publishing and maintaining JavaScript and TypeScript packages — from a single library to a monorepo with dozens of packages. Browse by section, jump straight to the error you are seeing, or follow a path for the job in front of you.
Start with the job in front of you
Publish a package that works everywhere
Get the manifest, module formats and types right, then prove it before release.
Set up or scale a monorepo
Workspaces, internal dependencies, a task runner and caching that keeps CI fast.
Fix a failing install or build
Resolution conflicts, lockfile drift, ESM/CJS errors and missing types.
Harden and automate releases
Trusted publishing, provenance, 2FA, release channels and the package lifecycle.
Browse all topics and guides
Every topic below opens a full reference page — concepts, configuration, internals, CI integration and pitfalls — and each lists its focused guides. Expand a topic to jump straight to a guide.
Core JavaScript Package Workflows
The manifest, dependency resolution, lockfiles, module formats, TypeScript declarations, builds and the tooling that keeps installs consistent. 11 topics and 68 guides.
Bundling and Build Tooling for Libraries
A library bundler turns your TypeScript source into the exact .mjs, .cjs, and .d.ts artifacts your package.json exports map promises consumers — get the bundler wrong…
7 guides
- Building a Library with Vite Library Mode
- Fixing 'Could not resolve node: Builtins' in a Browser Bundle
- Fixing 'process is not defined' in Browser Bundles
- Fixing tsup Output Missing .d.ts Type Declarations
- Preserving Modules for Tree-Shaking with Rollup
- Resolving Rollup 'Unresolved Dependencies' Warnings
- Shrinking Published Package Size with sideEffects and files
Dependency Auditing and Automated Updates
Dependencies rot: a lockfile that was clean at release accrues known vulnerabilities and drifts behind upstream within weeks.
7 guides
- Checking Dependency Licenses in CI
- Configuring Renovate for Grouped Updates in a Monorepo
- Finding Unused Dependencies and Exports with Knip
- Fixing 'npm audit fix' Introducing Breaking Changes
- Keeping Workspace Dependency Versions in Sync with syncpack
- Pinning Vulnerable Transitive Versions with overrides
- Reducing Dependabot Noise with Grouping and Schedules
Dependency Resolution Explained
Every npm install, pnpm install, or yarn install runs the same fundamental job: take a set of declared version ranges, walk the registry metadata, and collapse the…
8 guides
- Deduplicating Duplicate React Versions
- Fixing Missing Platform Binaries in optionalDependencies
- Fixing npm EBADENGINE 'Unsupported Engine' Warnings
- Fixing npm ERESOLVE Peer Dependency Conflicts
- Fixing npm ETARGET 'No Matching Version Found'
- Fixing Phantom Dependencies After Switching to pnpm
- Forcing a Single Dependency Version with pnpm overrides
- When to Use peerDependencies vs devDependencies
ESM and CJS Interoperability
A modern JavaScript package is expected to load cleanly whether a consumer writes import, require, a tsconfig with moduleResolution: "bundler", or a webpack config from…
8 guides
- Fixing '__dirname is not defined' in ES Modules
- Fixing 'Cannot use import statement outside a module'
- Fixing ERR_MODULE_NOT_FOUND for Extensionless Imports
- Fixing ERR_REQUIRE_ESM in Node.js
- Fixing ERR_UNKNOWN_FILE_EXTENSION for .ts Files
- Fixing the Dual Package Hazard (Two Instances Loaded)
- Loading ESM from CommonJS with require(esm)
- Resolving 'Named Export Not Found' in ESM
Lockfile Management Strategies
Without a committed, enforced lockfile, two engineers running the same install on the same day can end up with different transitive dependency trees — and the bug that…
Package Manager Version Management New
When developers, CI runners and dependency bots each use a different version of npm, pnpm or Yarn, the same repository produces different lockfiles, different…
Root-Level vs Package-Level Scripts
Where a script lives — in the root package.json or inside an individual package — dictates monorepo stability, CI throughput, and supply-chain exposure.
Testing and Validating Packages Before Publishing New
A package can pass every unit test in its repository and still be broken for the people who install it: the tarball is missing dist/, the exports map sends CommonJS…
TypeScript Declaration Publishing
Shipping .d.ts files that resolve correctly under every consumer's tsconfig.json is the difference between a package that "just works" and one that floods editors with…
Understanding package.json Fields
The package.json manifest is the single contract between your source tree, the resolver, the bundler, and every consumer who installs your package — and a single…
Workspace Configuration Deep Dive
The moment a repository holds more than one package, the questions multiply: how do internal packages depend on each other, which dependencies hoist to the root, and how…
Monorepo Architecture & Orchestration
Workspaces, internal dependencies, task runners, caching, affected CI, TypeScript project references and migrating into (or out of) a monorepo. 10 topics and 46 guides.
Choosing a Monorepo Task Runner
Picking the wrong task runner costs months: you either over-invest in tooling a three-package repo never needed, or you outgrow a thin orchestrator the moment your CI…
CI/CD Pipeline Optimization for Monorepos
A monorepo CI pipeline that rebuilds and retests every package on every commit gets slower with each package you add, until a one-line change waits twenty minutes for…
7 guides
- Building Docker Images for One Workspace with turbo prune
- Caching the pnpm Store in GitHub Actions
- Caching Turborepo Outputs in GitHub Actions Without a Remote Cache
- Fixing Nx 'Affected' Detecting All Projects as Changed
- Fixing Slow Monorepo CI with Affected Builds
- Running Monorepo Pipelines on GitLab CI
- Splitting Monorepo Tests into Parallel CI Shards
Cross-Package Dependency Management
Internal packages in a monorepo must resolve to local source deterministically, version in lockstep, and never form a cycle — and the difference between getting that…
Monorepo Migration and Adoption New
Moving from many repositories to one — or deciding which parts should stay separate — is an organisational change as much as a technical one, and most failed monorepo…
Nx Workspace Architecture
Nx turns a directory of loosely related packages into a deterministic build system: it derives a project graph from your imports, attaches a task pipeline to that graph…
pnpm Workspace Filtering
In a multi-package repository, running every script everywhere is the default and the wrong default.
Remote Caching Setup
A remote cache turns a build artifact produced once — on any machine, by any contributor — into a hit for everyone else who runs the same task with the same inputs.
Turborepo Pipeline Configuration
A Turborepo pipeline is a declarative task graph: you describe how each task depends on others, what it consumes, and what it produces, and Turborepo computes a…
TypeScript Project References in Monorepos New
Type-checking a monorepo package by package with tsc --noEmit repeats work: every package re-checks its dependencies' source from scratch, editors load the whole…
Workspace Symlinks vs Hard Links
Modern package managers build node_modules out of two filesystem primitives that are easy to confuse and behave very differently: symlinks and hard links.
Package Publishing & Release Engineering
Versioning, the publish itself, registries and access, supply-chain security, release channels and the long tail of a package's life. 6 topics and 37 guides.
npm Registry Publishing Workflows
Ship npm packages deterministically, with the right files, the right access level, and verifiable provenance.
8 guides
- Dry-Running a Publish Before Release
- Fixing npm 'Cannot Publish Over Previously Published Version'
- Fixing npm EOTP One-Time Password Errors
- Fixing npm publish 403 Forbidden Errors
- Fixing npm publish E404 Not Found
- Publishing from CI with npm Trusted Publishing
- Publishing Scoped Packages to npm
- Setting Up npm Provenance with GitHub Actions
Package Deprecation and Lifecycle New
Publishing a package is the beginning of a commitment, and most of a package's life happens after the first release: versions that must be retired because they are…
Private Registries and Access Control
Publishing internal packages to the public npm registry leaks your code and namespace; publishing them with no access controls invites supply-chain compromise.
7 guides
- Fixing npm 401 Unauthorized on a Private Registry
- Fixing SELF_SIGNED_CERT_IN_CHAIN on Internal Registries
- Publishing to AWS CodeArtifact
- Rotating npm Publish Tokens Without Breaking CI
- Routing Scopes to Multiple Registries in .npmrc
- Scoping GitHub Packages to a Single Organization
- Setting Up Verdaccio as a Private Proxy Registry
Release Channels and Dist-Tags New
Every npm install your-lib without a version installs whatever the latest dist-tag points to — so dist-tags, not version numbers, decide what most users get.
Semantic Versioning and Release Automation
Without an enforced versioning contract and an automated bump, releases drift: humans forget to increment, ship breaking changes as patches, and tag the wrong commit —…
Supply-Chain Security Hardening
The npm registry is a remote-code-execution channel: every npm install downloads and can execute arbitrary code from hundreds of maintainers you have never met.
9 guides
- Adding SLSA Provenance to Package Releases
- Blocking Malicious Install Scripts with --ignore-scripts
- Configuring lockfile-lint for Supply-Chain Safety
- Enforcing npm audit Thresholds in CI
- Generating an SBOM for a JavaScript Package
- Preventing Dependency Confusion Attacks
- Requiring 2FA for Package Maintainers
- Responding to a Compromised Dependency
- Verifying npm Package Provenance Before You Depend on It
Find a fix by error message
Seeing a specific error? Match it here and go straight to the guide that explains the cause and the fix.
Follow a package from first commit to retirement
Most questions belong to one stage of a package's life. These are the topics to open for each stage:
- Author: Understanding package.json Fields, ESM and CJS Interoperability, TypeScript Declaration Publishing, Bundling and Build Tooling for Libraries
- Validate: Testing and Validating Packages Before Publishing, Dependency Auditing and Automated Updates
- Publish: Semantic Versioning and Release Automation, npm Registry Publishing Workflows, Private Registries and Access Control, Supply-Chain Security Hardening
- Maintain: Release Channels and Dist-Tags, Package Deprecation and Lifecycle
New on the site
This update adds six topics and 94 guides. The new topics:
- Testing and Validating Packages Before Publishing — A package can pass every unit test in its repository and still be broken for the people who install it: the tarball is missing dist/, the exports map sends CommonJS…
- Package Manager Version Management — When developers, CI runners and dependency bots each use a different version of npm, pnpm or Yarn, the same repository produces different lockfiles, different…
- Monorepo Migration and Adoption — Moving from many repositories to one — or deciding which parts should stay separate — is an organisational change as much as a technical one, and most failed monorepo…
- TypeScript Project References in Monorepos — Type-checking a monorepo package by package with tsc --noEmit repeats work: every package re-checks its dependencies' source from scratch, editors load the whole…
- Release Channels and Dist-Tags — Every npm install your-lib without a version installs whatever the latest dist-tag points to — so dist-tags, not version numbers, decide what most users get.
- Package Deprecation and Lifecycle — Publishing a package is the beginning of a commitment, and most of a package's life happens after the first release: versions that must be retired because they are…
How the guides are written
Each section page gives the big picture for one area and links to its topics. Each topic page is a full reference: what the tool or concept does, how it works internally, how to configure it, how to run it in CI, and the pitfalls to avoid. Each guide handles one task or error message, starting from the exact symptoms, explaining the root cause, and ending with a verified fix, validation commands and guardrails that stop the problem coming back. Code examples assume Node.js 18 or later and current releases of npm, pnpm, Yarn, Turborepo and Nx.