A module for building electron-based scuttlbutt apps.
You provide a UI and plugins, and ssb-ahoy
takes care of boring details for you.
Built with [email protected]
and secret-stack@7
This version of electron runs Node version 18.6.1
(or something like it)
$ npm i ssb-ahoy
Create a root file for your project:
// index.js
const ahoy = require('ssb-ahoy')
const path = require('path')
ahoy(
'http://localhost:8080', // an address (http/file) for UI
{
plugins: [
require('ssb-db'),
require('ssb-backlinks')
]
},
(err, ssb) => {
if (err) throw err
console.log('ahoy started', ssb.id)
}
)
Add a script to your package.json:
// package.json
{
"main": "index.js",
"scripts": {
"start": "electron index.js"
}
}
Run it:
$ npm start
-
url
String - a url to load the app UI from- can start with
http:
,https:
- great for local dev-serversfile:
- useful when you bundle ui for production, electron fetches directly from file system- e.g. `file://${path.join(__dirname, 'dist/index.html)}'
- required
- can start with
-
opts
Object with properties:opts.title
String - the title of your app- will be the title of the app window
- default:
'hello_world'
opts.plugins
[Plugin] - an array ofsecret-stack
plugins- default:
[]
- default:
opts.config
Object - over-rides what's passed tosecret-stack
+plugins
on launchopts.config.path
String - location your database + secret will be installed- default:
\${envPaths.data}/ssb-ahoy/dev/\${format(opts.title)}
- default:
- generally defaults follow
ssb-config/defaults.js
-
cb
function callback which is run once ssb and electron have started up
Convenience method which is a promisify
'd version of the last method.
There's a method exposed in the UI window, that can be used like this:
window.ahoy.getConfig()
.then(config => {
// could use this to connect to back end with e.g. ssb-client
console.log(config)
})
This repo includes two working example templates. Start simple and upgrade as your interest and time permits
Your project MUST have:
- a package.json with:
main
pointing at the file which contains your ahoy setup (electron-builder uses this to build from)script
for building release
{ "main": "main.js", "script": { "release": "electron-builder --config builder/config.js" } }
- an
electron-builder
config- the "release" script points at this
- putting your config in a
js
file means you can annotate it (you should) - see
templates/builder/config.js
for the most minimal template
Scuttlebutt is built with native dependencies - libraries for cryptography/ database work that depend on lower level C libraries that need to be compiled for particular architectures (i.e. are native).
electron-builder
does a great job of making sure that the versions installed are compatible
with the electron environement we're running them in, but sometimes it trips up.
You can often address this by adding a script to your package.json like:
json { "script": { "postinstall": "npm run fixDeps", "fixDeps": "electron-builder install-app-deps" } }
Most of the modules typically used have "prebuilds" which are just fetched from the internet.
If a prebuild doesn't exist you may have to build it yourself - read the errors, you'll likely
see node-gyp
mentioned, which is a one common node tool for compiling dependencies.
electron
electron-builder
- Apple's painful signing process:
-
we pin
electron
to an exact version here for 2 reasons:- ensure it's tested + stable in this module
- help
electron-builder
to know exactly what it's building against
-
adding
electron
andelectron-builder
to peerDependencies was done to try and make it as easy as possible to get started withssb-ahoy
. Things to take into acount if changing this:- build size: current example app makes an 83MB AppImage
- if you set things up incorrectly, this will jump to 125MB+
- not having to manually install lots of modules
electron-builder
shouldn't need to be told what version ofelectron
it's building for
- build size: current example app makes an 83MB AppImage
-
adding
dmg-license
to optionalDependencies was done to try and make it as easy as possible to get started for mac users- this module throws some error if you try and install it on linux
- listing it here seems to stimulate installation of it on macs
-
To inspect
app.asar
files:$ cd example/dist/installers/linux-unpacked/resources $ npx asar extract app.asar destfolder $ filelight destfolder
- alternatively, temporarily set
asar: false
in electron-builder config - filelight is a linux tool for visually exploring folders
- alternatively, temporarily set
-
electron > 20.3.8
currently breaks importantsodium-native
functions- https://github.com/sodium-friends/sodium-native/issues/185
- this is currently blocking further upgrades