Creating a Single Page Application

The following procedure describes how to create single page applications (SPAs) in an SDF SuiteApp project.

Before you start, make sure you have completed the prerequisite tasks and you have read and understood the concepts discussed in the following topics:

Components and Structure of Single Page Applications – Describes the project folder structure required to implement SPAs.
NetSuite User Interface Framework for Single Page Applications – Describes how to access and use NetSuite UIF to develop SPAs.
Single Page Application Samples – Provides sample SPA SuiteApps, from basic SuiteApps that you can use as a template to more complex SuiteApps that demonstrate NetSuite UIF features and use SuiteScript to handle data.
Prerequisites for Single Page Applications – Describes the prerequisite setup tasks that must be completed before working on SPAs.

Note:

If you plan to create an SPA using SuiteCloud IDE Plug-in for WebStorm, keep in mind that the SPA object type is not listed in the New Custom Object window.

Similarly, script templates for the SPA client script and SPA server script are not available when you select a new SuiteScript file. You need to manually create the SPA object definition and SPA script files. Alternatively, you can use the sample SPA SuiteApps as a starting point, or you can copy the structure from an existing SPA.

To create an SDF SuiteApp project with a single page application:

Create an SDF SuiteApp project. If you need guidance on how to perform this task using your preferred NetSuite SDK development tool, see References to SuiteCloud SDK Tools.

Alternatively, you can use one of the sample SPA SuiteApps as a starting point or open an existing SuiteApp project where you want to add SPAs.
Set up the target NetSuite account for your project. If you need guidance on how to perform this task using your preferred NetSuite SDK development tool, see References to SuiteCloud SDK Tools.

In the manifest.xml file, add the SuiteScript Server (SERVERSIDESCRIPTING) feature dependency. You can copy the following code sample to your manifest.xml file.

                <dependencies>
    <features>
        <feature required="true">SERVERSIDESCRIPTING</feature>
    </features>
</dependencies>

Create the following files and folders for each SPA implementation.

If you are using a sample SuiteApp project as a template, ensure that you update the folder names, file names, and contents based on your project.
1. SPA folder (src/SuiteApps/<ApplicationID>/<SpaFolder>) – This folder is where you will store your source files for your SPA. Each SPA implementation in the SuiteApp project must have a unique folder. Inside each SPA folder, you can organize your files into sub-folders. For guidance on creating and organizing the folder for your source files, see SuiteApp Project Structure for Single Page Applications.
2. SPA client script and SPA server script – If you copied the folder from the sample project, the SpaClient and SpaServer scripts with the minimum required content are already included the src/SuiteApps/<ApplicationID>/<SpaFolder> folder. You can use these scripts as a starting point. You can also change the file names if you prefer. For information about the script structure and examples of SuiteScript modules that you can add to these scripts, see Developing Single Page Applications.
  
  If you want to create these scripts manually, ensure that you save them inside the SPA folder.
3. SPA assets folder (src/SuiteApps/<ApplicationID>/<SpaFolder>/assets) – This folder is optional and, if available, must be located inside the SPA folder. It can be used to store assets such as style sheets and images. These assets can be accessed by your SPA through the asset endpoint /spa-app/<ApplicationID>/<SpaFolder>/assets/<path_to_asset>, where <path_to_asset> is the relative path to the asset file within the assets folder.
  
  For example, an image located at src/SuiteApps/com.netsuite.spa/helloworld/assets/logo.png can be accessed using the endpoint: /spa-app/com.netsuite.spa/helloworld/assets/logo.png.
4. SPA object definition XML file – You can copy the SPA object definition file from a sample project, or you can manually create a new XML file for your SPA object. Save this file in the src/Objects folder. If you are using the XML definition file from the sample project, be sure to update the file name and edit its contents (such as the script ID and paths) to match the details of your project.
  
  SPAs are defined in SDF as a singlepageapp SDF custom object. For more information, see Single Page Applications as XML Definitions.
  
  Follow these guidelines for the SPA object XML definition file:
  - Each SPA implementation in the SuiteApp project must have its own SPA object definition XML file stored in the Objects folder.
  - The scriptid specified in the object definition must match the file name of the SPA object definition file.
  - The paths specified in the object definition are relative to the src/FileCabinet/ folder. Take note of the following:
    - The target location for the SPA folder must be inside src/FileCabinet/SuiteApps/<ApplicationID>/ (where the transpiled files will be saved after running the build). In the XML definition, you do not need to include src/FileCabinet in the path.
    - The path specified for the SPA client script (clientscriptfile) and SPA server script (serverscriptfile) must point to a location inside the SPA folder.
    - The assets folder is optional. If you provided a folder path in the assetsfolder field of the SPA object definition, then you also need to have the assets folder in the SPA folder.
  The basic XML definition for an SPA object in a SuiteApp looks like the following:
