[DOCS] Clearer instructions on functional parity between arborist and NPM

[danielamar101]

Hey there, as a preface, I appreciate everything you guys do to maintain npm and all of its workspaces.

I am trying to programmatically install modules into a project without using exec calls or the deprecated npm programmatic interface. Arborist is the perfect package for this endeavor. However, I am finding it difficult to understand how exactly I can use arborist to mimic an npm install exactly? Do I have to do more than this?

const arb = new Arborist(optionsObject)
await arb.loadActual()
await arb.loadVirtual()
await arb.buildIdealTree({})
await arb.reify();

That example omits error handling.

I guess I am more so confused on how the virtual and actual trees change with changes to a package.json file, and how Arborist handles that.

Thanks in advance.

[ljharb]

My understanding is that "actual" reads from node_modules, "virtual" reads from the lockfile, "ideal" reads from package.json, if that helps.

[danielamar101]

Ahh. so:

To install from a package-lock.json (npm ci):

loadVirtual
reify()

To install from package.json (npm i)

buildIdealTree()
reify()

Then what is the point of loading the actual tree? I guess my question still stands, how do these different trees interact with each other and where does that occur?

[ljharb]

Not quite - I think if you loadActual and then reify, it will do what npm install does with an existing node_modules. If you buildIdeal and reify, it will do what a fresh no-lockfile npm install would do.

[danielamar101]

That makes sense. So is it advised to only load one of the three trees and reify? Or is there another piece I am missing that connects them all more.

[ljharb]

I would assume that only one makes sense, depending on the answers to questions like:

1. is there a lockfile, or not?
2. (if a lockfile) do you want to simulate npm ci or npm install behavior?
3. do you want to take into account existing node_modules? ("yes" to match npm install, "no" to match npm ci)