Import a JSS app into your headless site

Version: 10.3

When you deploy a classic JSS application to an SXA environment, there are some differences to the general app deployment process. Because with headless 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. If you need to define GraphQL endpoints, and therefore using the Config Deployment step, you must comment out app and site nodes in the configuration.

Important

Before you import the classic JSS app, you must follow the steps described on Sitecore JavaScript Rendering SDKs (JSS) , including configuring your app's site and host name.

To import a JSS classic app into your headless site:

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.sitecore/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. 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 ([headless site]/Settings).
Important
- Because you are working on a SXA deployment on JSS, you can skip the config deployment step.
- The application name defined in the package.json file must match the application name specified in the App Name field on the Settings item.

Change the Layout Service configuration used by your JSS application to sxa-jss.

For Next.js: In the \src\lib\layout-service-factory.ts file, update the configurationName property to 'sxa-jss'.
For React: In the \src\lib\layout-service-factory.js file, update the configurationName property to 'sxa-jss'.
For Angular: In the \src\app\lib\layout-service-factory.ts file, update the configurationName property to 'sxa-jss'.
For Vue: In the \src\lib\layout-service-factory.js file, update the configurationName property to 'sxa-jss .

The following code example shows what adding 'sxa-jss' looks like for React.

RequestResponse

export class LayoutServiceFactory {
  create(): LayoutService {
    return process.env.FETCH_WITH === 'GraphQL'
      ? new GraphQLLayoutService({
          endpoint: config.graphQLEndpoint,
          apiKey: config.sitecoreApiKey,
          siteName: config.jssAppName,
        })
      : new RestLayoutService({
          apiHost: config.sitecoreApiHost,
          apiKey: config.sitecoreApiKey,
          siteName: config.jssAppName,
          configurationName: 'default',
        });
  }
}

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.

Do you have some feedback for us?

If you have suggestions for improving this article,