Integrating Third-Party Libraries in SuiteScript 2.1: A Detailed Guide

April 29, 2024 | 6 minute read
Mohammed Kassem
SuiteCloud Advocate
Text Size 100%:

Integrating Third-Party Libraries in SuiteScript 2.1: A Detailed Guide

As SuiteScript developers, we often seek to extend the native capabilities of NetSuite with third-party libraries. This technical deep dive explores the practical aspects of integrating these libraries into SuiteCloud projects. When considering library integration, it's essential to understand the different types of libraries available. Each type serves a unique purpose and has distinct functionality and benefits:

  • AMD (Asynchronous Module Definition) compatible libraries: Libraries that use asynchronous loading and execution that ensure non-blocking operations to improve performance and modularity, making them suitable for complex project structures.
  • UMD (Universal Module Definition) compatible libraries: These libraries provide compatibility across various environments, such as CommonJS, AMD, and global scopes, and offer versatile and flexible code usage across multiple project setups.
  • Non-AMD compatible libraries: For all other libraries, we need to utilize tools like Babel to transform non-AMD formats (CommonJS or ESM) into AMD-compatible modules.

This guide will dive into each of these types, providing you with the knowledge to effectively integrate and leverage third-party libraries in your SuiteScript 2.1 projects.

AMD Compatible Libraries in SuiteScript

To determine if a library is AMD compatible, start by reviewing its official documentation for mentions of AMD or module definitions. Inspecting the library's source code for the presence of the Universal Module Definition (UMD) pattern or define function calls is also insightful. Additionally, checking community forums, issuing trackers, and conducting practical tests with an AMD loader like RequireJS can provide definitive answers regarding AMD compatibility.

The great news is that it’s simple to integrate an AMD-compatible library into SuiteCloud projects.

The amdconfig.json file acts as a guide for the interpreter to locate and utilize AMD-compatible library files. This configuration aligns with the asynchronous and modular nature of AMD to ensure efficient management of dependencies.

Here’s an example of amdconfig.json with the jquery library:

By specifying paths to AMD-compatible libraries, the amdconfig.json in SuiteScript projects guides the SuiteScript interpreter to load the correct modules.

Tips:

  • Keep paths relative: This ensures that your project is portable and not dependent on absolute paths which can vary between environments.
  • Organize dependencies: Group related dependencies together to improve readability and manageability.

Next, you can reference the imported libraries in your SuiteScript 2.1 file. Annotations in script files reference this configuration file to ensure that the scripts utilize the defined AMD modules as per the amdconfig.json settings.

Here’s how you do it:


Script file

The define() method is used to register a factory function with dependencies specified as an array of strings, rather than immediately executing it. The factory function only executes after all its dependencies have been loaded. These dependencies are then passed as arguments to the factory function for modular and efficient code execution.

UMD Compatible Libraries in SuiteScript

Universal Module Definition (UMD) libraries are highly versatile and enable seamless integration across various environments such as AMD, CommonJS, and global scopes. jQuery, Lodash, D3.js, and Underscore are just a few examples that showcase the potential for UMD modules within complex applications.

UMD's strength lies in its ability to recognize and adapt to the context in which it operates, allowing developers to write intelligent, context-aware code.

umd.js core logic usually begins with:

function (global, factory) {

   typeof exports === 'object'

   && typeof module !== 'undefined' ? factory(exports) :

   typeof define === 'function'

   && define.amd ? define(['exports'], factory) :

   (global = typeof globalThis !== 'undefined' ? globalThis : global

   || self, factory(global.Zod = {}));

This function demonstrates UMD's approach to compatibility:

  • In a Node.js environment or any CommonJS-compatible system, it exports the module using module.exports.
  • When in an AMD environment, such as with RequireJS, it registers the module using define().
  • If neither CommonJS nor AMD is detected, UMD falls back to attaching the module to the global object (window), ensuring that the module remains accessible. This commonly happens in the browser environment.

Non-AMD Compatible Libraries in SuiteScript

While SuiteScript is best compatible with AMD-compatible libraries, many don’t conform to this standard out of the box. We’ll need to use shims to intercept API calls and provide a layer of abstraction to ensure that non-AMD libraries, once transpiled, are loaded and used just like any other AMD module.

Let’s walk through integrating a non-AMD library math.js, step by step:

Non-AMD library (math.js)

  1. Create the amdconfig.json file to define paths and shims. The paths help SuiteScript locate your AMD modules, and shims provide the necessary metadata to load non-AMD libraries as if they were AMD modules.



amdconfig.json

  1. With the AMD configuration in place, you can reference your library in SuiteScript files. Add the library file to the NetSuite file cabinet, and then use the defined path to import your library into your SuiteScript file:


Script file

  1. Success! In the script file, we can import in the math module and use the library’s add function in the log.debug JSON argument.

Streamlining Integration with Babel

Developers often use transpilation tools like Babel to convert non-AMD libraries into AMD format. With plug-ins and presets like @babel/preset-env and babel-plugin-transform-es2015-modules-amd, Babel can modify your library code into an AMD module that's ready for SuiteScript consumption. Here's how to set up the process:

  1. Install Babel and plug-ins: Begin by adding the necessary Babel tools to your project using npm:

npm install @babel/core @babel/preset-env babel-plugin-transform-es2015-modules-amd

  1. Configure Babel: Create a .babelrc file or add a Babel configuration section in your package.json. Include the plug-ins and presets required to transform your library:

{

  "presets": ["@babel/preset-env"],

  "plugins": ["transform-es2015-modules-amd"]

}

  1. Transpile the library: Run Babel to transpile your non-AMD library code, specifying the source and the output directory. You can set up a script in your package.json to simplify this process:

"scripts": {

  "build": "babel src --out-dir lib"

}

Once transpiled, modify the AMD configuration and take advantage of shimming to use the transpiled library in your SuiteScript files.

Sandbox Environment: Compatibility & Performance Testing

Proceed with integration in a sandbox environment for initial compatibility testing. Use NetSuite's SuiteScript Profiler and Application Performance Management (APM) tools for performance testing, which can offer detailed insights into execution times and script efficiency. I also recommend monitoring script execution logs for governance usage and potential bottlenecks.

Browser developer tools (like Chrome) can be instrumental in profiling performance for client-side scripts. Combining these tools with thorough testing practices, such as load testing in realistic scenarios, allows you to effectively gauge the impact of third-party libraries on your SuiteCloud project's performance.

Conclusion

The journey to integrate third-party libraries into SuiteScript 2.1 is paved with advanced techniques to take advantage of AMD, UMD, and non-AMD library compatibility.

Click here for a list of known SuiteScript-compatible build time and runtime libraries.

By using Babel and shims, developers can transform and adapt any library to fit the SuiteScript environment. This guide has provided a comprehensive walkthrough of the integration process, from installation and configuration to transpilation and implementation. Embracing these methodologies will streamline your development workflow, ultimately leading to a more robust and dynamic NetSuite ecosystem.

Ready to take it to the next level with examples? Put your learning to action with the third-party integration step-by-step guide using TypeScript, Zod, and Webpack.

Mohammed Kassem

SuiteCloud Advocate


Previous Post

Navigating Third-Party Library Compatibility in SuiteScript 2.1: A Blog Series

Mohammed Kassem | 9 min read

Next Post


Enhancing SuiteScript with Third-Party Libraries: TypeScript, Zod, and Webpack

Mohammed Kassem | 5 min read