Add Third-Party Tools or Libraries to Your Oracle JET App

6 Add Third-Party Tools or Libraries to Your Oracle JET App

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

If you used command-line tooling to scaffold your app, you will install the library and make modifications to appRootDir/path_mapping.json . If you created your app using any other method and are using RequireJS, you will add the library to your app 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 app, do one of the following:

If you created your app with command-line tooling, perform the following steps.
1. 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
```
2. Add the new library to the path mapping configuration file.
  1. Open appRootDir/path_mapping.json for editing.
    
    A portion of the file is shown below.
```
{
 
  "use": "local",

  "cdns": {
    "jet": "https://static.oracle.com/cdn/jet/16.0.0/default/js",
    "css": "https://static.oracle.com/cdn/jet/16.0.0/default/css",
    "config": "bundles-config.js"
    },
    "3rdparty": "https://static.oracle.com/cdn/jet/16.0.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.x.x"
      },
      "release": {
        "src": "knockout-latest.js",
        "path": "libs/knockout/knockout-#{version}.js",
        "cdnPath": "knockout/knockout-3.x.x"
      }
    },

... contents omitted
```
  2. 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": {
      "cwd": "node_modules/my-library/dist",
      "debug": {
        "src": "my-library.debug.js",
        "path": "libs/my-library/my-library.debug.js"
      },
      "release": {
        "src": "my-library.js",
        "path": "libs/my-library/my-library.js"
      }
    },
...
```
    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 the existing entry that you copy to modify includes "cdn": "3rdparty", remove it from the newly-created entry for your library. This line references the Oracle JET third-party area on the content distribution network managed by Oracle. Your library won't be hosted there and keeping this line will cause a release build to fail at runtime by mapping the path for your library to a non-existent URL.
    
    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 app, perform the following steps to add the tool or library.
1. In the app’s /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.x.x',
    'jquery': 'libs/jquery/jquery-3.x.x.min',
    ... contents omitted
    'text': 'libs/require/text',
    'my-library': 'libs/my-library/my-library
  },
  require(['knockout', 'my-library'],
  function(ko) // this callback gets executed when all required modules are loaded
  {
      // add any startup code that you want here
  }
);
```