Unlock Modern Horizon Design System Components In Your Custom Components Using –fetch-assets-from-instance

The Horizon Design System (HDS) is a powerful resource when building custom UI components in ServiceNow. It provides a rich set of foundational UI elements buttons, inputs, activity streams, and more so you don’t have to reinvent the wheel.

However, there’s a significant catch: the versions of HDS components published to the public NPM registry are behind the versions that actually run on a ServiceNow instance.

The Problem: Public NPM Packages Are Out of Date

For example, the latest version of @servicenow/now-button available on the public NPM registry is 19.8.2-ecd, published over five years ago. By comparison, a Zurich Patch 4 instance includes @servicenow/now-button at version 28.4.1.

This version gap applies to all core Horizon Design System components, and it can significantly limit their usefulness when building modern custom components.

In practice, the versions running on an instance often include:

• Additional theme variables
• New or improved component properties
• Extra events and behaviors

All of these improvements make the components more pleasant – and sometimes far easier – to work with.

Components That Aren’t Published at All

It gets worse: some Horizon Design System components aren’t published to the public NPM registry at all.

For example, now-activity-stream-connected appears in the Horizon Design System documentation, but does not exist on the public registry. At first glance, it can seem like the only way to use it is directly within UI Builder, with no obvious path to using it in your own custom components.

Fortunately, there is a way.

The --fetch-assets-from-instance Flag

The ServiceNow CLI’s ui-component extension includes a powerful flag called:

--fetch-assets-from-instance

(Shorthand: --fa)

This flag is available on both the develop and deploy commands and allows package imports to be resolved directly from your ServiceNow instance, rather than from your local node_modules folder.

What’s a Package Import?

A package import is the statement at the top of your component’s JavaScript file that pulls in a dependency. For example:

import '@servicenow/now-button';

This single import gives you access to all components provided by that package, including:

• now-button
• now-button-bare
• now-button-stateful
• now-button-circular
• now-button-iconic

How It Works Under the Hood

When you run the develop or deploy commands, webpack scans your import statements and attempts to resolve them as packages.

When --fetch-assets-from-instance is enabled:

• The CLI first checks whether the package exists on the connected ServiceNow instance.
• If it exists, the package is not bundled locally.
• Instead, the import is rewritten as an external reference pointing to a relative URL at the /uxasset path.
• If the package does not exist on the instance, resolution falls back to the local node_modules folder.

For example, this import:

import '@servicenow/now-button';

Is transformed into something conceptually similar to:

import '/uxasset/externals/@servicenow/now-button/index.jsdbx';

(The exact path will differ, but this illustrates the idea. I discuss more about this /uxasset path in my previous post about using Next Experience components inside Service Portal widgets.)

When running develop, the CLI also sets up a proxy so that requests to /uxasset on your local dev server are transparently fetched from the connected instance. This means your component works the same way locally and when deployed, as the relative URL always resolves no matter if it’s running locally or on the ServiceNow instance..

Importing a Modern HDS Component

Let’s say you want to use the modern version of @servicenow/now-button from your instance instead of the outdated public NPM version.

From your component project, start development mode with:

snc ui-component develop --fa

Then, in your component’s JavaScript file, simply add:

import '@servicenow/now-button';

There’s no need to run npm install. The package will be fetched directly from your instance.

That’s it – you can now use the same now-button components that exist on your instance.

Discovering More Available Components

Some packages, like @servicenow/now-button, are obvious because they exist on the public registry. Others are only discoverable by inspecting what’s available on your instance.

To see a full list of UI components and the packages they belong to, visit the following path on your instance:

/sys_ux_lib_component_list.do

This page shows:

• Individual component tags (in the Tag field)
• The package they belong to (in the Source script name field)

Example: Activity Stream Components

A great example is the @servicenow/now-activity-stream package, which contains:

• now-activity-stream-connected
• now-activity-stream-compose-connected

Both are part of the Horizon Design System and usable in UI Builder, yet neither is published to the public NPM registry.

Using --fetch-assets-from-instance, you can use them in your own custom components.

First, run develop or deploy with --fa, then import the package:

import '@servicenow/now-activity-stream';

Once imported, you can use the components directly:

import { createCustomElement } from '@servicenow/ui-core';
import snabbdom from '@servicenow/ui-renderer-snabbdom';
import '@servicenow/now-activity-stream'
import styles from './styles.scss';

const view = (state, { updateState }) => (
	<div>
		<now-activity-stream-connected
			table="incident"
			sys_id="8e9bb3f9b701701094bb21208e11a9ab"
			title="Activity"
			isNewRecord="false" />
	</div>
);

createCustomElement('test-component-externals', {
	renderer: { type: snabbdom },
	view,
	styles
});

Your custom component now includes a fully functional ServiceNow activity stream.

Risks and Trade-offs

This technique is powerful, but it does come with risks.

While --fetch-assets-from-instance is an official part of the ServiceNow CLI, many of these components are not officially supported outside their intended contexts (such as UI Builder).

For example, the Activity Stream components are officially supported only when used via UI Builder. If a breaking change is introduced, ServiceNow can seamlessly update how UI Builder uses them during an upgrade.

Your custom component, however, is invisible to that process.

That means:

• You are responsible for testing these components during upgrades
• Breaking changes may require manual fixes
• There is no public compatibility contract for these internal components

This approach is best suited for internal applications and teams that can tolerate and manage this maintenance risk.

Conclusion

The --fetch-assets-from-instance flag unlocks access to the same modern Horizon Design System components that ServiceNow itself uses far beyond what’s available on the public NPM registry.

Used thoughtfully, it allows you to build richer, more consistent custom UI components while avoiding unnecessary duplication of UI logic.

If you’re building custom components, I’d strongly recommend experimenting with this approach.

Feel free to leave a comment below – are you using custom components today? What’s been your experience with the ServiceNow UI development workflow?