Skip to content

SDK 4.0.0

Choose a tag to compare

View all tags
@bryce-godfrey bryce-godfrey released this 04 Sep 21:05
· 2 commits to master since this release
v4.0.0
3ee13e9

🔥 4.0.0 is here! 🔥

The latest release of the @servicenow/sdk just dropped on npm, and it’s a big one.
Internally, we’ve completely overhauled our plugin framework to make APIs more reliable, and way faster to ship. Translation? You’ll be seeing more APIs, more often 🚀.
But the real star of the show:

  • ⚛️ Front-End app support with front end frameworks like React, Vue, Svelte, SolidJS, and others!
  • ⚡️ New Fluent APIs to level up your applications development
  • 🛠️ A rock-solid foundation for even bigger things coming soon

Check out the release notes below, kick the tires, and drop your thoughts on the discussion board. We can’t wait to see what you build with 4.0.0 🙌.

New Fluent APIs

Some new Fluent APIs have been added to make working with certain types of tables easier using the SDK.

Command changes

There are some minor command changes to now-sdk and they can be viewed using --help option for more information.

  • Added clean command
    The clean command will clean out the build output directory, typically dist folder. This is automatically performed as part of the build command, but if you have any other needs to clean out the folder you can use this command.

  • Added pack command
    The pack command will package up the output of a build into an installable archive file. pack is automatically performed as part of the install command. Pack used to be run at the end of build but this was removed since installalso performs pack

  • Added download command
    The download command can be used for downloading complete or incremental metadata from the instance for the application.

Front-end framework support

The SDK now supports building front-end applications with standard frameworks to run on ServiceNow! For this first release, we are natively supporting React out of the box, and we are aiming to support a "bring your own front end" (BYOF) approach. This new feature will let you use a more modern development experience for building UI applications.

To get started building front ends, simply choose a template with included front-end framework support such as now-sdk + fullstack React when running init to get started!

This is just the beginning of the BYOF support we are adding to the SDK and we will be following up soon with more support for providing your own bundler and tooling for other frameworks like Svelte, Vue, etc...

How does it work?

Front-end applications utilize the UiPage Fluent API for bundling and hosting the application and its entry point. The SDK detects importing from an .html page that is being assigned to the html attribute on UiPage Fluent API and bundles your front end into static assets served with your application.
By default, the front-end application code lives in your src/client directory (configurable in now.config.json with the clientDir property). Add all your images, style sheets, fonts, etc. here the same way you would for any typical React application that you're building. The out of the box bundler we have included is Rollup to package up the your front end application.

Example with React:

import { UiPage } from '@servicenow/sdk/core'
import indexPage from '../client/index.html'

UiPage({
    $id: Now.ID['sample-frontend'],
    endpoint: 'x_sampleapp-uipage-fe.do',
    description: 'Sample Front-End Application',
    category: 'general',
    html: indexPage,
    direct: true,
})

In the src/client folder create an index.html page like this:

<html>
<head>
  <title>Sample Front-End Application</title>

  <!-- Initialize globals and Include ServiceNow's required scripts -->
  <sdk:now-ux-globals></sdk:now-ux-globals>

  <!-- Include your React entry point -->
  <script src="./main.tsx" type="module"></script>
</head>
<body>
  <div id="root"></div>
</body>
</html>

In the src/client/* folder add a main.tsx file with your React code, CSS, and other assets to build your application

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './app'

const rootElement = document.getElementById('root')
if (rootElement) {
    ReactDOM.createRoot(rootElement).render(
        <React.StrictMode>
            <App />
        </React.StrictMode>
    )
}

When you are ready, just build and install then open the UI Page on the instance to view your application!

Limitations:

  • Only hash routing is currently supported by UI Pages.
  • Maximum file size of assets is limited to the com.glide.attachment.max_size system property
  • Preloading content linked from HTML isn't supported (rel="preload")
  • Relative style sheets linked from HTML aren't supported (rel="stylesheet"). Import your style sheets into code instead (import "path/to/style-sheet")
  • Relative @import in CSS isn't supported
  • CSS modules aren't supported
  • Server-side rendering and React server components aren't supported

API Changes

  • List API deprecates $id property as it is a coalescing table and uses combination of name, view, sys_domain, element, relationship, and parent properties. The property will not produce build errors but be marked as deprecated.
  • Role API deprecates $id property as it is a coalescing table and uses the name property to generate its key. The property will not produce build errors but will be marked as deprecated.
  • ClientScript API will no longer produce script fields with tagged template literalsscript tag during generation by default. Syntax highlighting for these tags were removed back in 3.0 in favor of Now.include functionality. The tags will not produce build errors, and they do not alter functionality.
//Before
ClientScript({
  script: script`gs.info("hello world")`
  ...
}) 

//After
ClientScript({
  script: `gs.info("hello world")`
  ...
})

Breaking Changes

  • Custom properties have been removed in this version. In versions 3.0 and earlier, you could specify custom properties not included in the type definition on any API. This was helpful for setting custom fields on out-of-box table definitions. However, this feature has been removed in 4.0 to prevent issues caused by allowing arbitrary properties in the API type. This feature would cause AI hallucinations during code generation due to lack of strict type checking on the arbitrary fields that were allowed. We are planning to bring this back soon (4.1+), so if you rely on this in your application please wait or alternatively use the Record API instead if that's a possibility.

For example, you could specify a field called x_customfield on an API like Role in version 3.0 and prior and that field would be automatically added to the build output.

Role({
  $id: Now.ID['my_id'],
  name: 'x_myapp_rolename',
  x_customfield: 'some value'
})

Documentation

https://www.servicenow.com/docs/bundle/zurich-application-development/page/build/servicenow-sdk/concept/servicenow-sdk-landing.html

Support and Issues

Assets 2
Loading
21 Join discussion