Skip to main content

Create Experience App

In this tutorial, you will create a simple Experience App. Along the way you will use the Experience App Tooling to master the setup, development, and deployment of your experience apps.

Requirements

  • Showpad domain with administrator rights
  • NodeJS
  • If your Experience App will be displayed in the Windows Desktop App, the app needs to run on (non-Chromium) Edge version 18 or above.

OAuth setup

You will need a configured OAuth client to develop Experience Apps. The basics of creating OAuth clients are explained in this article. The following information should suffice for a developer client:

  • Name: Developer Client
  • Redirect URL: https://your-domain.showpad.biz/
  • Description: OAuth client to facilitate Experience App development.
  • Website: https://your-domain.showpad.biz/
  • This client needs to: Check all the boxes

App setup

Scaffold new app with vite

To start off, we're going to scaffold our app using vite. vite is a build tool that aims to provide a faster and leaner development experience for modern web projects. It consists of two major parts:

  • A dev server that provides rich feature enhancements over native ES modules, for example extremely fast Hot Module Replacement (HMR).
  • A build command that bundles your code with Rollup, pre-configured to output highly optimized static assets for production.

vite is opinionated and comes with sensible defaults out of the box, but is also highly extensible via its Plugin API and JavaScript API with full typing support.

npm init vite@latest create-experience-app

A prompt will ask which framework and variant to use. Select vanilla as framework and vanilla-ts as variant. Change the working directory to this newly created vite project.

cd create-experience-app

We're now inside our project. Install the required packages from the package.json file.

npm install

Configure the way vite builds

We need to alter two important things in vite to support Experience App Development. Experience Apps require a config.json and manifest.json in the root folder of the dist. By default, vite will hash every file. You can create a public directory where you can put files that just needs to be copied 1 on 1.

mkdir public

Experience Apps are running in Iframes. This can cause havoc when importing files or routing in your SPA. The simple sollution is to use relative paths. This is something you can configure in the vite.config.ts file.

touch vite.config.ts

Add the following to vite.config.ts to specify a relative base path when you're building our app.

import { defineConfig, UserConfigExport } from 'vite';

// https://vitejs.dev/config/
export default (command: string): UserConfigExport => {
return defineConfig(command === 'dev' ? {} : { base: './' });
};

Configure package.json

Thanks to the vite scaffolding, we already have two of our required files:

  • index.html
  • package.json

However, the scaffolded package.json file does not contain all the fields Showpad requires. Both description and author fields are needed to be manually modified. Make sure to fill in a value for these two fields as it is required by the Experience App CLI. The package.json file should now look similar to this:

{
"name": "create-experience-app",
"version": "0.0.0",
"description": "Build your first Experience app",
"author": "Showpad app creator",
"scripts": {
"dev": "vite",
"build": "tsc && vite build",
"serve": "vite preview"
},
"devDependencies": {
"typescript": "^x.x.x",
"vite": "^x.x.x"
}
}

Install the Experience App CLI and SDK

Install both Experience App SDK and CLI. These will help to generate the remaining required files.

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

Run the Experience App CLI init command

Experience app CLI can now be initialized (init) our experience app.

npx experience-app-cli init --src public

When you run this command, a prompt is displayed asking to pick:

  • host: the domain linked to the Showpad admin you are using
  • OAuth Client ID: the client id found in the Showpad admin UI
  • OAuth Client Secret: found at the same place as the Client ID
  • username: the mail address of your admin account
  • password: the password of your admin account
note

Pay special attention if you copy paste values:

  • Remove the / when copy pasting your showpad domain as host.
  • When pasting the client secret or password, it might look as nothing changed but the value is actually hidden like you would type credentials.

The remaining fields (identifier, name, version, description and author) should be confirmed without any edits. The defaults suggested for these fields are taken from the package.json file.

If you open the public folder now you'll see two files have been added:

  • config.json
  • manifest.json

The config.json file handles the experience app editor. The manifest.json file contains all publicly available information of our app like its name.

Another file, the .env file, has also been created by running the command. This file contains information that should be protected like the client secret and admin password in addition to some other fields. This file is ignored by .gitignore so if you ever check this app into version control your secrets are safe.

App development

Run development server

npm run dev

The server is now running on the URL returned by the command. Open your browser and go to this local URL, and you'll see the HTML content of the index.html file.

Run the Experience App CLI proxy command

Locally, we don't have access to the Showpad functionality. So we need to add an intermediate server providing us this functionality. The Experience app CLI provides a command to spin up this proxy server. Before using this command, we have to:

  1. Download the proxy app.
  2. Upload the proxy app to Showpad platform.
tip

Check this Help Center article for a well-detailed explanation on how to upload custom Experience Apps to Showpad.

Don't worry if you're seeing ❌ onClose in the preview tab. This is because the proxy app is already trying to connect to the Experience App CLI. Just click the Publish Experience button and wait for your app to be published.

Now run the proxy app:

npx experience-app-cli proxy

Use the Experience App SDK inside your app

Replace the contents of main.ts with the following so instead of saying "Hello Vite", you get "Hello" and your own username.

import { Showpad } from '@showpad/experience-app-sdk';
import './style.css';

const app = document.querySelector<HTMLDivElement>('#app')!;

const main = async (): Promise<void> => {
// Always wait for ShowpadLib to be loaded.
await Showpad.onShowpadLibLoaded();

try {
// Get current Showpad user information and display it in the title.
const userInfo = await Showpad.getUserInfo();
app.innerHTML = `<h1>Hello ${userInfo.fullName}!</h1>`;
} catch (error) {
// Show a native error toast.
Showpad.handleErrorWithToast(error);
}
};

main();

App deployment

Bundle Experience App

Bundle the app by following the steps outlined in this guide.

Deploy the app

Deploy the app by following the steps outlined in this Help Center article.