{"id":24915148,"url":"https://github.com/ssbc/ssb-ahoy","last_synced_at":"2025-10-17T01:31:44.098Z","repository":{"id":36462360,"uuid":"170441697","full_name":"ssbc/ssb-ahoy","owner":"ssbc","description":"An onboarding mini-app - gets you all set up, and caught up on the gossip before you set out on your adventure","archived":false,"fork":false,"pushed_at":"2024-04-11T12:12:56.000Z","size":2365,"stargazers_count":22,"open_issues_count":5,"forks_count":3,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-04-14T12:08:30.688Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ssbc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-02-13T04:43:41.000Z","updated_at":"2022-04-06T21:46:56.000Z","dependencies_parsed_at":"2023-10-16T13:19:26.951Z","dependency_job_id":"477d9598-ae17-4f42-a577-519871d97f1c","html_url":"https://github.com/ssbc/ssb-ahoy","commit_stats":{"total_commits":160,"total_committers":3,"mean_commits":"53.333333333333336","dds":0.1875,"last_synced_commit":"f6afe79eada23c494b171af86639d4a9a2e87f64"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssbc%2Fssb-ahoy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssbc%2Fssb-ahoy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssbc%2Fssb-ahoy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssbc%2Fssb-ahoy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ssbc","download_url":"https://codeload.github.com/ssbc/ssb-ahoy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236686704,"owners_count":19189062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-02T07:16:23.620Z","updated_at":"2025-10-17T01:31:38.749Z","avatar_url":"https://github.com/ssbc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ssb-ahoy !\n\nA module for building electron-based scuttlbutt apps.\nYou provide a UI and plugins, and `ssb-ahoy` takes care of boring details for you.\n\nBuilt with `electron@20.3.8` and `secret-stack@7`\n\nThis version of electron runs Node version `18.6.1` (or something like it)\n\n## Getting started \n\n```bash\n$ npm i ssb-ahoy\n```\n\nCreate a root file for your project:\n```js\n// index.js\nconst ahoy = require('ssb-ahoy')\nconst path = require('path')\n\nahoy(\n  'http://localhost:8080', // an address (http/file) for UI\n  {\n    plugins: [\n      require('ssb-db'),\n      require('ssb-backlinks')\n    ]\n  },\n  (err, ssb) =\u003e {\n    if (err) throw err\n\n    console.log('ahoy started', ssb.id)\n  }\n)\n```\n\nAdd a script to your package.json:\n```json\n// package.json\n{\n  \"main\": \"index.js\",\n  \"scripts\": {\n    \"start\": \"electron index.js\"\n  }\n}\n```\n\nRun it:\n```bash\n$ npm start\n```\n\n## API\n\n### `ahoy(url, opts, cb)`\n\n- `url` *String* - a url to load the app UI from\n  - can start with\n      - `http:`, `https:` - great for local dev-servers\n      - `file:` - useful when you bundle ui for production, electron fetches directly from file system\n          - e.g. `file://${path.join(__dirname, 'dist/index.html)}'\n  - required\n\n- `opts` *Object* with properties:\n    - `opts.title` *String* - the title of your app\n        - will be the title of the app window\n        - default: `'hello_world'`\n    - `opts.plugins` *[Plugin]* - an array of `secret-stack` plugins\n        - default: `[]`\n    - `opts.config` *Object* - over-rides what's passed to `secret-stack` + `plugins` on launch\n        - `opts.config.path` *String* - location your database + secret will be installed\n            - default: `\\${envPaths.data}/ssb-ahoy/dev/\\${format(opts.title)}` \n        - generally defaults follow `ssb-config/defaults.js`\n\n- `cb` *function* callback which is run once ssb and electron have started up\n\n\n### `ahoy(url, opts) =\u003e Promise`\n\nConvenience method which is a `promisify`'d version of the last method.\n\n## `window.ahoy` (ui window api)\n\nThere's a method exposed in the UI window, that can be used like this:\n\n```js\nwindow.ahoy.getConfig()\n  .then(config =\u003e {\n    // could use this to connect to back end with e.g. ssb-client\n    console.log(config)\n  })\n```\n\n\n## Templates\n\nThis repo includes two working example templates.\nStart simple and upgrade as your interest and time permits\n\n- [Simple Template](./templates/simple/README.md)\n- [Advanced Template](./templates/advanced/README.md)\n\n\n## Building installers\n\nYour project MUST have:\n- a package.json with:\n    - `main` pointing at the file which contains your ahoy setup (electron-builder uses this to build from)\n    - `script` for building release\n    ```json\n    {\n      \"main\": \"main.js\",\n      \"script\": {\n        \"release\": \"electron-builder --config builder/config.js\"\n      }\n    }\n    ```\n- an `electron-builder` config\n    - the \"release\" script points at this\n    - putting your config in a `js` file means you can annotate it (you should)\n    - see `templates/builder/config.js` for the most minimal template\n\n\n### Native dependencies\n\nScuttlebutt is built with _native dependencies_ - libraries for cryptography/ database work\nthat depend on lower level C libraries that need to be compiled for particular architectures\n(i.e. are native).\n\n`electron-builder` does a great job of making sure that the versions installed are compatible\nwith the electron environement we're running them in, but sometimes it trips up.\n\nYou can often address this by adding a script to your package.json like:\n    ```json\n    {\n      \"script\": {\n        \"postinstall\": \"npm run fixDeps\",\n        \"fixDeps\": \"electron-builder install-app-deps\"\n      }\n    }\n    ```\n\nMost of the modules typically used have \"prebuilds\" which are just fetched from the internet.\nIf a prebuild doesn't exist you may have to build it yourself - read the errors, you'll likely\nsee `node-gyp` mentioned, which is a one common node tool for compiling dependencies.\n\n\n## Resouces:\n\n- `electron`\n  - www.electronjs.org/releases\n  - [CHANGELOG](https://www.electronjs.org/releases/stable)\n- `electron-builder`\n  - www.electron.build\n  - [CHANGELOG](https://github.com/electron-userland/electron-builder/blob/master/packages/electron-builder/CHANGELOG.md)\n- Apple's painful signing process:\n    - https://kilianvalkhof.com/2019/electron/notarizing-your-electron-application/\n\n---\n\n## Development\n\n## Notes\n\n- we pin `electron` to an exact version here for 2 reasons:\n    - ensure it's tested + stable in this module\n    - help `electron-builder` to know _exactly_ what it's building against\n\n- adding `electron` and `electron-builder` to peerDependencies was done to try and make it as easy as possible to get started with `ssb-ahoy`. Things to take into acount if changing this:\n    - build size: current example app makes an 83MB AppImage\n        - if you set things up incorrectly, this will jump to 125MB+\n    - not having to manually install lots of modules\n    - `electron-builder` shouldn't need to be told what version of `electron` it's building for\n\n- adding `dmg-license` to optionalDependencies was done to try and make it as easy as possible to get started for mac users\n    - this module throws some error if you try and install it on linux\n    - listing it here seems to stimulate installation of it on macs\n\n- To inspect `app.asar` files:\n    ```bash\n    $ cd example/dist/installers/linux-unpacked/resources\n    $ npx asar extract app.asar destfolder\n    $ filelight destfolder\n    ```\n    - alternatively, temporarily set `asar: false` in electron-builder config\n    - _filelight is a linux tool for visually exploring folders_\n- `electron \u003e 20.3.8` currently breaks important `sodium-native` functions\n    - https://github.com/sodium-friends/sodium-native/issues/185\n    - this is currently blocking further upgrades\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fssbc%2Fssb-ahoy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fssbc%2Fssb-ahoy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fssbc%2Fssb-ahoy/lists"}