Skip to main content

Build custom JSS app templates for your team

Abstract

Create and distribute custom JSS templates to speed up project setup

JSS supports customizing application samples that can be used with jss create to make new JSS apps, allowing you to shape the JSS sample applications based on your needs and reuse your custom sample for future projects.

Create a custom template

JSS custom templates start as a copy of one of the sample apps, which you can modify and distribute.

At the root of each JSS sample application is the file jss-create.js.

When a developer runs the command jss create to create an app based on a sample app, JSS acquires the template files, copies them to a destination directory, runs npm install, and then invokes the jss-create.js file, if it exists.

The script renames app elements, such as the package name and Sitecore config patch names, to match the name of the newly created app. The script is an extension point for template authors to add custom functionality. It also enables template authors to modify the steps shown after the jss create finishes creating the application with custom instructions.

For example:

module.exports = function createJssProject(argv, nextSteps) {
  console.log(`Executing create script: ${__filename}...`);

  // if your template needs to change or add to the next steps shown
  // to the user after the create completes, you can manipulate the `nextSteps` 
  // array before returning it:
  nextSteps.push('* Reticulate the splines');
  return nextSteps;

  // ...or replace it entirely
  return [ 
    '* These are the only next steps shown',
    '* The defaults are ignored'
  ];
};

Note

On completion, the jss-create.js file is deleted in the new app.

Test your custom template

When you have created your customized app template, we recommend that you test creating new apps based on that template before you distribute it. The command jss create supports creating applications using locally stored templates.

To test a local template:

  1. Create a folder to store your template library.

  2. Move or copy your app template into the library folder. For example, if your library is ~/jss-templates and the new template is called react-custom, the template belongs at ~/jss-templates/react-custom.

  3. In a terminal, run the following command to create a JSS app based on your custom template:

    jss create <appname> react-custom --source ~/jss-templates
    

Distribute a custom template

To distribute a custom template for sharing with other developers, use a Github repository.

The command jss create supports --repository and --branch options for distributing public templates. Private repositories and non-GitHub repositories are not supported.

  jss create <appname> react-custom --repository githubusername/reponame --branch branchname

Warning

Using a custom template allows that template to run code on your machine. Only use app templates from sources you trust.