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: 

    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:

  • CLIENT1=core-client-dashboard
  • CLIENT2=core-client-content
  • CLIENT[any number]=core-client-settings

Branding

Change /globalBuildResources/theme.json directly to customize your app. For helful tips, see https://pankosmia.dev/uxui-guidelines/#theme

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 is intended for setting all clients up for first use, or for rebuilding all clients to their latest main branch. It changes to the main[2] branch, pulls the latest, and builds (or rebuilds) every client every time it is run.
  • Build client manually when you want to use a branch or when you only need to rebuild one client or when you do not want all clients built from their latest main branch!

Run[1] the build_server script to build the Pankosmia server and assemble the build environment. (be patient. This will also take a while.)

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

Running your Setup

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

  • Only one instance of the server can be running at a time.[3]

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 terminal:
             …repos\pankosmia[your-desktop-app-repo-name]\windows\scripts> .\[scriptname].bat
             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

[2] … The build script will fail on any clients set to a different branch with uncommitted changes or with conflicts vs, the latest main pull. Scroll back up in the terminal to find any build errors and address them.

[3] … If running into an error saying that another instance is running, you can either find the other instance and stop it, or simply reboot. Another instance could be one started from a .zip, .tgz, installed version, run from a different repo, or a manually started panksomia-web.