JavaScript libraries work without installation

Use existing JavaScript libraries in SharePoint Framework client-side web parts

  • 10 minutes to read

When building client-side web parts on the SharePoint Framework, you can benefit from using existing JavaScript libraries to build powerful solutions There are, however, some considerations that you should take into account to ensure that your web parts won't negatively impact the performance of SharePoint pages that they're being used on.

Reference existing libraries as packages

The most common way of referencing existing JavaScript libraries in SharePoint Framework client-side web parts is by installing them as a package in the project.

  1. Take the Angular example. To use this framework in a client-side web part, you would first use Angular using npm install: Taking Angular as an example, to use it in a client-side web part, you would first install Angular using npm:

  2. To use Angular with TypeScript, you would use NPM Install type declarations: To use Angular with TypeScript, you would install type declarations using npm:

  3. Finally, you would reference Angular in your web part via the statement: Reference Angular in your web part by using the statement:

Bundle web part resources

The SharePoint Framework uses a build toolchain based on open-source tooling such as gulp and Webpack. When creating SharePoint Framework projects, these build tools take into account automatically all referenced resources together in a single JavaScript file. This process is called bundling. When building SharePoint Framework projects, these build tools automatically combine all referenced resources into a single JavaScript file in a process called bundling.

Bundling offers you a number of benefits. First of all, there are all required resources for your web part available in a single JavaScript file.First of all, All resources required by your web part are available in one single JavaScript fileThis simplifies the deployment because the web part consists of a single file, and it's impossible to miss a dependency in the deployment process.

Also, because your web part uses different resources, it's important that they're loaded in the right order. The one generated by webpack during creation Web part bundle takes over the loading of the various resources for you. Among other things, it also resolves all dependencies between these resources. the web part bundle manages loading the different resources for you, including resolving any dependencies between these resources.

Bundling web parts also has benefits for end-users: generally speaking, it's faster to download a single, bigger file than a number of small files.By combining several smaller files into a larger bundle the web part loads faster on the page.By combining a number of smaller files into one bigger bundle, Your web part loads faster on the page.

However, bundling existing JavaScript libraries with SharePoint Framework client-side web parts isn't without drawbacks.

When bundling existing JavaScript frameworks in the SharePoint Framework, all referenced scripts are included in the generated bundle file. To refer to the Angular example again : Following the Angular example, an optimized web part bundle including Angular is over 170 KB.

If you add another web part to your project that also uses Angular and build the project, you will get two bundle files: one per web part. Each file is larger than 170 KB. If you add another web part to your project that also uses Angular and you build the project, you get two bundle files, one for each web part, each of them being over 170 KB.

Suppose you add these web parts to a page. If you add these web parts to a page, each user would download Angular multiple times, once with each web part on the page. This approach is inefficient This approach is inefficient and slows down page load time.

Reference existing libraries as external resources

A better approach to leveraging existing libraries in SharePoint Framework client-side web parts is by referencing them as external resources That way, the only information about the particular script that is included in the web part is the script's URL. When the web part is added to the page, it automatically tries to When added to the page, the web part automatically tries to load all required resources from the specified URL.

Referencing existing JavaScript libraries in the SharePoint Framework is easy and does not require any special code changes. Since the library is loaded at runtime from the specified URLs, it does not need to be installed as a package in the project. Referencing existing JavaScript libraries in the SharePoint Framework is easy and doesn't require any specific changes in the code. Because the library is loaded on runtime from the specified URL, it doesn't need to be installed as a package in the project.

Let's take Angular again as an example: To reference it as an external resource in your client-side web part, first install its TypeScript type declarations using NPM: Using Angular as an example, to reference it as an external resource in your client-side web part, you start by installing its TypeScript type declarations using npm:

Then add to the file config / config.json Add the following entry to the property: In the config / config.json file, to the property you add the following entry:

The full file config / config.json would then look something like this: The complete config / config.json file would then look similar to:

Reference Angular in your web part: Reference Angular in your web part:

If you build your project now and take a look at the size of the generated bundle file, you notice that it's only 6 KB.

If you add another web part to your project that also uses Angular, and you build the project again, both bundles would be 6 KB each.

It isn't correct to assume that you've saved over 300 KB. Both web parts still need Angular and load it the first time a user visits the page Both web parts still need Angular and load it the first time the user visits the page where one of the web parts is placed.

Even if you add both Angular web parts to the page, SharePoint Framework still downloads Angular only once.

