Pnpjs: Please doucment the use of sp.setup

[nils-a]

Category

• [X] Enhancement
• [ ] Bug
• [X] Question
• [ ] Documentation gap/issue

Version

Please specify what version of the library you are using: [ 1.2.8 ]

Please specify what version(s) of SharePoint you are targeting: [online ]

If you are not using the latest release, please update and see if the issue is resolved before submitting an issue.

Expected / Desired Behavior / Question

I'am tying to access multiple different sites/web in the same app (azure function) for this, I am doing multiple requests, each one preceded by a different call to "sp.setup".
However, "sometimes" I see strage bahaviour, as if the url to the site being used is the url from the sp.setup used before the last one.

Is there some limitiation on sp.setup, like "use only once" or something?
Is there a method to change only the url for the next sp.web-call?

[koltyakov]

Hi @nils-a,

sp.setup is a global thing.

For per web object configuration this approach is preferred:

const web = new Web('[WEB_ABSOLUTE_URL]').configure({
  headers: { /* ... */ }
});

[nils-a]

Thanks.
Any plans on getting that a bit more "documented"?

[koltyakov]

@nils-a,

Actually, this is documented.

[thw0rted]

Hi @koltyakov and @nils-a , this behavior is no longer documented and the link above is a 404.

Do I need to open a new ticket to document new Web(...) and IWeb#configure or would it be better to reopen this one?

ETA: I noticed that ISPInvokableFactory is no longer a constructor so new Web(...) is marked as an error by the type checker. Are we supposed to use w = Web(...) or is new Web(...) correct and it's just the typings that need to be fixed?

[koltyakov]

The docs were rearranged, the link I pointed to is no longer exist. The information is now could be found at https://pnp.github.io/pnpjs/sp/webs/#access-a-web

Create a web instance using the factory function

import { Web } from "@pnp/sp/webs";

const web = Web("https://something.sharepoint.com/sites/dev");
const r = await web();

Please also check the section in the transition guide https://pnp.github.io/pnpjs/transition-guide/#factory-functions-interfaces

[thw0rted]

Thanks, the transition guide does a good job explaining about the factory methods. I notice that in your updated sample it doesn't call configure -- does that mean that I no longer need to set the Accept header manually?

Is it never appropriate to call IWeb#configure anymore? The docs no longer mention it at all.

[koltyakov]

You never needed to set up headers manually until you needed it. =)
configure method is still there and can be used, e.g. when the unique per-instance configuration is required.

[thw0rted]

OK, so, does the configure method need a new ticket for docs or should this one be re-opened? Or does the project want users to come and search Github issues if they think they might need it?

That's an honest question! The whole layout of the docs is pretty different from what I'm used to, so I'm working on the assumption that this project has its own conventions.

I expected to find docs that say "this is the Web factory method; here are the type and meaning of each of its arguments; it returns an IWeb interface; here are all of its member properties and methods, with their argument and return types; etc etc." Instead, the docs tell you "here's how you do X, along with some sample code" and never actually spell out individual API types or methods in a single format. That's different from the other NPM packages I use, but it's also how a lot of e.g. Powershell docs seem to be put together, so I'm not making a value judgment.

[koltyakov]

There is docs article for configure https://pnp.github.io/pnpjs/odata/queryable/#configure - it's a part of any queriable object, not necessarily Web.

Thanks for your feedback! I agree that some corners of the docs have room for improvement. It's revisiting work, where active contributors do their best.

It's better to open a separate issue with a specific suggestion or question, as closed has less visibility and not revisited. PRs are also welcome especially if somebody can suggest outside view recommendations for logical gaps fixes for whose who read and deal with the library for the first time or so.