Creating a Single Page Application

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

1. Create an SDF SuiteCloud 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 project or open an existing SuiteCloud project where you want to add SPAs.

2. 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.

3. 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> 
   
                 

4. Create the following files and folders for each SPA implementation. For the SPA source and SPA File Cabinet output paths for each SuiteCloud project type, see Local Project Folders and Files for Single Page Applications.

   If you're using a sample SPA project as a template, ensure that you update the folder names, file names, and contents for your project.

   1. SPA folder - Create this folder in the SPA Source path. This folder is where you'll store the source files for your SPA. Each SPA in the SuiteCloud 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 SuiteCloud Project Structure for Single Page Applications.

   2. SPA client script and SPA server script - If you copied the folder from a sample SPA project, the SpaClient and SpaServer scripts with the minimum content are already in the SPA 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 - This folder is optional and, if available, must be located inside the SPA folder. Use it to store assets like style sheets and images.

      Access assets through the endpoint for your project type:

      • For SuiteApp projects, use /spa-app/<ApplicationId>/<SpaFolder>/assets/<path_to_asset>. For example, an image at src/SuiteApps/com.netsuite.spa/helloworld/assets/logo.png is available at /spa-app/com.netsuite.spa/helloworld/assets/logo.png.

      • For ACPs, use /spa/<CustomURL>/assets/<path_to_asset>, where <CustomURL> is the value in the SPA object definition's url field. For example, an image at src/SuiteScripts/helloworld/assets/logo.png is available at /spa/<CustomURL>/assets/logo.png.

      In both endpoints, <path_to_asset> is the asset file's relative path in the assets folder.

   4. SPA object definition XML file - You can copy the SPA object definition file from a sample SPA 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 SPA 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 SuiteCloud 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 the Deployable File Cabinet path, 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> 
      
                        

      The basic XML definition for an SPA object in an ACP looks like the following:

                          <singlepageapp scriptid="custspa_acp_hello_world_ts">
          <name>Hello World</name>
          <description>This is an account customization project that uses NetSuite UIF components.</description>
          <url>helloworld-acp-spa</url>
          <folder>[/SuiteScripts/helloworld/]</folder>
          <clientscriptfile>[/SuiteScripts/helloworld/SpaClient.js]</clientscriptfile>
          <serverscriptfile>[/SuiteScripts/helloworld/SpaServer.js]</serverscriptfile>
          <assetsfolder>[/SuiteScripts/helloworld/assets/]</assetsfolder>
      </singlepageapp> 
      
                        

      For a complete example showing all the supported fields, see Single Page Application XML Definition Example.

5. Create the root component for your SPA and save the script in the SPA folder.

   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:

   1. 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"
      } 
      
                        

   2. 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"
          }
      } 
      
                        

   3. 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.

   The following examples show the SPA-related project files before you build the project:

6. Build the SuiteCloud project. The build process transpiles the source files in the SPA Source path and stores the converted files in the Deployable File Cabinet path.

   You can use any standard toolchain to transpile and convert your SPA source files, or use the gulpfile.mjs from the sample SPA projects. For details about the tasks in the gulpfile.mjs, see Build Process for SuiteCloud Projects with Single Page Applications.

   To use the gulpfile.mjs, 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 the SPA Source path and saves the result in a new build folder.

   • npm run bundle - To bundle the SuiteCloud project. This task takes the transpiled sources from the build folder and bundles them together. The result is saved in the Deployable File Cabinet path and is ready to be deployed to the target NetSuite account.

   After you build and bundle the project, the SPA-related project files look like this:

7. Validate and deploy the SuiteCloud project. If you're using the gulpfile.mjs from the sample SPA projects, run npm run deploy to bundle and deploy the SuiteCloud project to the target NetSuite account.

   If you prefer to deploy the SuiteCloud project from your NetSuite SDK tool, see References to SuiteCloud SDK Tools for guidance.

8. When the SuiteCloud project 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.

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.

Related Topics