Get started tutorial

Use this tutorial to start working on your store locally.

You’ll learn how to fetch your store data from the Frontend web application and set up your local project folder.

With the shogun CLI tool you can set up your local folder from scratch or add the necessary setup to your existing store folder which already contains sections and components.

Also, you can set up 3rd party APIs such as Shopify Cart API, Algolia Search, etc., and develop your store in conjunction with actual 3rd party APIs.

System Requirements

In order to run the CLI you will need to have the following installed

npm version 8.x
node version 16.x
OS: MacOS, Linux, Windows with WSL

Authenticate in Shogun Frontend application

Before you start using shogun CLI you need to authenticate in Frontend application.

Run the following command to initialize the authentication process: npx shogun@latest login
This command will open a browser window and load Frontend device confirmation form.
Compare the device code in your terminal with the one in the browser. If they match, press Confirm.
If you are not logged in, you will be shown the Frontend login form. Log in to Frontend as usual.
At the end of the login flow you should see a confirmation message stating that your login attempt was successful. You can safely close the browser window and return to your terminal.

At this point, the CLI tool obtained the necessary token and it is ready to operate on your behalf.

Get your store id

Each store in the Frontend application has its own unique identifier. You need to find out Frontend id of your store. You’ll use this id to set up your local development environment.

Run the following command to list your stores: npx shogun@latest list
The output of this command should look like this:
```
$ npx shogun@latest list 
Fetching your stores list... 

1. Example store, id=xxx 
2. Another store, id=xxx
```
Copy your store id to clipboard. You’ll need it for further steps.

Set up local store folder

Now that you have everything ready, you can bring your store on your local machine.

💡 Prerequisite: Make sure your store is published at least once

Run the following command to fetch your store from Frontend and set it up in a local folder:
npx shogun@latest clone <store-directory-name> --store-id=<store-id>

This command performs the following main operations for you:
- Creates the store folder with package.json and necessary configuration files.
- Fetches the latest store data from Frontend.
- Runs npm install to install store and framework dependencies.
- Sets up Storybook as a supplementary tool for local development of components and sections in isolation.
- Initializes Git repository and sets .gitignore file to exclude everything besides sections, components, and global styles.
Upon completion of the above steps, the folder structure should look like this:
```
.shogun
.storybook
node_modules
src
    components
    sections
    global.css
.env
.gitignore
.npmrc
package.json
package-lock.json
```
In the scripts section of the package.json you’ll find the following scripts that will help you work on your store:
- shogun:create-component - creates a new component with boilerplate code
- shogun:create-section - creates a new section with boilerplate code
- shogun:pull - fetches latest store data from Frontend
- shogun:dev - starts development server and opens your store in a browser
- shogun:lint - runs linter for the project (Not implemented yet)
- shogun:sync-schema - generates unified generated-schema.json file
- shogun:storybook - starts Storybook
- shogun:build-storybook - builds Storybook
- shogun:version - prints the current version of the CLI tool (the one installed locally in the node_modules folder)
- shogun:update - updates shogun CLI and pulls your store
Once you have your local store folder ready, push your store code to your GitHub repository.
If you don't have a GitHub repo yet, create one and follow run the following commands in your store folder to push your local code to GitHub
Bash
```
$ git remote add origin <git-url-of-your-new-repository> $ git branch -M master $ git push -u origin master
```
If you already have a GitHub repo, you need to set it as the origin in your local folder.
Local development environment works best when you have GitHub integration enabled for your store.
Follow this document to enable GitHub integration for your repository: https://docs.getshogun.com/shogun-frontend-guides/docs/github-integration

Keeping the `shogun` CLI tool up to date

# Display the current version
npm run shogun:version 

# Update the CLI to the latest version
npm run shogun:update

Note that when a newer version of the shogun CLI tool is available, running the npm run shogun:pull command will prompt you to update to the latest version. It's important to stay updated with the latest version to stay consistent with the build processes of Frontend.

If you need to pull the latest changes, but you don't wish to update the package at the given time then you can skip the version update by running the following command:

npm run shogun:pull -- --force

This will skip the update prompt and will allow you to run the pull command as normal. Though it's highly encouraged to update to the latest version shortly thereafter.

Set up local store folder over an existing project

⚠️This functionality is provided as "best-effort".

It might not work in some cases. Consider cloning a store into a new folder as a more reliable approach.

If you have an existing repository, you might want to set up a local development environment in this folder. This is useful when you are already using a repository for development with Starter Kit and therefore you already have a src folder with your components and section code.

In order to set up a local development environment over an existing project, follow these steps:

As a safety measure, make a full copy of your current project folder before proceeding with the next steps.
cp -R path/to/your/store store-copy/
Change your current directory to the one with your existing project:
cd path/to/your/store
Run clone command in this folder: npx shogun@latest clone . --store-id=xxx
This command preserves your existing setup for the project. It leaves your local sections and components code intact.
This command gently augments your current local project so that you could run your whole store locally.

