Sitecore JavaScript Rendering SDK CLI Tools API reference

Abstract

JSS CLI commands and scripts

During JSS development, you commonly use scripts provided by the JSS CLI (command line interface). These scripts can be run from within a JSS application in your command-line tool of choice (bash, PowerShell, cmd, and so on).

Some JSS commands run globally, for example, jss create.

Other commands are meant to run in the root directory of your JSS application. Such commands might have application-specific arguments. In the root directory of your JSS app, run jss --help and jss <command> --help for application-specific arguments.

Additionally, in applications created with the JSS CLI based on official application samples, you have a set of scripts specific to the application, defined in the package.json file. You can run any scripts defined in the package.json file in a terminal with npm CLI utility provided by Node.js.

Frequently used JSS commands and scripts

The JSS CLI provides the following commands:

jss create

Creates a JSS application. You must provide an application name and a framework.

jss create <your-app-name> <app-template-name>

The command requires the following parameters:

Parameter

Description

Value type

name

The name of the app to create.

String

template

The template to create the app from; corresponds to folders in the official JSS repository

String

The command supports the following optional parameters:

Parameter

Description

Options

Default

Template

--version

Show version number

-

true

all

--help

Show help for the command

-

true

all

--hostName, -r

Sets the hostname of the Sitecore site if this app is deployed to Sitecore.

-

$name.dev.local

all

--repository, -r

Configures the repository to use for creating the JSS app

A repository: <githubusername>/<reponame>

Sitecore/jss

all

--branch, -b

Configures the branch of the repository to use for creating the JSS app

A branch name

master

all

--source, -s

Sources the app template from a local filesystem path, instead of a GitHub repository. Use for custom JSS app templates

A local directory path

-

all

--proxy, -p

Specifies an HTTP proxy when downloading templates.

A local directory path

-

all

--fetchWith

Specifies how the application fetches Sitecore layout and dictionary data.

REST or GraphQL

REST

nextjs, react, angular, vue

--prerender

Specifies the Next.js pre-rendering form for the primary [[...path]].tsx route.

SSG or SSR

SSG

nextjs

--empty

Specifies the app is created empty

-

false

nextjs

Examples

// React-based app using a specific version of JSS
jss create my-jss-app react --branch release/11.0.0

// Next.js-based application with Static Generation and fetching data using GraphQL
jss create my-jss-app nextjs --prerender SSG --fetchWith GraphQL

// Next.js-based application with Server-Side Rendering and fetching data using REST
jss create my-jss-app nextjs --prerender SSR --fetchWith REST

jss setup

This JSS command runs the interactive setup process to optionally provide info about connecting/deploying to a Sitecore instance. The input is saved to the scjssconfig.json file in the app root.

The command supports the following parameters:

Parameter

Description

Value Type

instancePath

Path to the Sitecore Website folder (for example, c:\dev\sitecore\Website)

String

deployUrl