```
                    <singlepageapp scriptid="custspa_helloworld"> 
    <name>Hello World</name> 
    <description>This is a sample SuiteApp that uses NetSuite UIF components.</description> 
    <url>helloworld-suiteapp-spa</url> 
    <folder>[/SuiteApps/com.netsuite.spa/helloworld/]</folder> 
   <clientscriptfile>[/SuiteApps/com.netsuite.spa/helloworld/SpaClient.js]</clientscriptfile> 
    <serverscriptfile>[/SuiteApps/com.netsuite.spa/helloworld/SpaServer.js]</serverscriptfile> 
    <assetsfolder>[/SuiteApps/com.netsuite.spa/helloworld/assets/]</assetsfolder>
</singlepageapp> 

                  
```
  For a complete example showing all the supported fields, see Single Page Application XML Definition Example.
Create the root component for your SPA, and save the script file inside the appropriate folder under src/SuiteApps/<ApplicationID>/<SpaFolder>.

Go to NetSuite UIF for information about the components and APIs that you can use to develop your SPA. To access NetSuite UIF, copy this URL to your browser and replace <AccountID> with your NetSuite account ID: https://<AccountID>.app.netsuite.com/ui/apps/catalog.nl.

If you want to use the NetSuite UIF TypeScript type declarations, follow these steps to install the @netsuite-uif-types package:
1. In the package.json file, add @oracle/suitecloud-uif-types and typescript to the devDependencies and specify the appropriate version based on the NetSuite version that you are developing for.
  
  For example:
```
                    "devDependencies": {
    "@oracle/suitecloud-uif-types": "^7.0.0",
    "typescript": "^5.2.0"
} 

                  
```
2. In the tsconfig.json, include @oracle/suitecloud-uif-types as an additional type root.
  
  For example:
```
                    "compilerOptions": {
    "typeRoots": {
        "node_modules/@types",
        "node_modules/@oracle/suitecloud-uif-types"
    }
} 

                  
```
3. Open a terminal or command line, and run npm i to install dependencies.
Important:
After defining the root component, you must import the component from the SPA client script and provide it as a parameter to the setContent(rootComponent) method. For more information, see Single Page Application Client Script.

At this point, your SuiteApp project folder structure should look something like the following:
```
                com.netsuite.spa
├── src/
│   ├── FileCabinet/
│         ├── SuiteApps/com.netsuite.spa/
│         └── Web Hosting Files
│   ├── InstallationPreferences/
│   ├── Objects/
│         └── custspa_helloworld.xml
│   ├── SuiteApps/com.netsuite.spa/
│         └── helloworld/
│               ├── 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 

              
```
Build the SuiteApp. The build process transpiles the source files in the src/SuiteApps/<ApplicationID>/<SpaFolder> folder and stores the converted files in the src/FileCabinet/SuiteApps/<ApplicationID>/<SpaFolder> folder.

You can use any standard tool to transpile and convert your SPA source files, or you can use the gulpfile provided in the sample SPA SuiteApp projects. For more information about the tasks implemented in the gulpfile, see Build Process for SuiteApp Projects with Single Page Applications.

