Skip to content

Web app template with TypeScript, PostCSS, Workbox & PWA Asset Generator. Has Github Actions to publish via Electron for desktop or Capacitor for Android.

License

GPL-3.0, MPL-2.0 licenses found

Licenses found

GPL-3.0
LICENSE
MPL-2.0
LICENSE-MPL-2.0
Notifications You must be signed in to change notification settings

thinknathan/web-app-starter-project

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Web App Starter Project

Web App Starter Project

CI Desktop CI Android

Web App Starter Project is a starting point for web app development. Apps can be packaged for the web, Windows, macOS, Linux, or Android via Github Actions.

For development, WASP installs opinionated defaults in the form of TypeScript and PostCSS, but can be made to work with any framework. Its focus is building for the web first. Non-browser APIs are only used to smooth over platform differences.

Development features

JavaScript

CSS

Export platforms

Getting started

Requirements

Install

  • yarn Installs main project dependencies

  • Update these important fields in package.json:

    • appId A unique domain for your app, in reverse order. Eg. www.example.com becomes com.example.www
    • name A short, simple of your app without spaces
    • productName The name of your app in a less strict format that can support spaces
    • description Describe what your app does
    • author The creator of your app - presumably you
    • version The version of your app. Semver is encouraged
  • (Optional) Update your app colours:

    • meta name="theme-color" in www/index.html
    • theme_color in www/app.webmanifest
    • iconBackgroundColor values in the icon:mobile scripts in package.json
    • background values in the icon:web scripts in package.json
    • darkBackground and lightBackground in src-electron/main.ts
  • (Optional) Change the default window resolution in Electron:

    • Edit width and height in src-electron/main.ts
  • (Optional) Generate your Capacitor project with npx --no cap add android

Commands

  • yarn build Builds the project

  • yarn build:desktop Builds the project for distribution as an Electron app

  • yarn build:mobile Builds TS and mobile app icons (Doesn't build the app files; you'll have to manually run cap build android)

  • yarn build:web Builds the project for distribution on the web, builds icons, generates service worker

  • yarn dev Watches for changes and serves to http://localhost:8000/

  • yarn dev:desktop Launches project in Electron

  • yarn dev:web Identical to yarn dev except it sets TARGET_ENV to web

  • yarn icon:desktop Generates icons in Electron folders

  • yarn icon:mobile Generates icons in Android folders

  • yarn icon:web Generates icons and adds links to them in index.html and app.webmanifest

  • yarn lint Checks for errors in Electron and web source TS

  • yarn lint:electron Checks for errors in Electron source TS

  • yarn lint:www Checks for errors in web source TS

  • yarn prettier Applies formatting to source TS and CSS

  • yarn prettier:scripts Applies formatting to source TS

  • yarn prettier:styles Applies formatting to source CSS

  • yarn sw Generates service worker

  • yarn sw:dev Generates service worker in debug mode

File structure

  • src-electron (Used by Electron for generating a desktop app)
    • buildResources (Icons for Electron generated by yarn icon:desktop)
    • main.ts (Main entry point for Electron)
  • src-www (Web source code)
    • scripts
      • app.ts (Main TypeScript source file for web)
    • styles
      • app.css (Main CSS source file for web)
    • images
      • icon.svg (Used to generate icons for Android and PWA. Keep in mind it may be masked in a circle, rounded square, etc.)
      • icon-precomposed.svg (Used to generate icons for Electron and web favicon)
      • splash.svg (Used to generate splash screen for Android and PWA)
  • www (All production files)
    • assets
      • fonts (Font files can be added here manually)
      • images
        • icons (Generated by yarn icon:web)
      • scripts (Bundled JS)
      • styles (Bundled CSS)
    • app.webmanifest (Manifest for a Progressive Web App)
    • index.html (Main HTML file for the project)
  • build-electron.mjs (esbuild script for bundling Electron assets)
  • build-www.mjs (esbuild script for bundling web assets)

