aljaz/pear-docs
1
0
Fork 0
mirror of https://github.com/aljazceru/pear-docs.git synced 2025-12-17 14:34:19 +01:00
Code Issues Packages Projects Releases Wiki Activity

Move more code into 'Starting a Pear App'

Browse Source
This commit is contained in:
Tobias Baunbaek
2023-12-07 16:12:09 +01:00
parent 6eaa89adad
commit 4160c6330a
3 changed files with 119 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

118
guides/making-a-pear-app.md
View File

@@ -2,117 +2,19 @@
## Step 1. Install modules
This app uses these modules: `hyperswam`, `hypercore-crypto`, and `b4a`.
This app uses these modules: `hyperswarm`, `hypercore-crypto`, and `b4a`.
```
$ npm i hyperswam hypercore-crypto b4a
$ npm i hyperswarm hypercore-crypto b4a
```
**Note**: If the modules are installed while the app is running an error is thrown similar to `Cannot find package 'hyperswarm' imported from /app.js`. When installing modules, close down the app, before they can be installed.
- [hyperswam](https://www.npmjs.com/package/hyperswam). One of the main building blocks. Find peers that share a "topic".
- [hyperswarm](https://www.npmjs.com/package/hyperswarm). One of the main building blocks. Find peers that share a "topic".
- [hypercore-crypto](https://www.npmjs.com/package/hypercore-crypto). A set of crypto function used in Pear.
- [b4a](https://www.npmjs.com/package/b4a). A set of functions for bridging the gap between the Node.js `Buffer` class and the `Uint8Array` class.
## Step 2. Create the UI
In this first version, users are able to create a chat room or join others. Then write messages to each other.
``` html
<!DOCTYPE html>
<html>
<head>
<style>
body {
display: flex;
height: 100vh;
color: white;
justify-content: center;
margin: 0;
padding: 0;
}
.hidden {
display: none !important;
}
#setup {
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
}
#loading {
align-self: center;
}
#chat {
display: flex;
flex-direction: column;
width: 100vw;
}
#header {
display: flex;
justify-content: space-between;
}
#messages {
flex: 1;
font-family: 'Courier New', Courier, monospace;
overflow-y: scroll;
}
#message-form {
display: flex;
}
#message {
flex: 1;
}
</style>
<script type='module' src='./app.js'></script>
</head>
<body>
<div id="setup">
<div>
<button id="create-chat-room">Create chat room</button>
</div>
<div>
- or -
</div>
<div>
<button id="join-chat-room">Join chat room</button>
<input id="join-chat-room-topic" type="text" placeholder="Topic for chat room" />
</div>
</div>
<div id="loading" class="hidden">Loading ...</div>
<div id="chat" class="hidden">
<div id="header">
<div>
Topic: <span id="chat-room-topic"></span>
</div>
<div>
Peers: <span id="peers-count">0</span>
</div>
</div>
<div id="messages"></div>
<form id="message-form">
<input id="message" type="text" />
<input type="submit" value="Send" />
</form>
</div>
</body>
</html>
```
After running with `pear dev` it should look like this:
![Layout of the app](../assets/chat-app-3.png)
## Step 6. Write the javascript code, using `hyperswarm`
## Step 2. Write the javascript code, using `hyperswarm`
Open `app.js` in a code editor and replace with this:
@@ -159,7 +61,7 @@ async function joinSwarm(topicBuffer) {
document.querySelector('#setup').classList.add('hidden')
document.querySelector('#loading').classList.remove('hidden')
// Join the swam 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()
@@ -210,16 +112,20 @@ After that the two apps are able to send messages between them
## Understanding the code
Looking through the code, a great part of it has to with handling the layout. It's outside of the scope of this tutorial to delve into that, but shouldn't look unfamiliar to most. It's possible to use larger frameworks like React, but that will be covered in other examples.
Looking through the code, a great part of it has to do with handling the layout. It's outside of the scope of this tutorial to delve into that, but shouldn't look unfamiliar to most. It's possible to use larger frameworks like React, but that won't be covered here.
There are two main differences between a more common client-server chat app vs this peer-to-peer chat app
### 1. Discovery
In a traditional client-server setup the server is hosted on an ip (or hostname) and a port, e.g. `http://localhost:3000`. This is what clients use to connect the server. And then it's the servers responsibility to have clients find each other.
In a traditional client-server setup the server is hosted on an ip (or hostname) and a port, e.g. `http://localhost:3000`. This is what clients use to connect to the server.
In our code it says `swarm.join(topicBuffer, { client: true, server: true })`. Here `topicBuffer` is a 32 byte string. The creator of a chat room will create a random byte string, which they will share with others, who can then join.
In the code it says `swarm.join(topicBuffer, { client: true, server: true })`. Here `topicBuffer` is a 32 byte string. The creator of a chat room will generate a random byte string, which they will share with others, who can then join.
### 2. No servers
When the chat app was started there wasn't one of them that acting as a server, and another as a client. Instead they join/leave topics. This is an important point, because it means that even if the peer that created a chat room leaves, then it doesn't stop working.
## Next
Everything is starting to look good, and now that there's a running app, it's time to learn how we [share it with others](./sharing-a-pear-app.md).

4
guides/sharing-a-pear-app.md
View File

@@ -45,3 +45,7 @@ $ pear launch pear:nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o
This will download and open the app.
Note: Anyone running the app also help to seed it. So if the app had a lot of users, the original seeder could close down the process.
## Next
The app is shared and others can now run it on their machines. To learn how a more production-ready setup would look like read [releasing a Pear App](./releasing-a-pear-app.md).

103
guides/starting-a-pear-app.md
View File

@@ -40,3 +40,106 @@ Pear apps have automatic reload included. This means that there is no need to st
While keeping the app open with `pear dev`, open `index.html` in a code editor. Change `<h1>chat</h1>` to `<h1>Hello world</h1>` and go to the app again. It should now look like this:
![Automatic reload](../assets/chat-app-2.png)
## Step 4. Create a basic UI
To add some more interesting UI, let's have an example of a chat app, where users are able to create or join chat rooms and write messages to each other.
``` html
<!DOCTYPE html>
<html>
<head>
<style>
body {
display: flex;
height: 100vh;
color: white;
justify-content: center;
margin: 0;
padding: 0;
}
.hidden {
display: none !important;
}
#setup {
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
}
#loading {
align-self: center;
}
#chat {
display: flex;
flex-direction: column;
width: 100vw;
}
#header {
display: flex;
justify-content: space-between;
}
#messages {
flex: 1;
font-family: 'Courier New', Courier, monospace;
overflow-y: scroll;
}
#message-form {
display: flex;
}
#message {
flex: 1;
}
</style>
<script type='module' src='./app.js'></script>
</head>
<body>
<div id="setup">
<div>
<button id="create-chat-room">Create chat room</button>
</div>
<div>
- or -
</div>
<div>
<button id="join-chat-room">Join chat room</button>
<input id="join-chat-room-topic" type="text" placeholder="Topic for chat room" />
</div>
</div>
<div id="loading" class="hidden">Loading ...</div>
<div id="chat" class="hidden">
<div id="header">
<div>
Topic: <span id="chat-room-topic"></span>
</div>
<div>
Peers: <span id="peers-count">0</span>
</div>
</div>
<div id="messages"></div>
<form id="message-form">
<input id="message" type="text" />
<input type="submit" value="Send" />
</form>
</div>
</body>
</html>
```
After running with `pear dev` it should look like this:
![Layout of the app](../assets/chat-app-3.png)
## Next
Now that there's some basic UI for a chat app, let's take a look at [making a Pear App](./making-a-pear-app.md).