SuiteApp Project Structure for Single Page Applications

To use NetSuite UIF with single page applications (SPAs), you need a specific folder structure to convert the source files before you deploy the SuiteApp project. This folder structure lets you use JavaScript or TypeScript in your source files. During conversion, the SPA source files are transpiled and the converted files are saved in a different folder in the project directory.

You can find sample SuiteApp projects with SPAs in the SuiteCloud Project Repository on Oracle Samples GitHub. For more information, see Single Page Application Samples.

For information about SDF SuiteApp projects, see SuiteApp Projects and SuiteCloud Project Structure and File Components.

Project Structure for SDF SuiteApps with SPAs

SDF SuiteApp projects with SPAs need to follow this structure:

  • /src/SuiteApps/<ApplicationID>/<SpaFolder> – This SPA folder holds the SPA server script, SPA client script, and the application's root component. It can also include the assets folder for static files.

  • /test – Holds unit tests and test stubs.

  • /src/manifest.xml and /src/deploy.xml – These files contain the SuiteApp configuration.

  • /src/Objects/custspa_xxx.xml – The XML object definition file for the SPA SDF custom object.

  • /src/FileCabinet/SuiteApps/<ApplicationID>/<SpaFolder> – This folder holds the transpiled and converted sources that get pushed to NetSuite when you deploy the SuiteApp. You can use the gulpfile from the sample SPA projects to run the build and bundle tasks that convert the SPA source files (see Build Process for SuiteApp Projects with Single Page Applications). Or, you use your own tool to transpile and convert the files, and save the converted files in this folder.

    Note:

    All JavaScript files in the src/FileCabinet/SuiteApps folder must use the Asynchronous Module Definition (AMD) format.

If you have non-SPA script files in your SuiteApp project, take note of the following when using the gulpfile from the sample projects:

  • If you have JavaScript and AMD script files, save them directly in the /src/FileCabinet/SuiteApps/<ApplicationID> folder. Keep them outside the SPA folder (if it already exists) because the gulpfile regenerates that folder each time you run a bundle task.

  • Don't place AMD script files inside the /src/SuiteApps/<ApplicationID>/<SpaFolder>. The gulpfile assumes that all files in that folder are in ECMAScript Modules (ESM) format. If you include AMD scripts, the gulpfile treats them as ESM and tries to convert them to AMD, which causes errors.

  • The gulpfile only processes files inside the SPA folders, anything outside is ignored. If you want to place scripts in the /src/SuiteApps/<ApplicationID> folder, you'll need to handle building, bundling, and moving those scripts to the src/FileCabinet/SuiteApps/<ApplicationID> folder for deployment.

  • The gulpfile is designed specifically for converting SPA scripts. If you want to use it to convert non-SPA scripts in TypeScript and ESM, you'll need to handle any errors that may occur during this process.

For more information about the gulpfile, see Build Process for SuiteApp Projects with Single Page Applications.

The following shows a sample folder structure for an SPA SuiteApp after running the build and bundle tasks implemented in the gulpfile.

            <ApplicationID>
├── build/
├── node_modules/ 
├── src/
│   ├── FileCabinet/
│         ├── SuiteApps/<ApplicationID>/
│               ├── <OtherScripts>/
│               ├── <SpaFolder>/
│                    ├── assets/
│                    ├── SpaClient.js
│                    └── SpaServer.js
│         └── Web Site Hosting Files/
│   ├── InstallationPreferences/
│   ├── Objects/
│         └── custspa_helloworld.xml
│   ├── SuiteApps/<ApplicationID>/
│         ├── <SpaFolder>/
│               ├── assets/
│               ├── HelloWorld.tsx
│               ├── SpaClient.tsx
│               └── SpaServer.tsx
│   ├── Translations/
│   ├── deploy.xml
│   └── manifest.xml
├── test/
├── gulpfile.mjs
├── jest.config.js
├── package.json
├── suitecloud.config.js
├── tsconfig.json
└── tsconfig.test.json 

          

Related Topics

General Notices