Set up Accounts, Cart, and Search APIs

Shogun provides a set of powerful React components and hooks to make working with Accounts, Cart, and Search API easier. These components and hooks use environment variables to connect to remote API.

You don’t need to do anything special to set up these environment variables. It’s all done under the hood when you run npx shogun@latest clone to scaffold your folder initially. All environment variables can be found in the local .env file.

You can make changes to the .env file, for example, to switch between stores in Shopify/Bigcommerce. You might want to have a separate store on the platform for development purposes.

💡 Note, you need to restart the local dev server each time you make a change in the .env file

Code your store locally

Local development environment allows you to run your store locally.

You can make changes to your components/sections and instantly see them in the browser.

Change existing section/component code

Working on the code locally:

Navigate to the store folder created in the previous step cd store-directory-name
Launch Nextjs dev server: npm run shogun:dev.
This command builds your store and opens it in a browser window.
Now you can open the project in your favorite editor and start working on the code
Make some changes to a section or a component. The dev server should automatically re-render changes in the browser.
Create a new component.
This can be done manually or by running the command: npm run shogun:create-component MyComponent. This command creates boilerplate code and a Storybook story for your new component.
Import your new component into an existing section. Changes should be automatically reflected in the store.

⚠️ You should abstain from changes outside of the src folder. Changes in other folders won’t be picked up by GitHub sync and such changes will be overwritten upon next synchronization with Frontend

Work with section variables

src/sections/MySection/schema.ts, src/sections/MySection/schema.js or src/sections/MySection/schema.json file can be used to control the variables that section has. With the file it is possible to add, remove or rename variables for a specific section.

The format of the files is as follows:

// in `schema.ts` or `schema.js` file
export const schema = {
  "props": [
    {
      "name": "headerText",
      "type": "string"
    },
    {
      "name": "fontSize",
      "type": "number"
    }
  ]
}

// in `schema.json` file
{
  "props": [
    {
      "name": "headerText",
      "type": "string"
    },
    {
      "name": "fontSize",
      "type": "number"
    }
  ]
}

In this example, we define two variables: headerText of type string and fontSize of type number. Once this file is added to the repository, it will be picked up by GitHub integration (it has to be set up) and these variables will be created in the Frontend application.

List of possible variable types:

string
number
boolean
richText
html
media
reference
datetime

In order to create multiple value variables you need to set isMultiple flag to true (by default it’s false):

{
  "props": [
    {
      "name": "links",
      "type": "string",
      "isMultiple": true
    }
  ]
}

To create a reference type variable, you set "type": "reference" and select the fields of the referenced type:

{
  "props": [
    {
      "name": "topProduct",
      "type": "reference",
      "selection": {
        "Products": {
          "description": true,
          "variants": {
            "name": true
          }
        }
      }
    }
  ]
}

In this example, we create topProduct variable referencing Products type with Product.description and Product.variants.name fields selected.

Add a variable

To add a new variable you just add an entry to the schema file under props key.

Remove a variable

To remove a variable, you remove the desired entry from the schema file.

🚧Contact Shogun support to enable variable deletion for you

By default variable deletion is disabled, please contact Shogun support to enable it.

Change a variable

Once a variable is created, you cannot change its type or isMultiple attribute. If you want to change these attributes for a variable, remove that variable in first commit and re-add it in the next commit with the needed attributes changed.

Rename a variable

You can rename a variable by changing its name property.

Generate store schema

Once you are done editing schemas for each sections run npm run shogun:sync-schema command in order to sync all section schemas with src/generated-schema.json file which will be taken by GitHub integration and to update schemas in Frontend.

❗️ The changes to the src/generated-schema.json file are synced by GitHub integration, make sure it is set up for your site.

🚧 It is better to stick with a single approach for managing section variables: either schema files or Frontend Web IDE approach.

Create a new section

Sections are different from components. You can map CMS data, like products into sections. Also, sections are building blocks of pages.

While components can be created and imported into other components or sections manually in your local IDE, sections’ creation requires a bit of a different approach.

In order to add a new section, you need to perform the following steps:

Create a new section.
This can be done manually or by running the command: npm run shogun:create-section MySection. This command creates boilerplate code and a Storybook story for your new section.
Now you can start working on your section locally.
For now, this section hasn't been added to any page yet, so you need to use Storybook to render it in the browser in an isolated environment.
You can use the following command to launch Storybook with your sections and components: npm run shogun:storybook
As soon as you are happy with the initial section code and you want to put your section into a page or you want to map CMS data into it, proceed with the following steps.

Add changes to git and push them to your remote branch to trigger GitHub sync in Frontend:

Bash

$ git add path/to/section/index.jsx
$ git commit -m "Initial version of My new section"
$ git push origin

