Add support for library packages

[waldekmastykarz]

Category

• Question
• Typo
• Bug
• Enhancement / Suggestion
• Additional article idea

Expected or Desired Behavior

When building web parts I'd like to be able to extract common code to a separate library that can be shared amongst the different web parts.

Observed Behavior

Currently, working with library packages works only with the local workbench. At this moment, it's not possible to generate a package for a project with a library component type. Having generated a library package myself, and deployed it to the App Catalog, the library package causes an error in SharePoint stating that component type Library is not supported. As a result no custom web parts show in the toolbox.

Steps to Reproduce

• create a solution with a component type library
• run $ gulp package-solution
  • error: Component type 'Library' not recognized. Skipping manifest.

[vignes412]

we can import modules in three methods

FIRST::Using Config-->config.json and change

 "externals": {
    "jquery": "https://code.jquery.com/jquery-3.1.0.min.js",
    "OwlCarousel":{
      "path":"./node_modules/react-owl-carousel/lib/OwlCarousel.min.js",
      "globalName":"OwlCarousel"
    },
    "Slider":{"path":"./node_modules/react-slick/lib/slider.js",
    "globalName":"Sliders"}
  },

SECOND:: npm install @types/youtube-api-search --save

THIRD ::

 `npm install typings` 

`typings install dt~youtube-api-search -global --save`

sometimes dt~ is neccessary sometimes it is not necessaary

[waldekmastykarz]

@vignes412 this issue is not about referencing regular Node packages but using SharePoint Framework libraries which are a specific type of component.

[amishra0909]

Thanks for the feedback @waldekmastykarz. We do not support third party "Library" components currently but we have this feature added and tracked in our backlog. I am closing this issue for now and you can use our UserVoice to post your feature requests in future. Here is the link to the UserVoice: https://sharepoint.uservoice.com/forums/329220-sharepoint-dev-platform

[michel-weber]

And here is the UserVoice entry:
https://sharepoint.uservoice.com/forums/329220-sharepoint-dev-platform/suggestions/19224202-add-support-for-library-packages-in-the-sharepoint

[octogonz]

Following up on this: The "client-side libraries" feature is mainly used by the SPFx runtime itself. It enables dynamic side-by-side versioning, i.e. it allows your library to be modeled as a client-side component with a manifest and a bundle. When new versions of your library are deployed, other already deployed consumers (e.g. web parts or extensions) will be automatically linked at runtime to the most recent compatible version number.

Currently we don't officially support this for third parties. It is a somewhat advanced approach that requires you to:

• Set up separate TypeScript project folders, since each library is a separate NPM package
• Use a tool like Rush to symlink your project folders during development, because if you try to use "npm link" you are likely to encounter a TypeScript compiler bug (that will be fixed soon)
• Deploy your libraries separately to the App Catalog, since "gulp package-solution" does not span multiple project folders
• Think carefully about your runtime API contracts, since there is a possibility that components might get linked to a different library version than they were tested with

I have not personally heard anyone asking for this feature specifically. What most people seem to want is one of these two scenarios:

1. I have two web parts, and I want to share some code between them; and (less commonly)
2. ...when I load only one of my web parts, I want to improve performance by NOT loading the other web part's code

Both of these scenarios have a much simpler solution than client-side libraries: We're working on a feature that will allow multiple web parts (from the same project) to be packed into a single bundle. This means that if they share code, only one copy of the code will be on the page. Also there will not be duplicate instances of your singleton objects (as happens with libraries packed into separate bundles). Since everything builds together as one project, this approach will avoid the complexity that I mentioned above. And if you want to avoid loading unnecessary code, you can use Webpack chunks just like with a single-web-part project.

I suspect that this will meet the needs of the vast majority of people asking about library code. The one exception would be if someone was distributing a shared platform API and wanted to push out updates without having to rebuild already deployed components that rely on it (like what SPFx does). So far I haven't heard any serious requests for that yet, but if so, we'd be interested to hear about it. :-)

@VesaJuvonen @waldekmastykarz @nickpape-msft @patmill @iclanton @qz2017

[waldekmastykarz]

I think there is still need to deploy and manage separate libraries of common code. I suspect people haven't been asking for it, because it's still very early and many are yet to start building solutions on the SharePoint Framework. In the past it was a common scenario for developers to split a solution into multiple WSPs which could be managed separately. I think the same requirement still applies to the SharePoint Framework, particularly for bigger projects that would contain dozens of web parts and extensions.

[octogonz]

@waldekmastykarz Just to clarify, are you saying that this seems like something people will eventually want, as their needs become more sophisticated (which we agree)? Or are you saying that you need this for a real project right now, i.e. our other solution won't work for you?

I'm just trying to figure out how we should prioritize it against our other work.

[waldekmastykarz]

First one: people will need this eventually. The number of votes on UserVoice are a good indication on how desired this capability is.

[arnieraju]

Thanks for driving this Waldek. Depending on what we are trying to achieve, we have been using ScriptEditor, ContentEditor web parts, and Custom Actions to make common libraries available to different client side apps on a page. The first two of which won't work in the new world of Modern Pages and all of which provide a disjointed and hacky development and deployment experience.

It would be great to have an SPFx way for approaching how we package and deploy common libraries.

