The JSS app initializer

Current version: 21.7

The Sitecore JavaScript Rendering SDK (JSS) provides the create-sitecore-jss package that contains an app initialization script and JSS application templates for popular JavaScript frameworks and application add-ons.

To use the JSS initializer, in a terminal, you can run one of the following commands:

RequestResponse
npx create-sitecore-jss

To provide any arguments, use the npx command.

Required arguments

When creating a JSS application with the initializer, you can follow the prompts to provide information about the setup you want for your application.

Alternatively, you can override any prompt by passing in that value as a flag using the following arguments:

Argument

Type

Description

templates

string[]

A comma-separated list of template names to use in scaffolding the JSS application. It can include the name of a base app template, for example, nextjs, and any number of add-on templates, such as nextjs-styleguide.

For example, npx create-sitecore-jss --templates nextjs,nextjs-styleguide.

You can also supply a list of templates using the positional argument: npx create-sitecore-jss nextjs,nextjs-styleguide.

appName

string

The name of your JSS application.

Default: sitecore-jss-app.

destination

string

Path/directory for the application. If you provide a non-empty directory path, the initializer shows potential changes to existing files. It also provides options for handling the change (approve the changes to the current file, skip the file, approve changes to all files, or abort). Using the initializer in a non-empty destination helps you apply add-on templates to an existing JSS project.

Default: <current-directory-path>/<base-template-name>.

fetchWith

string

Method for fetching data. Choose REST or GraphQL.

Default: GraphQL.

prerender

string

Only available if using the nextjs template. Prerendering method for the application. Choose between static site generation (SSG) and server-side rendering (SSR).

Default: SSG.

language

string

Only valid if using the nextjs-styleguide add-on. Language and locale code. For example, es-MX.

Default: da-DK.

hostName

string

The hostname of your Sitecore instance.

Default: <app-name>.dev.local.

For example, if you want to skip the templates, appName, and fetchWith prompts, you can run the following command:

RequestResponse
npx create-sitecore-jss --templates nextjs --appName my-nextjs-app --fetchWith GraphQL

You can shorten the command by using the positional argument as follows:

RequestResponse
npx create-sitecore-jss nextjs --appName my-nextjs-app --fetchWith GraphQL

Optional arguments

In addition to the required arguments, the JSS initializer accepts the following optional parameters:

Argument

Type

Description

appPrefix

boolean

If present, the application:

  • Uses the appName argument to prefix templates, ensuring each template has a unique name when deployed to Sitecore. Multiple templates with the same name cause errors when using strongly typed GraphQL queries because of naming conflicts.

  • Uses the appName argument to prefix placeholders. When using prefixed placeholders, if you have multiple JSS apps deployed to Sitecore, the Sitecore interface for inserting components in a placeholder shows only the components for the current site.

force

boolean

If provided, suppresses any questions related to file system operations, and the initializer runs default actions.

silent

boolean

If provided, suppresses log messages.

Usage: npx create-sitecore-jss --silent

prePushHook

boolean

If provided, runs a linting script that checks TypeScript type and code formatting validity.

yes

boolean

If provided, it suppresses any questions related to the CLI argument values, and the initializer uses the default values.

--xmcloud

boolean

If provided, the application uses the nextjs-xmcloud template to scaffold the JSS application.

Base templates

When creating a project, you can provide one base template name using the positional argument or by using the --templates flag:

RequestResponse
npx create-sitecore-jss <base-template-name>

Or:

RequestResponse
npx create-sitecore-jss --templates <base-template-name>

The available base template names are:

  • nextjs.

  • react.

  • angular.

  • vue.

  • react-native.

  • node-headless-ssr-experience-edge.

  • node-headless-ssr-proxy.

Add-on templates

When creating a project, in addition to the base template name, you can also provide multiple add-on template names using the positional argument or the --templates flag:

RequestResponse
npx create-sitecore-jss <base-template-name>,<first-add-on-template-name>,<second-add-on-template-name>

Or:

RequestResponse
npx create-sitecore-jss --templates <base-template-name>,<first-add-on-template-name>,<second-add-on-template-name>

The available add-on template names are:

  • nextjs-styleguide - includes example components and the setup for working disconnected.

  • nextjs-styleguide-tracking - includes an example tracking component for applications running against a Sitecore Experience Platform (XP) instance. It requires the nextjs-styleguide add-on. It is not compatible with the nextjs-personalize add-on or with a Sitecore Experience Manager (XM) Cloud content management instance.

  • nextjs-xmcloud - supports the Sitecore Context data, simplifying the application's connection to XM Cloud and configuring the integration of multiple composable Sitecore products. It is only available in JSS 21.6 and later, and we recommend it for integrating your JSS Next.js app with XM Cloud and composable Sitecore products.

  • nextjs-sxa - includes example components and setup for Headless SXA projects.

  • nextjs-multisite - includes an example setup for hosting multiple sites from a single Next.js application.

Do you have some feedback for us?

If you have suggestions for improving this article,