Import a JSS app into your headless site

Abstract

Learn how to deploy a JSS application.

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 can skip the Config Deployment step of the general process described at jss.sitecore.com.

Important

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.

To import a JSS app into your headless site:

  1. Create an API Key and note its Item ID for use in setting up the app.

  2. 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}

  3. To configure the Sitecore connection, run jss setup at a command line within your JSS app, and follow the prompts. The prompts ask you for the following pieces of information:

    • Path to the Sitecore folder: enter the path to the headless 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).

      Headless Deployment secret

    Important

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

  4. 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>
    
  5. Change the Layout Service configuration used by your JSS application to sxa-jss.

    • For React: In the \src\RouteHandler.js file, add configurationName: 'sxa-jss' to the fetchOptions object.

    • For Angular: In the \src\app\jss-context.service.ts file, add configurationName: 'sxa-jss' to the fetchOptions object.

    • For Vue: In the \src\RouteHandler.vue file, add configurationName: 'sxa-jss' to the fetchOptions object.

    The following code example shows what adding 'sxa-jss' looks like for React. For Angular and Vue, you must also add the snippet to the layoutServiceConfig item.

    const fetchOptions = {  layoutServiceConfig: { host: getHostname(), configurationName: 'sxa-jss' },  querystringParams: { sc_lang: language, sc_apikey: config.sitecoreApiKey },  fetcher: dataFetcher,};
  6. 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, open the Content item, and click the Security, Assign. In the Assign Security Rights dialog, select the sitecore\JssImport user, and make sure they have write permissions to both Items and Descendants.