Skip to main content

Experience App CLI

Introduction

The Experience App CLI is a command line tool to help you build Experience apps.

Requirements

  • Showpad domain with administrator rights.
  • NodeJS >=15.0.0
  • Rosetta (for Mac computers with Apple silicon)

Platform & Browser Compatibility

@next versions: Versions tagged with --next might contain small issues. Only use in production if you can alter the .Showpad package quickly.

Development

LocalhostProxy App
Chrome
Firefox
Edge
Safari

The Proxy App doesn't run on Safari: Use another browser to run the Proxy App while developing Localhost on Safari.

MacWindowsLinux
CLI Version2.2.02.2.02.1.7

Production

Showpad Experience Apps run inside Iframes: Use relative paths in production.

The Experience App SDK targets ES2022: Transpile your code if you need legacy support.

Documentation

You can find documentation on the Showpad Developer Portal.

Installation

# npm
npm i @showpad/experience-app-cli -D

# yarn
yarn add @showpad/experience-app-cli -D

Usage

Commands

You can use the --help option on every command to get more information about the command.

init

Init the experience app by checking/creating required files for experience app development.

It is not permitted to have duplicate Experience App source files (manifest.json, config.json, index.html) in your project. When using a build tool, please delete the builded directory after bundling or use lib or dist as build directories as the Experience App CLI will ignore these directories.

# npm
npx experience-app-cli init

# yarn
yarn experience-app-cli init
Options
  • -u, --unattended
  • --host
  • --client_id
  • --client_secret
  • --username
  • --password
  • --src

sync

Sync the manifest.json version from the package.json file. Helpful when working with Semantic Versioning.

# npm
npx experience-app-cli sync

# yarn
yarn experience-app-cli sync
Semantic Versioning

Use Semantic Versioning to update the version of your project by running npm version --type or yarn version --type with the increment type. Git tags are created by default.

bundle

Create a .showpad bundle by checking required files and bundling a folder. Defaults to the current working directory.

It is not permitted to have duplicate Experience App source files (manifest.json, config.json, index.html) in your project. When using a build tool, please delete the builded directory after bundling or use lib or dist as build directories as the Experience App CLI will ignore these directories.

# npm
npx experience-app-cli bundle

# yarn
yarn experience-app-cli bundle
Options
  • -u, --unattended
  • --dist
  • --output

create

Create a new Experience App Channel from a .showpad bundle.

# npm
npx experience-app-cli create

# yarn
yarn experience-app-cli create
Options
  • -u, --unattended
  • --channel_name

proxy

This command will install the Proxy Experience App on the configured domain.

Develop on localhost with the Proxy Experience App.

# npm
npx experience-app-cli proxy

# yarn
yarn experience-app-cli proxy
Proxy Experience App

The Proxy Experience App acts as a bridge between a running Showpad domain and localhost. It allows you to execute all functions from the Experience App SDK on localhost with actual responses.

You can download the latest version here: Proxy Experience App.

Showpad.parseConfig(): The Experience App CLI caches the first result to serve the next requests immediately. Restart the Experience App CLI proxy command after you publish a new version to serve the latest contents.

Options

All commands have optional flags available. The Experience App CLI will not prompt if the corresponding option is present and valid. If an invalid option is passed, the Experience App CLI will prompt as a fall back.

All options are mandatory in -u, --unattended mode. The Experience App CLI will throw an error if the option is neither present nor valid.

-u, --unattended

This option allows you to run this CLI command unattended. Unattended mode requires all options to be present and will throw an error if options are missing or does not pass validation.

Unattended mode is different in some aspects than passing all options in the default (attended) mode. Unattended mode has some default values for prompts or values that can not be passed through options. In addition, running in unattended mode will do the following below:

  • create the manifest.json file automatically from package.json
  • automatically select the first Proxy Experience App if multiple are present
  • throw errors on invalid options instead of falling back to prompting the value

--host host

Showpad Domain (e.g. https://domain.showpad.biz)

--client_id client_id

Showpad Oauth Client ID

You can find more information about authentication, authorization, and OAuth clients in this article.

--client_id client_secret

Showpad Oauth Client Secret

You can find more information about authentication, authorization, and OAuth clients in this article.

--username username

Showpad Username

The email address of the user used to log in to Showpad.

--password password

Showpad Password

The password of the user used to log in to Showpad. If SSO is being used to log in to Showpad instance, it is required to set a username and password authentication to make use of the Experience App CLI. This does not alter your existing SSO setup. You can always use the forgot password manual to quickly set a password.

--src src

Source directory of your project. Common directories are src, public, ...

Beware if you pass the --src option while not having an index.html file. The Experience App CLI will place it in the same directory as config.json and manifest.json which can be unintended. However, most framework scaffolding wil already generate an index.html.

--dist dist

Build directory of your project. Common directories are src, dist, ...

Most build tools will compile your code to a specific directory like dist. You can just select your src directory if you are not using a build tool.

--output output

Output directory of your bundle relative to the current working directory

The output path is relative to the current working directory. You can use dots to go to parent directories. An example: you have the folder structure monolith/subproject where your current working directory is monolith/subproject but you want to build to the monolith folder. You can execute yarn experience-app-cli bundle --output ../ to achieve this.

--channel_name channel_name

Name of an Experience App Channel

Use the create command with a specific name by passing the Channel Name.

--channel_id channel_id

ID of an Experience App Channel

Use the update or proxy commands with a specific channel by passing the Channel Id.

--overwrite_values

Flag to overwrite the config.json values while updating an Experience App Chanel

This option allows you to overwrite the values of the config.json file while updating an Experience App Chanel.