To use the gulpfile, open a terminal or command line, and run the following NPM tasks from the src folder:
- npm i – To install build dependencies.
- npm run build – To build the project. This task runs the TypeScript compiler on the files in src/SuiteApps/<ApplicationID>/<SpaFolder> and saves the result in a new build folder.
- npm run bundle – To bundle the SuiteApp. This task takes the transpiled sources from the build folder and bundles them together. The result is saved in src/FileCabinet/SuiteApps/<ApplicationID>/<SpaFolder> and is ready to be deployed to the target NetSuite account.
After building the SuiteApp, your project folder structure should look something like the following:
```
                com.netsuite.spa
├── build/
├── node_modules/
├── src/
│   ├── FileCabinet/
│         ├── SuiteApps/com.netsuite.spa/
│               └── helloworld
│                     ├── assets/               
│                     ├── SpaClient.js
│                     └── SpaServer.js
│         └── Web Hosting Files
│   ├── InstallationPreferences/
│   ├── Objects/
│         └── custspa_helloworld.xml
│   ├── SuiteApps/com.netsuite.spa/
│         └── helloworld/
│               ├── 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 

              
```
Validate and deploy the SuiteApp project. If you are using the gulpfile, you can run npm run deploy to bundle and deploy the SuiteApp to the target NetSuite account.

If you prefer to deploy the SuiteApp from your NetSuite SDK development tool, see References to SuiteCloud SDK Tools for guidance on how to perform this task.
When the SuiteApp is successfully deployed, you can open the single page application in NetSuite.
- To see the list of single page applications in your account, go to Customization > Scripting > Single Page Applications. To open the management page for an SPA, click the SPA name.
- To open a single page application:
  - From the SPA list, click the link icon next to the SPA name.
  - From the SPA record, click the link in the URL field.

After setting up the SPA SuiteApp project, you can continue to develop and configure your SPA. For more information about these topics, see Developing Single Page Applications and Single Page Application Management.

References to SuiteCloud SDK Tools

SuiteCloud Software Development Kit (SDK) are tools that enable you to customize accounts through SuiteCloud Development Framework (SDF). If you need guidance on how to perform specific tasks using these tools, refer to the referenced help topics in the following table. These tasks are referenced in Creating a Single Page Application.

Task	General Information	SuiteCloud Extention for Visual Studio Code	SuiteCloud IDE Plug-in for WebStorm	SuiteCloud CLI for Java	SuiteCloud CLI for Node.js
Create a SuiteApp project	SuiteApp Projects	Creating a SuiteCloud Project in SuiteCloud Extension for Visual Studio Code	Creating a SuiteApp Project in SuiteCloud IDE Plug-in for WebStorm	createproject	project:create
Set up account	—	Setting Up NetSuite Accounts in SuiteCloud Extension for Visual Studio Code	SuiteCloud IDE Plug-in for WebStorm Account Setup	authenticate	account:setup
Validate a SuiteApp project	SuiteCloud Project Validation	Deploying a SuiteCloud Project to Your NetSuite Account with SuiteCloud Extension for Visual Studio Code	Validating a SuiteCloud Project with SuiteCloud IDE Plug-in for WebStorm	validate	project:validate
Deploy a SuiteApp project	SuiteCloud Project Deployment Preparation	Deploying a SuiteCloud Project to Your NetSuite Account with SuiteCloud Extension for Visual Studio Code	Deploying a SuiteCloud Project to Your NetSuite Account with SuiteCloud IDE Plug-in for WebStorm	deploy	project:deploy

Task

General Information

SuiteCloud Extention for Visual Studio Code

SuiteCloud IDE Plug-in for WebStorm

SuiteCloud CLI for Java

SuiteCloud CLI for Node.js

Create a SuiteApp project

SuiteApp Projects

Creating a SuiteCloud Project in SuiteCloud Extension for Visual Studio Code

Creating a SuiteApp Project in SuiteCloud IDE Plug-in for WebStorm

createproject

project:create

Set up account

—

Setting Up NetSuite Accounts in SuiteCloud Extension for Visual Studio Code

SuiteCloud IDE Plug-in for WebStorm Account Setup

authenticate

account:setup

Validate a SuiteApp project

SuiteCloud Project Validation

Deploying a SuiteCloud Project to Your NetSuite Account with SuiteCloud Extension for Visual Studio Code

Validating a SuiteCloud Project with SuiteCloud IDE Plug-in for WebStorm

validate

project:validate

Deploy a SuiteApp project

SuiteCloud Project Deployment Preparation

Deploying a SuiteCloud Project to Your NetSuite Account with SuiteCloud Extension for Visual Studio Code

Deploying a SuiteCloud Project to Your NetSuite Account with SuiteCloud IDE Plug-in for WebStorm

deploy

project:deploy

To create an SDF SuiteApp project with a single page application:

References to SuiteCloud SDK Tools

Related Topics