[octogonz]

Suppose you have three pieces of code:

• Web Part 1
• Web Part 2
• Common Library

In your scenario, would you want to go through these steps separately for each piece: compile, package, upload to App Catalog, get tenant admin approval? Would each piece have its own dev team?

If so, how would you handle mismatches, e.g. where Web Part 1 requires Common Library version 2.0.3 but Web Part 2 requires Common Library version 1.5.6?

The approach I was advocating instead would have all three pieces compiled together and packaged into a single ".spkg" file.

[waldekmastykarz]

I've been thinking about the case where all three are separate packages managed independently. This is common for large organizations who have a standard for things like logging, error handling or calling line of business applications that should be reused by all projects. So while the common library might not be managed by itself it would most likely be extended with required pieces when working on Web Part 1 or Web Part 2 which in fact are better to be seen seen as Project 1 and Project 2.

With regards to handling version conflicts: if v2 is not backwards compatible with v1 then major versions could be included in the package name, e.g. contoso-common-v1. Each major version would have a different ID and be deployed separately to the app catalog. If they are backwards compatible, then v2 could replace v1.

[VesaJuvonen]

Just an additional comment on the @waldekmastykarz 's input. Mid-sized and larger enterprises were already doing this exact thing with farm solutions back in the on-premises days with similar version dependencies cross solutions.

Considering the fact that development projects can have tens of developers for one project, customers / partners create their own development processes to ensure that there are no version conflicts. Obviously using separately deployed code is not really recommended for smaller deployments due to the additional overhead, but even back in the days when was also personally working in the field, customer projects could have easily 30-40 web parts developed by different geographically located teams.

What would be interesting is to hear about the cases where the library model would be used and what sized projects are currently being built on top of the SharePoint Framework, so that we can internally evaluate the priority for this request.

[octogonz]

Agreed. Releasing this feature is actually not particularly difficult, since it is what we already do internally for the SPFx packages. The challenge is that is a somewhat advanced model. It requires the kind of coordination you describe (which for us has turned out to be an involved process). We would need to document the model clearly, help people to understand whether it is appropriate for their problem, and give guidance to avoid "DLL hell".

That's the main reason I was waiting for to see whether the multiple-components-in-one-bundle alternative would suffice for most people. BTW I believe that one will be included in the next major SPFx release, if you want to give it a try for comparison.

[patmill]

Covered under user voice https://sharepoint.uservoice.com/forums/329220-sharepoint-dev-platform/suggestions/19224202-add-support-for-library-packages-in-the-sharepoint

[pkmelee337]

I know this is covered under the user voice, but I really have some troubles atm setting this up. I have created a Library component and it's compiling very smooth. I have also set up a private npm package location in Azure DevOps Artifacts to can publish this library to. When I include this library in my webpart, it is building also, but as @waldekmastykarz already said in his blog, it's only working on the workbench,

When I'm adding my generated library js file from my node_modules folder (or from an azure cdn) in my webpart as an external to the config.json, I am retrieving the error "External "<librayr name" is specified both as a linked package in the node_modules dependency tree and as an external in in the config.json file. Remove one of the external references. Only one external reference type is allowed per external package.". My solution is compiling, but it also doesn't work. I tried to delete the manifest.json and the config folder in my node_modules folder, but this also isn't working.

Do I really have to go to the trouble of compiling my library without sp-web-build and the other SPFx tools and do it myself? That also means I can't create some global translations in my library project and I will need to write the whole publishing mechanism (to an Azure CDN) myself to.

Did any of you guys figure out how to do this with the tools provided by SPFx?

[pkmelee337]

Allright, so after some puzzling I created a workaround untill this feature is supported outside of the workbench. An side effect of this workaround is that every webpart importing the library is including the library in it's bundle, because adding the library as an external isn't working. Another side effect is that translations aren't working this way. For now that will do, because we were only needing a shared spfx codebase to get included in multiple solutions.

After all I didn't change that much after following @waldekmastykarz blog. The most important part is the .npmignore file. Normally on a publish the dist folder is published too. The bundle created here isn't working, so I added the dist folder to my .npmignore file. This means that on an import in one of the webparts the files are looking at the lib folder instead. I also removed the config folder from the publish just to be certain.

From this point on bundling is working, but the bundling part is complaining about files missing in the src folder. This is because the .map files in your lib directory are (off course) pointing to the .ts files in your src folder. Because our library is only used in internal projects (and hosted in Azure Repos) I fixed this by simply including these files in an npm publish, which means removing the src directory from your .npmignore file. I can also imagine you don't want to include these files. Another possible solution might be just replacing the map files or simply deleting them, but I did not test this.

The final .npmignore file looks as followed:

# Temporary until SPFx libraries are working
config
dist
# src

# Folders
.vscode
coverage
dist
node_modules
sharepoint
temp

# Files
.editorconfig
.tfignore
*.csproj
.git*
.yo-rc.json
gulpfile.js
tsconfig.json
tslint.json
webpack.config*

[msft-github-bot]

Issues that have been closed & had no follow-up activity for at least 7 days are automatically locked. Please refer to our wiki for more details, including how to remediate this action if you feel this was done prematurely or in error: Issue List: Our approach to locked issues