Creating a Single Page Application

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

Before you start, make sure you've completed the prerequisite tasks and you've 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're creating an SPA with the SuiteCloud IDE Plug-in for WebStorm, note that the SPA object type is not listed in the New Custom Object window.

Likewise, script templates for the SPA client script and SPA server script are not available when you create a new SuiteScript file. You'll need to manually create the SPA object definition and SPA script files. Alternatively, you can start with a sample SPA SuiteApp or 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, check the help topic for your preferred NetSuite SDK tool. See References to SuiteCloud SDK Tools.

Alternatively, you can start with a sample SPA SuiteApp 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, check the help topic for your preferred NetSuite SDK 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 into 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're using a sample SuiteApp project as a template, ensure that you update the folder names, file names, and contents for your project.
1. SPA folder (src/SuiteApps/<ApplicationID>/<SpaFolder>) – This folder is where you'll store the source files for your SPA. Each SPA in the SuiteApp project needs its own 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 content are already in the src/SuiteApps/<ApplicationID>/<SpaFolder> folder. You can use these scripts as a starting point, and 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. Use it to store assets like style sheets and images. Your SPA can access these assets through the asset endpoint /spa-app/<ApplicationID>/<SpaFolder>/assets/<path_to_asset>, where <path_to_asset> is the asset file's relative path in 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 manually create a new XML file for your SPA object. Save this file in the src/Objects folder. If you're using the XML definition file from a sample project, be sure to update the file name and edit its contents (such as the script ID and paths) to match your project details.
  
  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 in the SuiteApp project needs its own SPA object definition XML file in the Objects folder.
  - The scriptid specified in the object definition must match the SPA object definition file name.
  - 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 is inside src/FileCabinet/SuiteApps/<ApplicationID>/ (where the transpiled files are saved after you run the build). In the XML definition, don't 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 add a 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 inside the appropriate folder under src/SuiteApps/<ApplicationID>/<SpaFolder>.

Go to NetSuite UIF for information about the components and APIs you can use to develop your SPA. To access NetSuite UIF, copy this URL into 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:

In the package.json file, add @oracle/suitecloud-uif-types and typescript to 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"
} 

                  
```

In tsconfig.json, add @oracle/suitecloud-uif-types as an additional type root.

For example:

                    "compilerOptions": {
    "typeRoots": {
        "node_modules/@types",
        "node_modules/@oracle/suitecloud-uif-types"
    }
}

Open a terminal or command line, and run npm i to install dependencies.

Important:

After you define the root component, import it in the SPA client script and pass 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 looks like this:

                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 src/SuiteApps/<ApplicationID>/<SpaFolder> and stores the converted files in src/FileCabinet/SuiteApps/<ApplicationID>/<SpaFolder>.

You can use any standard tool to transpile and convert your SPA source files, or use the gulpfile from the sample SPA SuiteApp projects. For details about the tasks 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 these 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 looks like this:
```
                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're using the gulpfile, 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 tool, see References to SuiteCloud SDK Tools for guidance.
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