The real benefit of referencing existing JavaScript libraries as external resources is if your organization has a centralized location for all commonly used scripts or you use a CDN. In such cases, there's a chance that the particular JavaScript library is already in the user's browser cache As a result, the only thing that needs to be loaded is the web part bundle, which makes the page load faster.

The previous example shows how Angular can be loaded from a CDN. However, a public CDN is not required. The previous example shows how to load Angular from a CDN, but using a public CDN isn't required. The configuration allows you to point to any location: public CDN, privately hosted repository, or SharePoint Document Library. In the configuration, you can point any location from a public CDN, a privately hosted repository, to a SharePoint Document Library. As long as the users of your Web Parts can access the specified URLs, the Web Parts will work as expected. As long As users working with your web parts can access the specified URLs, your web parts will work as expected.

CDNs are optimized for fast resource delivery across the globe. Another benefit of referencing scripts from CDNs is that a particular script may already have been used on another website that the The additional advantage of referencing scripts from public CDNs is that there's a chance that the same script has been used on some other website the user has visited in the past. Since the script is then already cached in the local browser it would not have to be downloaded again specifically for your web part. Because the script is already present in the local browser's cache, it wouldn't need to be downloaded specifically for your web part, which would make the page with the web part on it load even faster.

Some organizations don't allow access to public CDNs from the corporate network. In such cases, using a privately hosted storage location for commonly used JavaScript frameworks is a great alternative. Because your organization hosts the libraries, it could also control the cache headers, which could help you optimize your resources for performance even further.

JavaScript libraries formats

Different JavaScript libraries are built and packaged in different ways. Some are packed as modules, while others consist of simple scripts that are executed in the global area. (Such scripts are often referred to as non-module scripts.) Some are packaged as modules, while others are plain scripts that run in the global scope (these scripts are often referred to as non-module scripts). When loading JavaScript libraries from a URL, how you register an external script in a SharePoint Framework project depends on the format of the script. There are different module formats, for example AMD, UMD or CommonJS; All you need to know is whether or not the script in question is a module. There are multiple module formats, such as AMD, UMD, or CommonJS, but the only thing that you've to know is if the particular script is a module or not.

When registering scripts packaged as modules, the only thing that you've to specify is the URL where the particular script should be downloaded from . Dependencies to other scripts are handled inside the script's module construct.

Non-module scripts require, at minimum, the URL from where the script should be downloaded and the name of the variable with which the script is registered in the global scope. If the non-module script depends on other scripts, these can be listed as dependencies scripts, they can be listed as dependencies. Let's have a look at a few examples.

Angular v1.x is a non-module script. If you want to specify it as an external resource in a SharePoint Framework project, specify its URL and the name of the global variable with which it should be registered: Angular v1.x is a non-module script. You register it as an external resource in a SharePoint Framework project by specifying its URL and the name of the global variable it should register with:

It is important that the name given in the property exactly matches the name the script uses. This allows it to correctly expose itself to other scripts that may depend on it. It's important that the name specified in the property corresponds to the name used by the script. That way it can correctly expose itself to other scripts that might depend on it.

ngOfficeUIFabric, the Angular directives for Office UI Fabric, is a UMD module that depends on Angular. The dependency on Angular is already in the module processed. To register you only have to enter the module URL: The dependency on Angular is already handled inside the module, so to register it, all you need to specify is its URL:

jQuery is an AMD script, so this simple line of code is sufficient for registration: To register it, you could simply use:

Imagine now that you wanted to use jQuery with a jQuery plug-in that itself is distributed as a non-module script.

If you registered both scripts by using the following code, loading the web part would likely result in an error. and the plug-in wouldn't be able to register itself with jQuery.

As mentioned earlier, you can specify dependencies for non-module plug-ins in the SharePoint Framework. These dependencies are specified in the property: As mentioned previously, SharePoint Framework allows you to specify dependencies for non-module plug-ins. These dependencies are specified using the property:

Each dependency specified in the property must reference a different dependency in the section in the file config / config.json Each dependency specified in the property must point to another dependency in the section of the config / config.json file.

If you tried to build the project now, an error would be reported again. This time it would be criticized that you are not allowed to specify a dependency to a non-module script script.

To solve this problem, all you need to do is to register jQuery as a non-module script:

How to set the script simpleWeather to be loaded to jQuery and that jQuery should be available under a globally available variable that the jQuery plug-in simpleWeather required to register yourself. This way you specify that the simpleWeather script should be loaded after jQuery, and that jQuery should be available under a globally available variable, which is required by the simpleWeather jQuery plug-in to register itself.

