Sitecore JavaScript Rendering SDK CLI Tools API reference
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 |
---|---|---|
|
The name of the app to create. |
|
|
The template to create the app from; corresponds to folders in the official JSS repository |
|
The command supports the following optional parameters:
Parameter |
Description |
Options |
Default |
Template |
---|---|---|---|---|
|
Show version number |
- |
|
all |
|
Show help for the command |
- |
|
all |
|
Sets the hostname of the Sitecore site if this app is deployed to Sitecore. |
- |
|
all |
|
Configures the repository to use for creating the JSS app |
A repository: |
|
all |
|
Configures the branch of the repository to use for creating the JSS app |
A branch name |
|
all |
|
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 |
|
Specifies an HTTP proxy when downloading templates. |
A local directory path |
- |
all |
|
Specifies how the application fetches Sitecore layout and dictionary data. |
|
|
nextjs, react, angular, vue |
|
Specifies the Next.js pre-rendering form for the primary |
|
|
nextjs |
|
Specifies the app is created empty |
- |
|
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 |
---|---|---|
|
Path to the Sitecore Website folder (for example, c:\dev\sitecore\Website) |
|
|
The Sitecore host used to deploy the app (for example, http://myinstance.com/sitecore/api/jss/import) |
|
|
The Sitecore host used to download Layout Service data (for example, http://myinstance.com) |
|
|
Sitecore API Key (GUID of item under /sitecore/system/Settings/Services/API Keys/ in the |
|
|
Deployment secret (32+ random chars). |
|
|
Disallows interactive prompts (all other arguments must be passed in this mode). |
|
|
The file path for placing the config. Default: |
|
|
Skip validation of command arguments (for example, for CI). |
|
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 |
---|---|---|
|
The source path of the config patches to deploy.Default: |
|
|
Destination path to deploy to. Defaults to the |
|
|
Path to |
|
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.
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 |
---|---|---|
|
URL to the Sitecore JSS import service that accepts the package deployment.Default: |
|
|
Shared secret to authenticate the deployment with Sitecore.Default: |
|
|
Path to |
|
|
Enables diagnosing authentication issues with your deployment. Exposes secrets to output, use only for temporary diagnostics.Default: |
|
|
If |
|
|
Specify an HTTP proxy to use when deploying items. |
|
|
Whitelists a specific SSL certificate thumbprint, regardless of normal SSL validation. Useful for self-signed certificates. |
|
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 |
---|---|---|
|
The source path of the config patches to deploy.Default: |
|
|
Destination path to deploy to. Defaults to the |
|
|
Path to |
|
|
Filters specific file(s) from the deployment package by file name(s).Default: |
|
|
If |
|
|
Name of the |
|
|
Whether to delete all existing items in the destination before copying new artifacts.Default: |
|
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.
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 |
---|---|---|
|
The placeholder name(s) to allow the rendering to be placed in. For example |
|
|
The names of any placeholders exposed on this component (to place other components in). This causes placeholder settings items to be generated for them. |
|
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 |
---|---|---|
|
The name of the app. Defaults to the package.json config value. |
|
|
The files or file patterns to parse to generate the manifest. Default: |
|
|
A JS module to require before processing the manifest. This might initialize a custom compiler (Babel, TypeScript), perform init tasks, and so on. Default: |
|
|
The path of the file to which manifest output is written. Default: |
|
|
Includes content and media items in the manifest output. Default: |
|
|
Includes dictionary items in the manifest output. Default: |
|
|
Defines the language the manifest represents. Defaults to the language config in the package.json. Alias: |
|
|
Sets the root placeholder name(s) for the app. If set, overrides root placeholders set in the package.json. Alias: |
|
|
Causes the JSS import to run as a wipe + recreate of any existing app items. Pass |
|
|
List of files or file patterns from which to load pipeline config patch files. Default: |
|
|
If true, emits additional diagnostic information. Default: |
|
|
Enables using placeholder names that conflict with Sitecore or SXA. Default: |
|
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 |
---|---|---|
|
The location the JSS manifest package is written to. Default: |
|
|
If |
|
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 |
---|---|---|
|
The name of the item to create or update. |
|
|
Sets the item's display name (visual name, as opposed to the actual |
|
|
Creates template fields. Fields can be either a plain name or |
|
|
Sets the icon of the item in Sitecore. For example, |
|
|
The name of the app. Default: |
|
|
Path to |
|
|
URL to the Sitecore JSS import service that accepts the package deployment. Default: |
|
|
If |
|
|
Whitelists a specific SSL certificate thumbprint, regardless of normal SSL validation. Useful for self-signed certificates. |
|
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 |
---|---|---|
|
The path to clean. Defaults to |
|
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 |
---|---|---|
|
The name of the environment variable to print. |
|