Adding Third-Party Tools or Libraries to Your Oracle JET Application

You can add third-party tools or libraries to your Oracle JET application. The steps to take will vary, depending on the method you used to create your application.

If you used command-line tooling to scaffold your application, you will install the library and make modifications to src/js/path_mapping.json . If you created your application using any other method and are using RequireJS, you will add the library to your application and update the RequireJS bootstrap file, typically main.js.

Note:

This process is provided as a convenience for Oracle JET developers. Oracle JET will not support the additional tools or libraries and cannot guarantee that they will work correctly with other Oracle JET components or toolkit features.

To add a third-party tool or library to your Oracle JET application, do one of the following:

If you created your application with command-line tooling, perform the following steps.

In your main project directory, enter the following command in a terminal window to install the library using npm:
```
npm install library-name --save
```
For example, enter the following command to install a library named my-library:
```
npm install my-library --save
```

Add the new library to the path mapping configuration file.

Open src/js/path_mapping.json for editing.

A portion of the file is shown below.

{
  "baseUrl": "js",
  "use": "local",

  "cdns": {
    "jet": "https://static.oracle.com/cdn/jet/v5.2.0/default/js",
    "3rdparty": "https://static.oracle.com/cdn/jet/v5.2.0/3rdparty"
  },

  "libs": {

    "knockout": {
      "cdn": "3rdparty",
      "cwd": "node_modules/knockout/build/output",
      "debug": {
        "src": "knockout-latest.debug.js",
        "path": "libs/knockout/knockout-#{version}.debug.js",
        "cdnPath": "knockout/knockout-3.4.2"
      },
      "release": {
        "src": "knockout-latest.js",
        "path": "libs/knockout/knockout-#{version}.js",
        "cdnPath": "knockout/knockout-3.4.2"
      }
    },

... contents omitted

Copy one of the existing entries in "libs" and modify as needed for your library.

The sample below shows modifications for my-library, a library that contains both minified and debug versions.
```
...
 "libs": {

    "my-library": {
      "cdn": "3rdparty",
      "cwd": "node_modules/my-library/dist",
      "debug": {
        "src": "my-library.debug.js",
        "path": "libs/my-library/my-library.debug.js",
        "cdnPath": ""
      },
      "release": {
        "src": "my-library.js",
        "path": "libs/my-library/my-library.js",
        "cdnPath": ""
      }
    },
...
```
In this example, cwd points to the location where npm installed the library, src points to a path or array of paths containing the files that will be copied during a build, and path points to the destination that will contain the built version.

Note:
If you use a CDN, add the URL to the CDN in the entry for cdnPath.

If you didn’t use the tooling to create your application, perform the following steps to add the tool or library.
1. In the application’s js/libs directory, create a new directory and add the new library and any accompanying files to it.
  
  For example, for a library named my-library, create the my-library directory and add the my-library.js file and any needed files to it. Be sure to add the minified version if available.
2. In your RequireJS bootstrap file, typically main.js, add a link to the new file in the path mapping section and include the new library in the require() definition.
  
  For example, add the highlighted code below to your bootstrap file to use a library named my-library.
```
requirejs.config({
  // Path mappings for the logical module names
  paths: 
  {
    'knockout': 'libs/knockout/knockout-3.4.2',
    'jquery': 'libs/jquery/jquery-3.3.1.min',
    ... contents omitted
    'text': 'libs/require/text',
    'my-library': 'libs/my-library/my-library
  }
  ,
  // Shim configurations for modules that do not expose AMD
  // Updated as needed for your library.
  shim: {
    'jquery': {
      exports: ['jQuery', '$']
    }
  },
  require(['ojs/ojcore', 'knockout', 'jquery', 'my-library'],
  function(oj, ko, $) // this callback gets executed when all required modules are loaded
  {
      // add any startup code that you want here
  }
);
```
  For additional information about using RequireJS to manage your application's modules, see Using RequireJS for Modular Development.