← ./articles

Node.js on OneDrive: Move node_modules with a Windows Junction

windowsonedrivenodejsnpmnextjsvite

Running Node.js projects inside a OneDrive-synced folder can turn ordinary development into random dependency and build failures.

The common advice is "do not put node_modules in OneDrive." That is correct, but it is not always practical. Some developers keep their project folder under Desktop or Documents, and those folders are often synced by OneDrive on Windows.

A practical compromise is to keep the project where it is, but move node_modules outside OneDrive and expose it back to the project through a Windows directory junction.

The symptom

The failure rarely announces itself as "OneDrive broke your install." It usually appears as unrelated Node or bundler errors:

  • npm install completes, but packages are missing
  • next dev or vite dev fails with module resolution errors
  • esbuild or Vite crashes during install or build
  • build output is created and then disappears or becomes stale
  • reinstalling seems to fix it, then the problem returns

The shared cause is high-frequency file churn. node_modules contains thousands of small files. npm, Vite, Next.js, and esbuild read and write quickly. OneDrive tries to sync those files at the same time.

The junction pattern

Use a stable external store outside OneDrive:

<external-store>\my-project\node_modules

Then create a junction at the project path:

<project>\node_modules -> <external-store>\my-project\node_modules

To Node.js and npm, node_modules still appears in the project. To OneDrive, the heavy dependency tree lives outside the synced folder.

Minimal PowerShell setup

Use PowerShell, not mklink, especially if your project path contains non-ASCII characters.

$ProjectRoot = "<project-root>"
$Store = "<external-store>\my-project\node_modules"
$Junction = Join-Path $ProjectRoot "node_modules"

New-Item -ItemType Directory -Path $Store -Force | Out-Null

if (Test-Path $Junction) {
  Remove-Item $Junction -Recurse -Force
}

New-Item -ItemType Junction -Path $Junction -Target $Store | Out-Null

After that, install packages into the project as usual. For a more reliable automation script, make the junction check idempotent and run it before dev/build commands.

npm can replace the junction

One subtle failure is that npm can delete and recreate node_modules during install. If that happens, the junction is replaced with a real folder under OneDrive again.

That is why a one-time setup is not enough. Add an ensure-node-modules.ps1 script and run it before dev, build, and test commands.

{
  "scripts": {
    "predev": "powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\\ensure-node-modules.ps1",
    "prebuild": "powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\\ensure-node-modules.ps1",
    "dev": "next dev",
    "build": "next build"
  }
}

The script should verify:

  • node_modules exists
  • it is a junction
  • it points to the expected external store
  • if not, it recreates the junction

What this does not solve

Moving node_modules helps, but it does not make OneDrive a perfect build workspace.

Build artifacts can also be noisy:

  • Next.js writes .next/
  • Vite writes dist/
  • Rust writes target/

If those directories become a problem, move or clean build artifacts separately. For Next.js, run a clean single build before blaming app code. For Vite/Tauri, be careful with output paths and verify that generated files are fresh.

Checklist

Use this order:

  1. Put dependencies in an external store such as <external-store>\project\node_modules
  2. Create a junction from project node_modules to that store
  3. Reassert the junction before dev and build
  4. Avoid parallel builds that write to the same artifact directory
  5. If build output still corrupts, handle .next, dist, or target separately

This is not as clean as moving the whole repository outside OneDrive. But when the project must stay under a synced folder, a junction can remove the largest source of churn.

References