App Spin-up

How to fork and configure a Desktop App repo built on Pankosmia

Table of Contents

Fork desktop-app-template

Desktop-app-template is a repo designed to be forked to spin up and maintain new Desktop App repos built on Pankosmia.

  1. Start at https://github.com/pankosmia/desktop-app-template/fork

  2. Choose a repository name of 30 characters or less if you want to keep Windows developers from needing to clone to a shorter local repo name. The windows cargo build c compiler requires repos names of 30 characters or less.

  3. Create Fork

Setup 

    |-- repos
    |-- pankosmia
        |-- [your-desktop-app-repo-name] (30 characters or less on windows!)

package.json

Replace all instances of “desktop-app-template” in package.json with “[your-desktop-app-repo-name]”

At the root of your clone of this repo, run:

Migration from npm to pnpm in process

Use the repo root lock file to determine which applies: pnpm-lock.yaml → pnpm; package-lock.json → npm. For additional detail see our Migration Plan.

pnpm-lock.yaml package-lock.json
> pnpm install > npm install

Edit app_config.env

Entering the App Name, version number, Apps Short Name for working directory, assets, and clients.

Required Assets:

  • ASSET1=resource-core
  • ASSET1_PATH=/runtime_resources
  • ASSET1_NAME=app_resources
  • ASSET2=resource-core
  • ASSET2_PATH=/templates
  • ASSET2_NAME=templates
  • ASSET3=webfonts-core
  • ASSET3_PATH=/
  • ASSET3_NAME=webfonts

Required Clients:

The only required client is one that matches the HOMEPAGE entered in app_config.env. The homepage is typically core-client-dashboard which has an id of dashboard, but the id of any client in the product may be configured as the homepage.

Some Optional Clients:

Start with 1. Keep numbering sequential. Do not skip numbers.

  • CLIENT1=core-client-dashboard
  • CLIENT2=core-client-content
  • CLIENT3=core-client-settings
  • CLIENT4=core-contenthandler-generic

Branding

Change /globalBuildResources/theme.json directly to customize your app. For helful tips, see the Theme section of UX/UI guidelines.

For implementing your logo, see the Branding README for scripts to customize /globalBuildResources/.ico, /globalBuildResources/.png, and /globalBuildResources/icon.icns, along with info on how each is used.

Setup Scripts

cd [os]/scripts

Run[1] the clone script to clone all repos listed in app_config.env (assets and clients)

Run[1] the app_setup script to generate the config files to match app_config.env. Re-run[1] the app_setup script anytime app_config.env is modified.

Run[1] the build_clients script to build all clients. Be patient. This will take a while.

  • This script defaults to all main branches, pulls the latest, and builds every client each time it is run.
  • Specify branches other than main as arguments: ./build_clients.[ext] [my-branch|dev|qa] [dev|qa][1]. Where “my-branch” does not exist, then fallback will be “main” unless the next argument is specified. If “dev” is indicated then a “dev” → “qa” → “main” fallback is implied. If “qa” is indicated then a “qa” → “main” fallback is implied. To build repos manually, identify whether to use pnpm or npm, then run pnpm run build or npm run build accordingly on just those repos as needed.

Run[1] the build_server script to build the Pankosmia server and assemble the build environment. When /local_server.env has different versions from the panksomia_web in /local_server/Cargo.toml, then use ./build_server.[ext] dev to build a local dev server, and ./build_server.[ext] qa to build a local qa server. Be patient. This will take a while.

(Optional) Run[1] the build_viewer script to create an Electronite viewer for use with the local development environment.

Running your Setup

Run[1] the run script to start the server without a browser launch.

  • Only one instance of the same server can be running at a time.

Run the viewer script to use the Electronite viewer with the local dev build environment, or launch a browser at the location indicated.

Footnotes

[1] … Windows developers, run .bat scripts from a Powershell or Command prompt:
…repos\pankosmia[your-desktop-app-repo-name]\windows\scripts> .[scriptname].bat
The .\ is optional from a command prompt.
Use a powershell terminal for the .ps1 build scripts.
MacOS developers, run .bsh scripts from a MacOS terminal:
…repos/pankosmia/[your-desktop-app-repo-name]/macos/scripts> ./[scriptname].bsh
Linux developers, run .zsh scripts from a linux terminal:
…repos/pankosmia/[your-desktop-app-repo-name]/linux/scripts> ./[scriptname].zsh