--- title: "Walkthrough: Connecting a JSS application to Sitecore" slug: "walkthrough--connecting-a-jss-application-to-sitecore" abstract: "Connect a React, Angular, or Vue.js JSS app to Sitecore and perform an initial deployment of code-first artifacts" --- # Walkthrough: Connecting a JSS application to Sitecore Every JSS application must at some point in its lifecycle transition from disconnected mode, to being deployed to a Sitecore environment. We can use the JSS CLI to deploy our app to Sitecore, which imports all of our disconnected content and components into Sitecore Items that can then be edited. > [!important] > Applications built with JSS for Next.js have a [different deployment process](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/walkthrough--connecting-a-code-first-jss-next-js-application-to-sitecore.html "Walkthrough: Connecting a code-first JSS Next.js application to Sitecore") because of the [characteristics of Next.js](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/sitecore-jss-for-next-js-differences-from-jss-for-react,-angular,-and-vue-js.html "Sitecore JSS for Next.js differences from JSS for React, Angular, and Vue.js"). When the app is deployed to Sitecore you can run it in [connected mode](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/start-a-jss-app-in-connected-mode.html "Start a JSS app in connected mode") where you develop the app using live data from Sitecore, as well as in [integrated mode](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/start-a-jss-app-in-integrated-mode.html "Start a JSS app in integrated mode") where the app is server-side rendered by Sitecore and Content Authors can edit the content and layout of the application. Connecting and deploying JSS applications to Sitecore requires that you have access to a Sitecore instance with [Sitecore Headless Services](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/sitecore-headless-services.html "Sitecore Headless Services"), you [installed the JSS CLI](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/install-the-jss-cli-globally.html "Install the JSS CLI globally") and [created a Sitecore API Key](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/create-a-sitecore-services-client-api-key.html "Create a Sitecore services client API key"). This walkthrough describes how to: - Configure the site name and hostname for the JSS app. - Set up the connection information. - Deploy the app configuration to Sitecore. - Deploy the application to Sitecore. - Verify the app deployment. ## Configure the site name and hostname for the JSS app Applications created with the JSS app initializer include a [Sitecore site definition](https://doc.sitecore.com/xp/en/developers/104/platform-administration-and-architecture/en/configure-multiple-managed-websites.html) in a [Sitecore configuration patch](https://doc.sitecore.com/xp/en/developers/104/platform-administration-and-architecture/en/use-a-patch-file-to-customize-the-sitecore-configuration.html) created with the application. In the root folder of your JSS application, open the file containing the configuration patch `/sitecore/config/.config` and confirm that the `hostName` attribute matches a host header that the server must respond to. If you are deploying a JSS app as the default site for the Sitecore installation, you can remove the `hostName` attribute so that the JSS app responds to any host. > [!note] > Provide a top-level domain (TLD) for the development hostname. The browser Microsoft Edge does not resolve hostnames without a TLD. For example, the browser can resolve `http://jss.sitecore` but not `http://sitecore`. The following is a site configuration example for setting the site name and the hostname: ```xml ``` When using a local instance, you must map the desired hostname to your local host. To map a hostname to your localhost on Windows: 1. Open a code editor as an administrator. 2. In the editor, open the file `C:\Windows\System32\drivers\etc\hosts`. 3. Add the mapping. For example: ```text 127.0.0.1 myapp.siteco.re ``` 4. Save and close the file. After adding the hostname entry, add it as a binding on your IIS instance as well: ![IIS Bindings](https://doc.sitecore.com/api/markdown-image/xp/en/developers/hd/23/sitecore-headless-development/images/iis-bindings.png) If you plan to deploy multiple JSS applications, you must configure the different hosts and hostname bindings in IIS for Sitecore to resolve the correct site. ## Set up the connection information To configure the connection: - In a terminal, run the JSS command `jss setup` and follow the prompts. Follow the prompts to supply the following pieces of information: - Website folder: This is the root physical path to the Sitecore instance, used to deploy config files and JS build artifacts. File share paths are fine for remote instances. For example: `c:\inetpub\wwwroot\MySitecore\Website`. If you do not have access to the website folder directly, answer *no* when asked if your instance is remote. - Sitecore hostname: This is the *hostname of your JSS app* previously configured in the Sitecore configuration patch `/sitecore/config/.config`. For example, `http://jssreactweb` - Sitecore import service URL: This is the *import service URL of your JSS app*. It consists of the *hostname of your JSS app* plus `/sitecore/api/jss/import`: `http://jssreactweb/sitecore/api/jss/import`. You can leave this blank to use the default value or provide your custom URL. - API key ID: provide the Item ID of the [Sitecore API key](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/create-a-sitecore-services-client-api-key.html "Create a Sitecore services client API key") for this JSS app. - Deployment secret: This is a shared secret that enables authentication to deploy your app items to Sitecore. We recommend you use the random key generated by the setup process. If you choose your own key, the secret must be a randomly generated string 32 or more characters long. > [!important] > Do not commit the secret to source control; use a unique secret for each environment and limit access to production secrets. For CI environments, `jss setup` accepts parameters (`--help`) that can be used to pass the secret and other parameters from variables. By default, the secret is stored in `/scjssconfig.json` and `/sitecore/config/AppName.deploysecret.config` - both of which are automatically ignored if you use Git for source control. The `jss setup` process generates the `/scjssconfig.json` file containing the connection strings for your JSS application. > [!tip] > To build an environment-agnostic JSS app bundle for production environments that always use the current hostname for API requests, in the `scjssconfig.json` set the `layoutServiceHost` setting to blank. This can be useful when you wish to commit one set of build artifacts and deploy them to CM + CD, or even a [headless proxy](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/walkthrough--rendering-a-jss-app-server-side-using-the-headless-jss-proxy.html "Walkthrough: Rendering a JSS app server-side using the headless JSS proxy"). This technique is incompatible with [connected GraphQL](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/connected-graphql-in-jss-apps.html "Connected GraphQL in JSS apps") and [server-side rendering](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/server-side-rendering-jss-applications.html "Server-side rendering JSS applications"), which requires an absolute URL to be set. ## Deploy the app configuration to Sitecore The JSS app is registered with Sitecore using configuration patches that are deployed to the Sitecore server. When setting up the Sitecore server, you already edited one of these patches when [setting the hostName attribute](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/walkthrough--connecting-a-jss-application-to-sitecore.html#UUID-d8b98717-2a2a-3e5e-bd77-240379c89d9b_section-idm456469661113283263080387184 "Configure the site name and hostname for the JSS app"). Before the configuration patch can take effect on the Sitecore server, you need to deploy it. You can deploy configurations automatically (recommended) or manually. Automatic deployment deploys the config patches directly from the JSS app using the JSS CLI. To automatically deploy the configuration patches: - In your JSS app working directory, in a terminal, run the command: ```text jss deploy config ``` The script copies the config patch files from the `sitecore/config` folder to the Sitecore `App_Config/Include/zzz` folder. The automatic configuration deployment configured the JSS app within Sitecorecreates a site for it and enables live mode without the need to publish. Developers should review the patch file carefully to ensure all the settings are correct for the environment. In production, for example, the application should not run in live mode. > [!note] > Ensure that the user account you use to run the command has permission to write to the Sitecore website folder configured in `/scjssconfig.json`. On Windows, this can involve UAC elevation. If the JSS app config is to be deployed by a dedicated Sitecore developer (or DevOps), or when you're working with a remote instance, the JSS app config may need to be deployed manually. Acquire the `sitecore/config/*.config` patches from the JSS application, and deploy them to your `App_Config/Include` folder in a location of your liking, such as a `zzz` folder. Ensure you review the config patches for content before deploying them. ## Deploy the application to Sitecore With the previous steps completed, you are ready to deploy your JSS app to Sitecore. The deployment procedure varies based on the SDK you used to build the app and the Sitecore instance. Choose the procedure for your scenario: - [Deploy JSS apps to a local Sitecore instance *without* local self-signed SSL certificates](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/walkthrough--connecting-a-jss-application-to-sitecore.html#UUID-d8b98717-2a2a-3e5e-bd77-240379c89d9b_section-idm4586200338800032630805916733 "Deploy JSS apps to a local Sitecore instance without local self-signed SSL certificates"). - [Deploy JSS apps to a local Sitecore instance *with* local self-signed SSL certificates](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/walkthrough--connecting-a-jss-application-to-sitecore.html#UUID-d8b98717-2a2a-3e5e-bd77-240379c89d9b_section-idm4613160135646432686114728843 "Deploy JSS apps to a local Sitecore instance with local self-signed SSL certificates"). - [Deploy a JSS app to a remote Sitecore instance](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/walkthrough--connecting-a-jss-application-to-sitecore.html#UUID-d8b98717-2a2a-3e5e-bd77-240379c89d9b_section-idm4570944034403232630805625823 "Deploy a JSS app to a remote Sitecore instance"). ### Deploy JSS apps to a local Sitecore instance *without* local self-signed SSL certificates You can deploy a React, Angular, or Vue.js JSS app to a local Sitecore instance that does not use self-signed SSL certificates with the following command: ```text jss deploy app --includeContent --includeDictionary ``` Content, media, and dictionary items are not installed by the deployment process by default, which is why you must use `--includeContent --includeDictionary`. It is appropriate to include them as long as disconnected content is being updated but not if [content editors are already writing content for the app](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/code-first-development-workflow.html "Code-first development workflow"), because they might lose content data. If your application has content in additional languages, you must perform a separate deployment of the items in that language using the command `jss deploy items`. For example, `deploy items --language da-DK --includeContent --includeDictionary `. > [!tip] > There are many available options for `jss deploy app`, which are all set to sensible defaults if unspecified. You can see all of the options for it using `jss deploy app --help`. This command performs the following steps for you, which can also be performed independently if required: - It triggers [app manifest generation](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/generating-a-jss-app-manifest-file.html "Generating a JSS app manifest file") by invoking the [JSS command `jss manifest`](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/sitecore-javascript-rendering-sdk-cli-tools-api-reference.html "Sitecore JavaScript Rendering SDK CLI Tools API reference") in the `sitecore-import.json` file. - The process continues with the generation of a manifest package by invoking the `jss package` command and packages the app manifest file and referenced media files. - It builds the app for production, by invoking the build script, usually `build`. - It deploys the manifest package to Sitecore using the [import service endpoint](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/import-service.html "Import Service") - `jss deploy items --includeContent --includeDictionary` - It copies the build artifacts to the Sitecore instance at the configured location using the command `jss deploy files`. ### Deploy JSS apps to a local Sitecore instance *with* local self-signed SSL certificates If your local Sitecore instance uses local self-signed SSL certificates: 1. Open a terminal in your JSS app directory. 2. Run the following command with a fake certificate thumbprint: ```text jss deploy app --includeContent --includeDictionary --acceptCertificate test ``` > [!note] > The parameter `--acceptCertificate` whitelists an SSL certificate by thumbprint (certificate pinning). Because Node does not respect Windows trusted root certificates, this enables deploying items to local Sitecore instances that use self-signed certificates without disabling SSL validation entirely. 3. From the resulting error message copy certificate thumbprint: ![View of SSL certificate thumbprint](https://doc.sitecore.com/api/markdown-image/xp/en/developers/hd/23/sitecore-headless-development/images/certificate-error.png) 4. Run the deployment command again, replacing the fake certificate thumbprint with the one you copied. For example: ```text jss deploy app --includeContent --includeDictionary --acceptCertificate CA:CD:3B:DB:19:D1:`97:92`:F9:`80:91`:FF:32:CC:F8:35:DC:F5:0B:01 ``` ### Deploy a JSS app to a remote Sitecore instance To deploy a React, Angular, or Vue.js JSS app to a remote Sitecore installation: 1. Open a command prompt/terminal within your JSS app. 2. Run the command: ```text jss deploy items --includeContent --includeDictionary ``` 3. Create production build artifacts for the app by running the build script defined in your `package.json` file (usually `build`): ```text jss build ``` 4. Deploy the build artifacts to the relative path on the Sitecore instance defined in `sitecoreDistPath` in your `package.json` file. For example, `$sitecore\dist\myappname`. ## Verify the app deployment A correctly configured and deployed JSS application must support Sitecore workflows. You must verify that: - The content of the JSS application appears in the Sitecore content tree. Log into your Sitecore instance using your JSS app's host `http://myapp.siteco.re/sitecore/`. You should see your JSS app item under */sitecore/Content/*. ![A JSS app in the Sitecore content tree](https://doc.sitecore.com/api/markdown-image/xp/en/developers/hd/23/sitecore-headless-development/images/jss-tree.png) - The application must run in [integrated mode](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/start-a-jss-app-in-integrated-mode.html "Start a JSS app in integrated mode") by visiting the hostname configured for the site, for example, `http://myapp.siteco.re/`. If integrated mode works correctly, viewing the source of the page shows a fully rendered app with complete HTML. ![View of the deployed JSS app in integrated mode](https://doc.sitecore.com/api/markdown-image/xp/en/developers/hd/23/sitecore-headless-development/images/jss-deployed.png) - The app is editable in a Sitecore editor. Try launching the `/Home` page in Experience Editor. For example, `http://myapp.siteco.re/?sc_mode=edit` or launch it from the dashboard. ![JSS app in the Sitecore Experience Editor](https://doc.sitecore.com/api/markdown-image/xp/en/developers/hd/23/sitecore-headless-development/images/basic-app-editable-ee.png)