Note

Note the following: The entry for registering jQuery will be jquery used as the name for the external resource, however jQuery as the name for the global variable. The name of the external resource is the name you use in the statements of the type in your code. This is also the name that must correspond to the TypeScript type declarations. The name of the global variable, specified via the property, is the name that other scripts know, for example plug-ins that are based on the library. For some libraries these names can be identical. However, this is not necessarily the case, and you should carefully check that you are using the correct names to avoid problems jquery for the external resource name, but jQuery as the global variable name. The name of the external resource is the name that you use in the statements in your code. This is also the name that must match TypeScript type declarations. The global variable name, specified by using the property, is the name known to other scripts such as plug-ins built on top of the library. While for some libraries these names might be the same, it's not required, and you should carefully check that you're using correct names to avoid any problems.

It is difficult to manually determine whether the script you are trying to load is a module or a non-module script. This is especially true when the script you are trying to load is minimized. If the script is hosted on a publicly available URL, you can use the free Rencore SharePoint Framework Script Check tool to determine the script type. The tool also determines whether the hosting location from which you are loading the script is configured correctly. This is especially the case if the script that you're trying to load is minified. If your script is hosted on a publicly accessible URL, you can use the free Rencore SharePoint Framework Script Check tool to determine the type of script for you. Additionally, this tool lets you know whether the hosting location from which you're loading the script is properly configured.

Non-module scripts considerations

Many JavaScript libraries and scripts developed in the past are distributed as non-module scripts. While the SharePoint Framework supports loading non-module scripts, you should refrain from using them whenever possible. Many JavaScript libraries and scripts developed in the past are distributed as non-module scripts. While the SharePoint Framework supports loading non-module scripts, you should strive to avoid using them whenever possible.

Non-module scripts are registered in the global scope of the page: a script loaded by one web part is also available to all other web parts on the page. If you have two web parts, each using a different version of jQuery, and both are loaded as non-module scripts, the last web part loaded would overwrite any previously registered versions of jQuery the page: a script loaded by one web part is available to all other web parts on the page. If you had two web parts using different versions of jQuery, both loaded as non-module scripts, the web part that loaded the last would overwrite all previously registered versions of jQuery.

As you can imagine, this could lead to unpredictable results and problems that are difficult to debug and that would only occur in certain scenarios: for example, only if other web parts are used on the page that use a different version of jQuery, As you can imagine, this could lead to unpredictable results, and it would be hard to debug issues that would occur only in certain scenarios, such as only with other web parts by using a different version of jQuery on the page and only when they load in a particular order. The modular architecture solves this problem by isolating the scripts. The module architecture solves this problem by isolating scripts and preventing them from affecting each other.

When you should consider bundling

Bundling existing JavaScript libraries into your web part can result in large web part files and dramatically degrade the performance of pages using that web part. In general, you should avoid bundling JavaScript libraries with your web parts. However, there are several scenarios in which bundling can be beneficial: Bundling existing JavaScript libraries into your web part can lead to large web part files and can cause poor performance of pages using that web part. While you should generally avoid bundling JavaScript libraries with your web parts, there are scenarios where bundling could work to your advantage.

If you're building a standard solution that should work on every intranet, bundling all your resources with your web part can help you ensure that your web part works as expected; after all, you don't know beforehand where your solution will be installed. If you have all of the dependencies in your web part's bundle file, it can work properly even if an organization does not allow resource downloads from CDNs or other external locations. Because you don't know upfront where your solution will be installed, including all dependencies in your web part's bundle file allows it to work correctly, even if the organization doesn't allow downloading resources from a CDN or other external location.

If your solution consists of many web parts that share some functionality with each other, it would be better to build the shared functionality as a separate library and reference it as an external resource in all web parts. Users would then only have to download the shared library once and reuse it with all web parts way users need to download the common library only once and reuse it with all web parts.

SummarySummary

When building client-side web parts on the SharePoint Framework, you can benefit from existing JavaScript libraries to build powerful solutions -Framework allows you to either bundle these libraries together with your web parts or load them as an external resource. The generally recommended strategy is to load existing libraries from a url. In some scenarios, however, bundling also has advantages. It is therefore essential that you carefully analyze your requirements and choose the approach that best meets those requirements. While loading existing libraries from a URL is generally the recommended approach, there are scenarios where bundling might be beneficial, and it's essential that you evaluate your requirements carefully to choose the approach that best meets your needs.

More articlesSee also