From 3817bff892abd0703186f4757512bc0f66ef944c Mon Sep 17 00:00:00 2001 From: Vivek Singh <47470314+heyitsvi@users.noreply.github.com> Date: Tue, 27 Aug 2024 15:45:39 +0530 Subject: [PATCH] Update guides (#134) * update desktop guide * update pear terminal guides * fixes * fix ctrl-c for example terminal app * use SIGINT on readline close --------- Co-authored-by: rafapaezbas --- guide/debugging-a-pear-terminal-app.md | 2 +- guide/making-a-pear-desktop-app.md | 14 +++++------ guide/making-a-pear-terminal-app.md | 21 +++++++++++----- guide/releasing-a-pear-app.md | 2 +- guide/sharing-a-pear-app.md | 6 ++--- guide/starting-a-pear-desktop-project.md | 29 ++++++++++++++++------- guide/starting-a-pear-terminal-project.md | 6 +++-- 7 files changed, 52 insertions(+), 28 deletions(-) diff --git a/guide/debugging-a-pear-terminal-app.md b/guide/debugging-a-pear-terminal-app.md index 3b201c1..9d8dad2 100644 --- a/guide/debugging-a-pear-terminal-app.md +++ b/guide/debugging-a-pear-terminal-app.md @@ -30,7 +30,7 @@ if (Pear.config.dev) { As the code specifies, `pear-inspect` is only running when in dev mode, so start the app: ``` -pear dev . +pear run --dev . ``` The application will output something similar to: diff --git a/guide/making-a-pear-desktop-app.md b/guide/making-a-pear-desktop-app.md index 4300b2d..acd2316 100644 --- a/guide/making-a-pear-desktop-app.md +++ b/guide/making-a-pear-desktop-app.md @@ -159,7 +159,7 @@ Start by defining the app's layout in `index.html`: ``` -Running `pear dev` should show +Running `pear run --dev .` should show ![Layout of the app](../assets/chat-app-3.png) @@ -190,7 +190,7 @@ Replace `app.js` with import Hyperswarm from 'hyperswarm' // Module for P2P networking and connecting peers import crypto from 'hypercore-crypto' // Cryptographic functions for generating the key in app import b4a from 'b4a' // Module for buffer-to-string and vice-versa conversions -const { teardown } = Pear // Cleanup function +const { teardown, updates } = Pear // Cleanup and updates function const swarm = new Hyperswarm() @@ -198,6 +198,10 @@ const swarm = new Hyperswarm() // (This is not a requirement, but it helps avoid DHT pollution) teardown(() => swarm.destroy()) +// Enable automatic reloading for the app +// This is optional but helpful during production +updates(() => Pear.reload()) + // When there's a new connection, listen for new messages, and add them to the UI swarm.on('connection', (peer) => { // name incoming peers after first 6 chars of its public key as hex @@ -267,11 +271,7 @@ function onMessageAdded (from, message) { ## Step 4. Chat -Open two app instances by running `pear dev` in two terminals. For now, you will need to specify a different storage directory for the second `pear` instance to allow for two instances to run simultaneously: - -``` -pear dev -s /tmp/tmp_pear_instance -``` +Open two app instances by running `pear run --dev .` in two terminals. In the first app, click on `Create`. A random topic will appear at the top. diff --git a/guide/making-a-pear-terminal-app.md b/guide/making-a-pear-terminal-app.md index ec661e8..327bdc6 100644 --- a/guide/making-a-pear-terminal-app.md +++ b/guide/making-a-pear-terminal-app.md @@ -14,7 +14,7 @@ Pear runs on [`Bare`](https://github.com/holepunchto/bare), a lightweight JavaSc ``` -npm i bare-readline bare-tty hyperswarm b4a hypercore-crypto +npm i bare-readline bare-tty bare-process hyperswarm b4a hypercore-crypto ``` ## Step 2. JavaScript @@ -28,9 +28,10 @@ import b4a from 'b4a' // Module for buffer-to-string and vice-ve import crypto from 'hypercore-crypto' // Cryptographic functions for generating the key in app import readline from 'bare-readline' // Module for reading user input in terminal import tty from 'bare-tty' // Module to control terminal behavior +import process from 'bare-process' // Process control for Bare -const { teardown, config } = Pear // Import configuration options and cleanup functions from Pear +const { teardown, config, updates } = Pear // Import configuration options, updates and cleanup functions from Pear const key = config.args.pop() // Retrieve a potential chat room key from command-line arguments const shouldCreateSwarm = !key // Flag to determine if a new chat room should be created const swarm = new Hyperswarm() @@ -39,6 +40,10 @@ const swarm = new Hyperswarm() // (This is not a requirement, but it helps avoid DHT pollution) teardown(() => swarm.destroy()) +// Enable automatic reloading for the app +// This is optional but helpful during production +updates(() => Pear.reload()) + const rl = readline.createInterface({ input: new tty.ReadStream(0), output: new tty.WriteStream(1) @@ -70,6 +75,10 @@ rl.on('data', line => { }) rl.prompt() +rl.on('close', () => { + process.kill(process.pid, 'SIGINT') +}) + async function createChatRoom () { // Generate a new random topic (32 byte string) const topicBuffer = crypto.randomBytes(32) @@ -86,7 +95,7 @@ async function joinChatRoom (topicStr) { } async function joinSwarm (topicBuffer) { - // Join the swarm with the topic. Setting both client/server to true means that this app can act as both. + // Join the swarm with the topic. Setting both client/server to true means that this app can act as both. const discovery = swarm.join(topicBuffer, { client: true, server: true }) await discovery.flushed() } @@ -105,7 +114,7 @@ function appendMessage ({ name, message }) { ## Step 3. Run in dev mode -To test this chat app, in one terminal run `pear dev .` +To test this chat app, in one terminal run `pear run --dev .` The app will output something similar to: @@ -113,7 +122,7 @@ The app will output something similar to: [info] Created new chat room: a1b2c35fbeb452bc900c5a1c00306e52319a3159317312f54fe5a246d634f51a ``` -In another terminal use this key as input, `pear dev . a1b2c35fbeb452bc900c5a1c00306e52319a3159317312f54fe5a246d634f51a` +In another terminal use this key as input, `pear run --dev . a1b2c35fbeb452bc900c5a1c00306e52319a3159317312f54fe5a246d634f51a` The app will output: @@ -128,4 +137,4 @@ Type something in one of the applications. Two Terminal Applications are now con ## Next -* [Sharing a Pear Application](./sharing-a-pear-app.md) +* [Sharing a Pear Application](./sharing-a-pear-app.md) \ No newline at end of file diff --git a/guide/releasing-a-pear-app.md b/guide/releasing-a-pear-app.md index b67f3fd..5c31836 100644 --- a/guide/releasing-a-pear-app.md +++ b/guide/releasing-a-pear-app.md @@ -52,7 +52,7 @@ pear seed production After marking a release, make a trivial change to the project (e.g. add a `console.log(...)` somewhere). -First verify that it works by running `pear dev`. +First verify that it works by running `pear run --dev .` Now stage the change with `pear stage production`. diff --git a/guide/sharing-a-pear-app.md b/guide/sharing-a-pear-app.md index 952e04a..aa7dc70 100644 --- a/guide/sharing-a-pear-app.md +++ b/guide/sharing-a-pear-app.md @@ -12,7 +12,7 @@ cd staging-example pear init -y ``` -If starting from [Making a Pear Desktop Application](./making-a-pear-desktop-app.md) or [Making a Pear Terminal Application](./making-a-pear-terminal-app.md) ensure that the comamnd-line current working directory is set to the project folder of the application. +If starting from [Making a Pear Desktop Application](./making-a-pear-desktop-app.md) or [Making a Pear Terminal Application](./making-a-pear-terminal-app.md) ensure that the command-line current working directory is set to the project folder of the application. ## Step 1. Stage the app @@ -50,7 +50,7 @@ Copy the application key that was output when the application was staged in the pear run pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o ``` -Where `pear dev` opens an application from the filesystem, `pear run` opens the application from Pear's application storage. So far the application has remained local, in order to share it with other peers it must be seeded. +`pear run` opens the application from Pear's application storage. So far the application has remained local, in order to share it with other peers it must be seeded. ## Step 3. Seed the app @@ -111,7 +111,7 @@ The trust dialog is a security mechanism in Pear that appears when the user trie ![Trust dialog](../assets/trust-dialog.png) -> During development with `pear dev`, applications are automatically trusted, as they are assumed to be safe for testing purposes. Trust dialog can be suppressed using the `--no-ask-trust` flag with `pear run` in which case the application will automatically decline unknown keys. +> During development with `pear run --dev`, applications are automatically trusted, as they are assumed to be safe for testing purposes. Trust dialog can be suppressed using the `--no-ask-trust` flag with `pear run` in which case the application will automatically decline unknown keys. The application has no state when it's opened for the first time, so the application may show a loader until it's ready to reveal. diff --git a/guide/starting-a-pear-desktop-project.md b/guide/starting-a-pear-desktop-project.md index 5729a28..6ce7edc 100644 --- a/guide/starting-a-pear-desktop-project.md +++ b/guide/starting-a-pear-desktop-project.md @@ -23,21 +23,35 @@ This creates the base project structure. ## Step 2. Verify Everything Works -Use `pear dev` to verify everything works as expected. +Use `pear run` to verify everything works as expected. ``` -pear dev +pear run --dev . ``` -The app should open in development mode. By default, developer tools are also opened. +> A directory or link needs to be specified with `pear run`, here `.` denotes the current Project directory. -![Running pear dev](../assets/chat-app-1.png) +The app should open in development mode. In this mode developer tools are also opened. + +![Running pear run --dev .](../assets/chat-app-1.png) ## Step 3. Automatic Reload -Pear watches project files. When they change, the app is automatically reloaded. +To enable automatic reloading, add the following lines to `app.js` : -While keeping the `pear dev` command running, open `index.html` in an editor. +```js +Pear.updates(() => Pear.reload()) +``` + +Run the app again using: + +```js +pear run --dev . +``` + +Now Pear watches project files. When they change, the app is automatically reloaded. + +While keeping the `pear run --dev .` command running, open `index.html` in an editor. Change `

chat

` to `

Hello world

`. @@ -58,7 +72,6 @@ Open `package.json` and update it to: ... "pear": { "gui": { - "backgroundColor": "#012a02", "height": 400, "width": 700 } @@ -67,7 +80,7 @@ Open `package.json` and update it to: } ``` -Close the app and re-run `pear dev` to see the changes: the background is now light blue, and the initial window size is different. +Close the app and re-run `pear run --dev .` to see the changes, the initial window size is different now. See the [Configuration Documentation](../reference/pear/configuration.md) for all options. diff --git a/guide/starting-a-pear-terminal-project.md b/guide/starting-a-pear-terminal-project.md index 1e3fa02..87074ad 100644 --- a/guide/starting-a-pear-terminal-project.md +++ b/guide/starting-a-pear-terminal-project.md @@ -19,12 +19,14 @@ This creates the base project structure. ## Step 2. Verify Everything Works -Use `pear dev` to see that it works. +Use `pear run` to see that it works. ``` -pear dev +pear run --dev . ``` +> A directory or link needs to be specified with `pear run`, here `.` denotes the current Project directory. + The app will now run. Note that it will keep running until you exit with `ctrl + c`. That's all there is to getting a Pear Terminal project started.