Github Actions

These Github Actions will automatically build your project for distribution on multiple platforms.

  • Build Desktop build-desktop.yml
    • Produces Windows, MacOS and Linux builds
  • Build Android build-android.yml
    • Produces Android builds in APK and AAB format

Code signing

Code signing is enabled by default in the Github actions for Windows and Android apps. Signing macOS apps is outside the scope of this project, but you can set it up yourself. See electron builder's docs.

Before you start, you may want to get familiar with adding secrets to your Github project.

Android code signing in Github Actions

The following is a simplified version of Stanislav Khromov's article. If you don't already have a keystore for Android app signing, start by reading that article.

  • Encode your keystore as a base64 string
  • Upload your keystore (now a base64 string) as a secret called RELEASE_KEYSTORE in your Github repo
  • Add your password as a secret called RELEASE_KEYSTORE_PASSWORD
  • Add your alias as a secret called RELEASE_KEYSTORE_ALIAS
  • Add your alias password as a secret called RELEASE_KEYSTORE_ALIAS_PASSWORD
  • You may now run the Build Android Github Action

Windows code signing in Github Actions

This process requires a .p12 or .pfx certificate file. The following instruction uses certutil, which is part of Windows.

  • Base64 encode the certificate using certutil -encode certificate.pfx base64cert.txt where certificate.pfx is the .pfx file and base64cert.txt is the output file
  • Add the base64-encoded text as a secret called CSC_LINK in your Github repo
  • Add the password to decrypt the cerificate as a secret called CSC_KEY_PASSWORD in your Github repo

Turning signing OFF

If you'd rather skip code signing for Windows, do the following:

  • Edit .electron-builder.config.js to set signAndEditExecutable to false

Export formats

This project generates unpacked directories by default. This format is suitable for uploading to distrbution platforms like Itch.

If you're not using a distribution platform that handles updates, you should set up auto update in Electron to ensure users of your app always have access to the latest and most secure version of your software.

If you'd like to generate simple executables that your audience downloads directly, here's what I recommend:

Windows Portable .exe

Update your .electron-builder.config.js:

win: {
	target: ['portable'],
	signAndEditExecutable: true,
},
portable: {
	unpackDirName: true,
},

Slow app start

Portable apps have to extract their files from a compressed archive before they can start, and this process takes around 10 seconds.

You can choose to add a splash screen to the portable app, so the user sees something while the app is unpacking. Your splash file should be the BMP format.

Update the .electron-builder.config.js file so it contains a path to your splash image:

portable: {
	splashImage: 'src-electron/buildResources/splash.bmp',
	unpackDirName: true,
},

macOS .dmg

Update your .electron-builder.config.js:

mac: {
	target: {
		target: 'dmg',
		arch: 'universal',
	},
	darkModeSupport: true,
},

Linux .flatpak, .AppImage and .snap

Update your .electron-builder.config.js:

linux: {
	target: ['AppImage', 'flatpak', 'snap'],
	// https://specifications.freedesktop.org/menu-spec/latest/apa.html#main-category-registry
	category: 'Game',
},
snap: {
	allowNativeWayland: true,
},
flatpak: {
	useWaylandFlags: true,
},

Flatpak

Building Flatpaks on Ubuntu requires extra dependencies.

The default Github Action will fail when trying to build a Flatpak due to these missing dependencies. Add in an extra step after Setup NodeJS:

- name: (Ubuntu) Install Flatpak dependencies
	if: matrix.os == 'ubuntu-latest'
	run: |
		sudo apt-get install -y flatpak flatpak-builder elfutils
		flatpak remote-add --if-not-exists --user flathub https://flathub.org/repo/flathub.flatpakrepo
		git config --global --add protocol.file.allow always

License

You may choose to use this software under either of the following licenses, at your option:

Your contributions

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual licensed as above, without any additional terms or conditions.

Thanks