The Sitecore host used to deploy the app (for example, http://myinstance.com/sitecore/api/jss/import)

String

layoutServiceHost

The Sitecore host used to download Layout Service data (for example, http://myinstance.com)

String

apiKey

Sitecore API Key (GUID of item under /sitecore/system/Settings/Services/API Keys/ in the master database, or core database for Sitecore 9.0).

String

deploySecret

Deployment secret (32+ random chars).

String

nonInteractive

Disallows interactive prompts (all other arguments must be passed in this mode).

Boolean

outputFile

The file path for placing the config. Default: ./scjssconfig.json

String

skipValidation

Skip validation of command arguments (for example, for CI).

Boolean

Note

For CI deployments, setup accepts arguments to build the config from variables. Use jss setup --help for details.

jss start

A script defined in the package.json file of your JSS app that starts the application in disconnected mode. Sitecore is not required or used even if available. Content comes from local files.

jss start:connected

A script defined in the package.json file of your JSS app that starts the application in connected mode, where it connects to Sitecore to retrieve the layout data and content but still runs locally.

jss deploy config

Copies the .config file from /sitecore/config to your Sitecore instance's Website/App_Config/zzz folder specified in scjssconfig.json file in the app root. This is a convenience script; you can also manually deploy the JSS app configuration in some other way or have the config owned by the Sitecore instance instead of the JSS app.

The command supports the following parameters:

Parameter

Description

Value type

source

The source path of the config patches to deploy.Default: ./sitecore/config

String

destination

Destination path to deploy to. Defaults to the instancePath set in scjssconfig.json, combined with the sitecoreConfigPath setting from package.json.

String

config

Path to scjssconfig file.Default: ./scjssconfig.json

String

jss deploy app

Shorthand for jss deploy items && jss deploy files. Used to deploy both the app's manifest items (routes, templates, and so on) and a production build of the app's code.

Use jss deploy app --help for options.

Note

The command jss deploy app accepts all options supported by jss deploy items or jss deploy files.

jss deploy items

Use this command when using the code-first JSS development methodology, and you want to build a manifest and deploy items to Sitecore.

The command supports the following parameters:

Parameter

Description

Value type

deployUrl

URL to the Sitecore JSS import service that accepts the package deployment.Default: deployUrl from scjssconfig.json

String

deploySecret

Shared secret to authenticate the deployment with Sitecore.Default: deploySecret from scjssconfig.json

String

config

Path to scjssconfig file.Default: ./scjssconfig.json

String

debugSecurity

Enables diagnosing authentication issues with your deployment. Exposes secrets to output, use only for temporary diagnostics.Default: false

Boolean

skipPackage

If true, it skips the build, manifest, and packaging steps. This can consume existing output from the jss package (via the packageOutputPath parameter) without rebuilding it.Default: false

Boolean

proxy

Specify an HTTP proxy to use when deploying items.

String

acceptCertificate

Whitelists a specific SSL certificate thumbprint, regardless of normal SSL validation. Useful for self-signed certificates.

String

Note

The command jss deploy items has many options that enable modifying how the package deploys, such as excluding content items with --noContent. Run jss deploy items --help to see all the options with descriptions.

When run with default options, jss deploy items also runs jss manifest, and jss package. Options for all of these commands may also be passed to deploy items.

Content, media, or dictionary items are excluded by default for safety if a content editor has changed the data. To deploy these items, run jss deploy items --includeContent --includeDictionary to deploy everything.

jss deploy files

Builds your production application (jss build) and copies all of its files to the configured Sitecore instance in scjssconfig.json. No items are deployed, and no manifest is generated.

The command supports the following parameters:

Parameter

Description

Value type

source

The source path of the config patches to deploy.Default: ./sitecore/config

String

destination

Destination path to deploy to. Defaults to the instancePath set in scjssconfig.json, combined with the sitecoreConfigPath setting from package.json.

String

config

Path to scjssconfig file.Default: ./scjssconfig.json

String

exclude

Filters specific file(s) from the deployment package by file name(s).Default: ['report.html']

Array

skipBuild

If true, no build task is invoked, and any existing build artifacts at the source path are deployed.Default: false

Boolean

buildTaskName

Name of the npm script to run to perform a build before deploying. To skip running any script, use --skipBuild or pass the argument with a blank value.Default: build

String

clean

Whether to delete all existing items in the destination before copying new artifacts.Default: false

Boolean

Note

The command jss deploy files has many options that enable modifying how the files deploy, such as skipping a build and using existing /dist items with --skipBuild. Run jss deploy files --help to see all the options with descriptions. When run with default options, jss deploy files also runs jss build.

jss deploy component

When using Sitecore-first/connected development methodology, this command scaffolds a new component (rendering item, datasource template, and allowed placeholder settings) in Sitecore.

The developer must still create the component in the JSS app and add the component to a route with one of the Sitecore editors.

The command jss deploy component can also modify existing components by adding fields, changing field types, or setting display names. Only explicitly specified arguments apply. For example, using the --fields parameter adds/modifies only the fields specified and does not delete any other fields.

Important

You must never use jss deploy component when working code-first or without a Sitecore instance because it does not update the manifest, only Sitecore items.

jss deploy component has many options that enable modifying how the component is scaffolded, such as specifying datasource template fields with --fields or setting a display name with --displayName.

Run jss deploy component --help to see all the options with descriptions.

The command supports the following parameters:

Parameter

Description

Value type

allowedPlaceholders

The placeholder name(s) to allow the rendering to be placed in. For example --allowedPlaceholders Foo or --allowedPlaceholders Foo Bar.

Array

exposesPlaceholders

The names of any placeholders exposed on this component (to place other components in). This causes placeholder settings items to be generated for them.

Array

Other JSS scripts and commands

All scripts you need to run during development are defined either as commands available in the JSS CLI (use --help for options) or as package scripts in the file package.json located in the root directory of your JSS application.

jss build

A script defined in the package.json file of your JSS app that creates a production build for deploying to Sitecore. The result of the build process is a JS bundle and other static assets under the /dist folder.

jss manifest

Runs the app's manifest generation process, which generates the app manifest file under /sitecore/manifest in app root.

The command supports the following parameters:

Parameter

Description

Value type

appName

The name of the app. Defaults to the package.json config value.

String

manifestSourceFiles

The files or file patterns to parse to generate the manifest. Default: ['./sitecore/definitions/**/*.sitecore.js', './sitecore/definitions/**/*.sitecore.ts']

Array

require

A JS module to require before processing the manifest. This might initialize a custom compiler (Babel, TypeScript), perform init tasks, and so on. Default: ./sitecore/definitions/config.js

String

manifestOutputPath

The path of the file to which manifest output is written. Default: ./sitecore/manifest

String

includeContent

Includes content and media items in the manifest output. Default: false Alias: c

Boolean

includeDictionary

Includes dictionary items in the manifest output. Default: false Alias: d

Boolean

language

Defines the language the manifest represents. Defaults to the language config in the package.json. Alias: l

String

rootPlaceholders

Sets the root placeholder name(s) for the app. If set, overrides root placeholders set in the package.json. Alias: p

Array

wipe

Causes the JSS import to run as a wipe + recreate of any existing app items. Pass --unattendedWipe in addition to bypass interactive confirmation for CI scenarios. Default: false Alias: w

Boolean

pipelinePatchFiles

List of files or file patterns from which to load pipeline config patch files. Default: ['./sitecore/pipelines/**/*.patch.js', './sitecore/pipelines/**/*.patch.ts']

Array

debug

If true, emits additional diagnostic information. Default: false

Boolean

allowConflictingPlaceholderNames

Enables using placeholder names that conflict with Sitecore or SXA. Default: false Alias: a

Boolean

Note

The command jss manifest has options that enable modifying how the manifest generates, such as --includeContent to add content and routes data to the manifest. Run jss manifest --help to see all the options with descriptions.

Manifest does not include content, media, or dictionary items by default for safety, in case a content editor has changed the data. To include these items, run jss manifest --includeContent --includeDictionary to include everything.

jss package

Creates an update package that includes both the app manifest and the production build artifacts.

The command supports the following parameters:

Parameter

Description

Value type

packageOutputPath

The location the JSS manifest package is written to. Default: ./sitecore/package

String

skipManifest

If true, skips manifest generation. This can be used to consume existing output from jss manifest (via the manifestOutputPath parameter) without rebuilding it. Default: false

Boolean

Note

The command jss package has many options that enable modifying how the package deploys, such as excluding build artifacts with --noFiles. Run jss package --help to see all the options with descriptions.

When run with default options, jss package also runs jss build and jss manifest. You can also pass options for all of these commands to package.

jss deploy template

When using Sitecore-first/connected development methodology, this command scaffolds out a new template in Sitecore. jss deploy template can also be used to modify existing templates (e.g., adding fields, changing field types, or set display names). Only explicitly specified arguments apply (e.g., using --fields will add/modify only the fields specified and will not delete any other fields.

The command supports the following parameters:

Parameter

Description

Value type

name

The name of the item to create or update.

String

displayName

Sets the item's display name (visual name, as opposed to the actual name of the template).

String

fields

Creates template fields. Fields can be either a plain name or name:fieldType. For example, --fields Foo Bar or --fields Foo "Bar Bas:Rich Text"

Array

icon

Sets the icon of the item in Sitecore. For example, People/16x16/alarmclock.png

String

appName

The name of the app. Default: appName from package.json config.

String

config

Path to scjssconfig file. Default: ./scjssconfig.json

String

deployUrl

URL to the Sitecore JSS import service that accepts the package deployment. Default: deployUrl from scjssconfig.json

String

skipDeploy

If true, no deployment is made, and the manifest registration code for code-first is written to the console instead. Default: false

Boolean

acceptCertificate

Whitelists a specific SSL certificate thumbprint, regardless of normal SSL validation. Useful for self-signed certificates.

String

Note

The command jss deploy template must never be used if code-first/disconnected development is in use as it does not update the disconnected manifest, only Sitecore items.

jss deploy template has options that enable modifying how the template is scaffolded, such as specifying template fields with --fields or setting a display name with --displayName. Run jss deploy template --help to see all the options with descriptions.

jss clean

Cleans the contents of a directory.

The command supports the following parameters:

Parameter

Description

Value type

path

The path to clean. Defaults to buildArtifactsPath config in package.json.

String

jss deploy

Deploys the JSS app artifacts to a Sitecore instance. Use jss deploy --help for subcommands.

jss deploy package

This command is deprecated. Use jss deploy app instead.

jss environment

Prints the value of an environment variable.

The command accepts the following parameters:

Parameter

Description

Value type

name

The name of the environment variable to print.

String