Understanding jss create for Sitecore JSS

One thing I love about Sitecore is the ability to extend and customize almost anything. And that also goes with the newly released Sitecore JSS.

In the previous posts, I gave a very brief introduction and getting started with Sitecore JSS, and then I tried to recreate a very minimal JSS app without using any out of the box client tools.

In this post I will show how to use the Sitecore JSS tools to reuse your own template.

Basic Template Generation

Sitecore JSS comes with tons of features and capabilities, the one I am exploring today is the jss create command, the official documentation already has a great starting point to let you know what’s there and how to extend it. Also, just typing in the command line jss create –help will give a great starting point.

So as you can see from the available options, there is already a couple few ways to make an app from a custom template.

1. By specifying your own repository using the –repository parameter, this repository should be public and accessible from your command line (there is no way to point to a non github repo or a private repo, but there is a workaround).
   • Also, works with –branch to change the active branch
2. By specifying a folder on the local hard disk using the –source parameter with value having the folder containing the template (which as written in the tool Good for private templates.)

One customization option here is to give the template generator a starting hostname using the –hostName parameter.

Advanced Template Generation

What actually happens when calling the jss create app template a set of tasks are executed.

First, the cli tool tries to copy the template from the source (built-in, custom repo or source folder. Next it tries to run npm install, to get the folder ready for you. After installing the required packages, the tool starts setting the package name to <the app name you chose> some default renaming happens here.

Then it’s up to you and use the magic of jss-create.js, which is a file that you add in the source (repo or folder) that gets executed and self deleted from destination folder. You can use it for any customization, renaming or moving bits that you need to add. If you add some default files with <tokens> to be replaced upon creating new projects this is the right place to add your replacing logic.

Sample demo

In the last post, I built a bare bones jss application, I will reuse it and make it as a template to show off the power of jss create.

So for the sake of the demo, I copied the old bare-bones-jss-app into a new folder and named it bare-bones-jss-template and then ran this command.

jss create app-one bare-bones-jss-template -s /Users/amr/Projects/Blog

As expected the cli did it’s job, a new folder name app-one was created with the contents of the template, npm install was called, and I ended up with the lovely ASCI Sitecore logo as shown here

One thing to notice, the top yellow line Template bare-bones-jss-template did not have a jss-create.js in its root to invoke. No template configuration will be performed. And that means the application will just be a copy with no special names replacement done.

Now I will borrow the default jss-create.js in the react default template and show what happens.

const { applyNameToProject } = require('@sitecore-jss/sitecore-jss-cli/dist/create');
/**
 * @param {object} argv Arguments passed to `jss create` script
 * @param {string[]} nextSteps Array of default 'next steps' to show at the console
 * @returns {string[]} The next steps to display to the console user (enables customization from this script)
 */
module.exports = function createJssProject(argv, nextSteps) {
  console.log(`Executing create script: ${__filename}...`);

  applyNameToProject(__dirname, argv.name, argv.hostName);

  return nextSteps;
};

After adding this file, we just need to add “@sitecore-jss/sitecore-jss-cli”: “^11.0.2” to devDependencies in package.json, since it’s required in the file. To understand what applyNameToProject does you can peek into the source code of that method here. You will figure out that it’s trying to find a config.appName entry from the package.json file to use it for renames. So let’s add that as well.

"config": {
    "appName": "bare-bones-jss-template"
  },

And there you go, run again the jss create command line. And all files and settings are renamed for you to start deploying.

jss create app-two bare-bones-jss-template -s /Users/amr/Projects/Blog

Now we are back on track, after poking around the default tooling to understand what is happening under the hood. Next is doing actual customization and adding your own stuff. renaming other files or creating new ones all from the beginning.

Even the list of steps that are displayed after the ASCI Sitecore logo can be customized. From within the jss-create.js file you can change/add to the nextSteps array.

  nextSteps.push('* Watch a movie');

I hope this post has been useful and beneficial to you, as it was a lot of fun and learning for me.