SuiteApp Project Structure for Single Page Applications

To use NetSuite UIF with single page applications (SPAs), a specific folder structure is required to convert the source files before deploying the SuiteApp project. With this folder structure, you can use JavaScript or TypeScript in your source files. During the conversion, the SPA source files are transpiled and the converted files are stored in a different folder within the project directory.

Sample SuiteApp projects that use single page applications (SPA) are available in the SuiteCloud Project Repository on Oracle Samples GitHub. For more information, see Single Page Application Samples.

SDF SuiteApp projects with SPAs must have the following structure:

/src/SuiteApps/<ApplicationID>/<SpaFolder> – The SPA folder that contains the SPA server script, SPA client script, and the root component of the application. It can also contain the assets folder for static assets.
/test – Contains unit tests and test stubs.
/src/manifest.xml and /src/deploy.xml – Contains the configuration of the SuiteApp.
/src/Objects/custspa_xxx.xml – The XML object definition file for the SPA SDF custom object.
/src/FileCabinet/SuiteApps/<ApplicationID>/<SpaFolder> – The folder that contains the transpiled and converted sources that are pushed to NetSuite when the SuiteApp is deployed. 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). Alternatively, you can opt to use your preferred tool to transpile and convert the files, and save the converted files in this folder.

Note:
All JavaScript files inside 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 provided in the sample projects:

If you have script files in JavaScript and AMD, you must save them directly inside the /src/FileCabinet/SuiteApps/<ApplicationID> folder. They must be placed outside of the SPA folder (if it already exists) because the gulpfile regenerates this folder each time you run a bundle task.
Do not place AMD script files inside the /src/SuiteApps/<ApplicationID>/<SpaFolder>. The gulpfile assumes that all files within this folder are in ECMAScript Modules (ESM) format. If AMD scripts are included, the gulpfile interprets them as ESM and attempts to convert them to AMD, leading to errors.
The gulpfile processes files inside the SPA folders only, anything outside these folders are ignored. If you want to place scripts inside the /src/SuiteApps/<ApplicationID> folder, you must handle the build, bundle, and transfer of these scripts to the src/FileCabinet/SuiteApps/<ApplicationID> folder that is deployed to NetSuite.
The gulpfile is designed specifically for converting SPA scripts. If you have non-SPA scripts in TypeScript and ESM that you want to convert using the gulpfile, be aware that handling possible errors during this process is your responsibility.

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

For information about the default project structure of SuiteApp projects created using SDF, see SuiteCloud Project Structure and File Components.

Related Topics