Wait until your new section appears in Frontend.
Add your new section to a page/frame/template in order to be able to see it in the store. Map the necessary CMS data into your section.
Generate a new store version.
This step can be skipped if the change has been made for a page in the draft state.
Run npm run shogun:pull in your local folder to fetch the latest Frontend data.
Alternatively, you can run npm run shogun:pull -- --path=/example-page to fetch only one page that you’ve just added your section to.
Upon completion of the above step, your store should render the newly added section.

Change Frontend data

When it comes to changes beyond sections, components code, and global styles, the source of truth is Frontend.

Such changes may include changes to pages, templates, frames, site settings, CMS data, and its mapping to sections’ props.

For all such changes you should follow the same approach:

Implement the necessary changes in Frontend and save them
Generate a new store version.
This step can be skipped if the change has been made for a page in the draft state.
Run npm run shogun:pull in your local folder to fetch the latest Frontend data.
You can skip this step if you change data for a page or section that has been already fetched to your local folder. Page data, like props, is automatically re-fetched when your page is rendered in the browser.
Upon completion of the above step, your changes should be reflected in your local store.

Go live!

When you are done with the changes and local testing, deploy them to your live store.

In order to deploy your code, you should follow these steps:

Add your changes to Git and push them to the remote branch with GitHub integration:
Bash
```
$ git add -A $ git commit -m "My new feature" $ git push origin
```
Wait until GitHub sync picks up the changes and they appear in Frontend
Now you can generate a build in Frontend, preview it and ultimately publish in Frontend Site Manager.

Commands Cheat Sheet

Bash

# Login to Frontend using the CLI
npx shogun@latest login;

# List your stores and copy the ID to clone your store
npx shogun@latest list;

# Setup local store
npx shogun@latest clone <store-directory-name> --store-id=<store-id>

Bash

# To start a local development server
npm run shogun:dev

# To pull changes from Frontend (page changes, CMS changes, section layout changes)
npm run shogun:pull

# To create a new section
npm run shogun:create-section

# To create a new component
npm run shogun:create-component

# To start Storybook and develop your components in isolation
npm run shogun:storybook

# To pull a single page from Frontend
npm run shogun:pull -- --path=/products/socks

# To overwrite local or unsynced changes with Frontend
npm run shogun:pull -- --include-all

To see the complete list of shogun commands run npx shogun@latest --help

Project status

Stage: General Availability
Current version: 1.4.2 / 12-16-2022

Caveats

Stores can be pulled for a limited time (about 7 days) since the last version was created in Frontend. In case this limit is exceeded the “Site publication has already been purged” error will be thrown during cloning/pulling.
In order to pull the store again, a new version must be created in Frontend Site Manager.
Every time a change has been made for a page a new store version should be generated before running the pull command. The only exclusion is draft pages which can be pulled immediately after saving.
package.json, .gitignore, .npmrc and .env are merged by default during pull run. package.json is replaced only when the --include-all option was set for the pull command. Note, that you need to separate command options with a double dash like so: npm run shogun:pull -- --include-all.
Store redirects are not supported in LDE.

Troubleshooting

Unexpected `x is not defined` errors

If you encounter x is not defined errors on a page you are working on unexpectedly it is possible your local version of the page is outdated.

Try pulling down the page again with npm run shogun:pull

“Site publication has already been purged” error

Stores can be pulled for a limited time (about 7 days) since the last version was created in Frontend. In case this limit is exceeded the “Site publication has already been purged” error will be thrown during cloning/pulling.

In order to pull the store again, a new version must be created in Frontend Site Manager.

“Oops, something went wrong” message in the device confirmation window

As part of the login flow, you need to confirm your device in a browser window. If you accidentally click the confirm button twice, you will see an “Oops, something went wrong” message. It’s a known issue with auth0 forms.

Close the browser window. Cancel your current run of npx shogun@latest login command by pressing Ctrl+C / CMD +. Then run the command npx shogun@latest login again.

uncaughtException: TypeError: this.target.close is not a function

Key Concepts

GitHub Integration

Dependency Management

Frontend Components

Your Homepage

Get started tutorial

System Requirements

Authenticate in Shogun Frontend application

Get your store id

Set up local store folder

Keeping the shogun CLI tool up to date

Set up local store folder over an existing project

Set up Accounts, Cart, and Search APIs

Code your store locally

Change existing section/component code

Work with section variables

Add a variable

Remove a variable

Change a variable

Rename a variable

Generate store schema

Create a new section

Change Frontend data

Go live!

Commands Cheat Sheet

Project status

Caveats

Troubleshooting

Unexpected x is not defined errors

“Site publication has already been purged” error

“Oops, something went wrong” message in the device confirmation window

uncaughtException: TypeError: this.target.close is not a function

Keeping the `shogun` CLI tool up to date

Unexpected `x is not defined` errors