Managing JSS apps with SXA

Import a JSS app into your JSS site

Version:

When you deploy a JSS application to an SXA environment, there are some differences to the general app deployment process. Because with JSS site creation, the default configuration settings are added in items (Site/Settings/), this means that you must skip the Config Deployment step of the general process described at jss.sitecore.com.

To import a JSS app into your JSS site:

Before you import the JSS app, you must follow the steps described on jss.sitecore.com including configuring your app's site and host name.
Create an API Key and note its Item ID for use in setting up the app.
To test whether the Layout Service is working, make a test request to Layout Service on your Sitecore host: http://myapp.siteco.re/sitecore/api/layout/render/jss?item=/&sc_apikey={YOUR_API_KEY_ID}
To configure the Sitecore connection, run jss setup at a command line within your JSS app, and follow the prompts. You will be asked for several pieces of information:
- Path to the Sitecore folder: enter the path to the JSS site you created earlier. For example: C:\inetpub\wwwroot\sxa92.
- Host name: enter the host name of your SXA site. For example: http://sxa92.
- Import service URL: you do not need to change the default setting. For example, leave it at: http://sxa92/sitecore/api/jss/import.
- API key: enter the GUID of the API key.
- Deployment secret: enter the secret here or press enter to create one. If you choose to create a new deployment secret, you must enter it in the Content Editor (JSS site/Settings).
Important

Because you are working on a SXA deployment on JSS, you can skip the config deployment step.

If you want to use GraphQL for your web application, you must deploy GraphQl endpoints configuration in a config file placed in \Website\App_Config\Include\zzz. You can use the example patch below. Make sure to update the URL and Template path.

<!--
  JSS Sitecore Configuration Patch File

  This configuration file registers the JSS site with Sitecore, and configures the Layout Service
  to work with it. Config patches need to be deployed to the Sitecore server.

  Normally `jss deploy config` can do this for local development. To manually deploy, or to deploy via CI,
  this file can be placed in the `App_Config/Include` folder, or a subfolder of it, within the Sitecore site.
-->
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/" xmlns:set="http://www.sitecore.net/xmlconfig/set/" xmlns:role="http://www.sitecore.net/xmlconfig/role/">
  <sitecore>
    <api>
      <!--
        Define the app's Sitecore GraphQL API endpoint
        Note: this can be removed if you are not using GraphQL.
        Note: the endpoint must be defined both for integrated and connected type GraphQL queries.
      -->
      <GraphQL>
        <endpoints>
          <carsGraphQLEndpoint url="/api/cars" type="Sitecore.Services.GraphQL.Hosting.DatabaseAwareGraphQLEndpoint, Sitecore.Services.GraphQL.NetFxHost" resolve="true">
            <url>$(url)</url>

            <enabled>true</enabled>
            <enableSubscriptions>true</enableSubscriptions>

            <!-- lock down the endpoint when deployed to content delivery -->
            <graphiql role:require="ContentDelivery">false</graphiql>
            <enableSchemaExport role:require="ContentDelivery">false</enableSchemaExport>
            <enableStats role:require="ContentDelivery">false</enableStats>
            <enableCacheStats role:require="ContentDelivery">false</enableCacheStats>
            <disableIntrospection role:require="ContentDelivery">true</disableIntrospection>

            <schema hint="list:AddSchemaProvider">
              <content type="Sitecore.Services.GraphQL.Content.ContentSchemaProvider, Sitecore.Services.GraphQL.Content">
                <!-- scope typed template generation to just this app's templates -->
                <templates type="Sitecore.Services.GraphQL.Content.TemplateGeneration.Filters.StandardTemplatePredicate, Sitecore.Services.GraphQL.Content">
                  <database>context</database>
                  <paths hint="list:AddIncludedPath">
                    <templates>/sitecore/templates/Project/Demo</templates>
                  </paths>
                  <fieldFilter type="Sitecore.Services.GraphQL.Content.TemplateGeneration.Filters.StandardFieldFilter, Sitecore.Services.GraphQL.Content">
                    <exclusions hint="raw:AddFilter">
                      <!--
                          Remove system fields from the API (e.g. __Layout) to keep the schema lean
                      -->
                      <exclude name="__*" />
                    </exclusions>
                  </fieldFilter>
                </templates>

                <queries hint="raw:AddQuery">
                  <!-- enable querying on items via this API -->
                  <query name="item" type="Sitecore.Services.GraphQL.Content.Queries.ItemQuery, Sitecore.Services.GraphQL.Content" />
                </queries>

                <fieldTypeMapping ref="/sitecore/api/GraphQL/defaults/content/fieldTypeMappings/standardTypeMapping" />
              </content>
            </schema>

            <!-- Enables the 'jss' graph nodes that are preformatted to use with JSS rendering components, and the datasource resolving queries for JSS -->
            <extenders hint="list:AddExtender">
              <layoutExtender type="Sitecore.JavaScriptServices.GraphQL.JssExtender, Sitecore.JavaScriptServices.GraphQL" resolve="true" />
            </extenders>

            <!-- Determines the security of the service. 'publicService' is open to anonymous access, but requires an SSC API key. -->
            <security ref="/sitecore/api/GraphQL/defaults/security/publicService" />

            <!-- Determines how performance is logged for the service. Defaults are defined in Sitecore.Services.GraphQL.config -->
            <performance ref="/sitecore/api/GraphQL/defaults/performance/standard" />
          </carsGraphQLEndpoint>
        </endpoints>
      </GraphQL>
    </api>
  </sitecore>
</configuration>

To import your app, open a command prompt/terminal within your JSS app and run:

jss deploy app --includeContent --includeDictionary

Note

For the import to work, your JSS import user must have the correct permissions. To make sure the user has the right permissions, go to the Content Editor, select the <site> item, and, in the Security section, click Assign security. In the Assign Security Rights dialog, select the sitecore\JssImport user, and make sure they have write permissions to both Items and Descendants.

If you have suggestions for improving this article, let us know!