Docs on package.json vs project/foo/package.json (and their lockfiles)

[EvanCarroll]

Description

The Creating Library guide is totally absent any information on package.json and dependencies.

Currently the library creation guide advocates creating a workspace for every library.

ng new my-workspace --create-application=false
cd my-workspace
ng generate library my-lib

This will give you two package.json files, and also two lockfiles

• my-workspace/package.json
• my-workspace/projects/my-lib/package.json

There is no information differentiating these two.

On StackOverflow there is advice to put in dependencies that people have to have to use your library in the my-workspace/projects/my-lib/package.json under the projects directory, and to put the dependencies that you need to develop the library in ./package.json, but this doesn't explicitly address how you can ever have one and not the other in tested functionality.

More succiently, if a user needs a library to run the library in my-workspace/projects/my-lib/package.json won't the developer also need it in my-workspace/package.json so it can be available to ng build, and ng test? Do we have to manually keep these in sync? Is there ever a reason to have a dependency in my-workspace/projects/my-lib/package.json but not in my-workspace/package.json? Is npm install --save not useful for Angular libraries (it only adds to the package.json in the toot of the repo and leaves the files in packages/ out of sync).

My experience with this workspace structure leads me to believe a greater discussion should be had about whether or not this is even good idea. It's very confusing to have reputable tools like @semantic-release (which seem even semi-official) not even support multiple libraries in one workspace when the cli and docs make this sound like a routine practice. It also feels like the cli should be updated to make single-library-per-repo the default, and to restructure this such that there is only ever one package.json and one package in the default configuration.

What is the affected URL?

https://angular.io/guide/creating-libraries

[TrevorKarjanis]

I had these same questions, and ran into the same SO post. Given the advice on SO and some apparently related issues with library dependencies in application builds, this is my take on the docs section on peer dependencies. Dependencies are touched on but their interpretation can vary based on perspective.

• "Angular libraries should list any @angular/* dependencies the library depends on as peer dependencies."

It's assumed this is referring to workspace/projects/my-lib/package.json which may not be intuitive if the reader isn't aware that the root package.json is for all project dependencies, not just root. There was confusion about this, and some were adding development dependencies to workspace/projects/my-lib/package.json. Also, what about non-angular dependencies?

• "This ensures that when modules ask for Angular, they all get the exact same module. If a library lists @angular/core in dependencies instead of peerDependencies, it might get a different Angular module instead, which would cause your application to break."

I assume, but it's not immediately obvious that this is referring to the peer dependencies installed to the workspace of the consuming application which would enforce versions. I think that's because it's not clear whether or not those dependencies were bundled by the library build.

• "While developing a library, you must install all peer dependencies through devDependencies to ensure that the library compiles properly. A linked library will then have its own set of Angular libraries that it uses for building, located in its node_modules folder."

This is confusing, because the documentation states and the CLI places these in dependencies not devDependencies. The latter half is also confusing, because it's easy to assume that it's referring a library specific set of node_modules. Actually, I think it's referring to the workspace which, yes, would be the library's node_modules if you're familiar with what the root package.json is for.

• "However, this can cause problems while building or running your application. To get around this problem you can use TypeScript path mapping to tell TypeScript that it should load some modules from a specific location. List all the peer dependencies that your library uses in the workspace TypeScript configuration file ./tsconfig.json, and point them at the local copy in the application's node_modules folder."

I am experiencing problems, but I'm not sure if this is the one I'm referring to. Maybe it would be good clarify, because I already expected the library's peer dependencies to be pulled from the application's node_modules. Is there an edge case or different library setup that may or may not apply to me?

[Edit] The first two sentences of Resolving UMD Module Identifiers will probably help a lot of people. However, I haven't seen it mentioned anywhere else in the libraries or ng-packagr docs.

[EvanCarroll]

@AndrewKushnir what's the process to get this triaged? It would be great to see it added to the backlog.