Urbit React Cookbook
In this lesson you will learn how to build a React frontend that connects to your ship and interacts with it using the four basic forms of communication, namely: poke, subscribe, thread, scry. These examples will get you started building React apps for Urbit as well as familiarize you with the Urbit APIs required to get you writing your own custom functions.
This project was bootstrapped with Create React App.
Getting Started
First run yarn install to install project dependencies.
Then boot a fake ~zod ship connected to localhost port 8080 (alternatively you can select a different port by editing src/App.tsx) For instructions on booting fake ships see this guide.
Then run yarn start to boot the local React server which will run at http://localhost:3000 by default.
In a separate browser tab connect to your fake ~zod's Landscape page which is http://localhost:8080 or a custom port of you changed it
Back at the React app, enter your ships localhost address and code in the top right corner. In this example the host will be http://localhost:8080. Obtain your ship's code by enter +code in your ship's dojo. For ~zod the code will be lidlut-tabwed-pillex-ridrup. Then press "Login."
Now we've almost got everything setup and talking to each other. Finally enter +cors-registry in your ship's dojo. You will likely see two URLs in the requests entry:
~~http~3a.~2f.~2f.localhost~3a.3000
and
~~http~3a.~2f.~2f.localhost~3a.8080
You'll need to add it to the approved list by running:
|cors-approve ~~http~3a.~2f.~2f.localhost~3a.3000
and
|cors-approve ~~http~3a.~2f.~2f.localhost~3a.8080
Verfiy these commands worked by running +cors-registry again.
Logging in
Click here for a detailed walkthrough of the login flow you performed above
Creating Groups
How to call threads
Start by adding a group using the form on the left of the React app. Enter a Group Name, Group Description and press "Create Group." Your browser will confirm the successful creation with an alert window. After clicking OK in the alert window navigate to your Landscape tab to confirm that the group was created and it's tile added.
Click here for a detailed walkthrough of the Creating Groups functions and UI
Creating Channels
How to create and maintain subscriptions
Back in the React app, fill in the middle "Create Channel" inputs. Select your newly created group from the drop-down and enter a Chat Name and Description and press "Create Channel". This should also be confirmed by a window alert upon success.
After clicking OK in the alert window navigate to your Landscape page to confirm that the channel was created within your previously created group.
Click here for a detailed walkthrough of the Creating Channels functions and UI
Sending Messages
Calling threads and managing subscriptions
NOTE: We are still waiting on an update to @urbit/http-api that uses the new group-update versioning syntax. Until then the steps below will not work.
Again back in the React app, select a chat from the drop-down menu under "Send Message" and enter some text. Upon clicking the "Send Message" button you should once again receive a confirmation alert.
Your message should now appear at the top of the React app. You can navigate back to your Landscape window to see the message you just sent from React displayed in the newly created channel.
Notice that you can send a message to the channel from Landscape and that it will also appear at the top of the React app.
Click here for a detailed walkthrough of the Sending Messages functions and UI
Adding Members
How to send a poke
In this input select a Group that you have created from the dropdown menu and enter a ship with '~' prefix. Then press "Add Member"
Confirm that the member has been added via Group info in Landscape. You can find this information be clicking on the Group tile. Then the gear icon in the top left corner of the group. From there click on Participants and confirm the ship you added is listed
Try adding a few different ships
Click here for a detailed walkthrough of the Adding Members functions and UI
Removing Members
Using pokes
First select one of the groups you created from the "Select a Group" drop down in this section
After selecting a group the list of members will auto-populate in the "Select a Member" dropdown. Select a member from this list
Now click "Remove Member" and then confirm that this user was indeed removed via your Landscape interface
Click here for a detailed walkthrough of the Removing Members functions and UI
Inviting Members
Using threads
To fully test this function we recommend booting another fake ship on your local network. Follow the instructions in the introduction to this guide for support in creating and booting fake ships. Call this second one ~mus
After ~mus is running, you should see ~zod is your neighbor displayed in its terminal. Check which port it is running on by looking for a message similar to this: http: web interface live on http://localhost:8081 in the startup text. Use that link to log into it's Landscape interface
Back in the React interface, select a group under the "Invite Members" heading
Enter the name of your new fake ship in the input below, ~mus in my case
Then enter a message and press "Send Invite"
After clicking "Ok" in confirmation popup, navigate to the ~mus Landscape interface. After a few moments you should receive a notification ontop of the Leap menu in the top left corner. Click on it to accept your invite and join the group.
Once inside the group you will have access the channel(chat) you created in the previous step. Notice that you can send a message in the chat from ~mus and it will display at the top of our React interface
Click here for a detailed walkthrough of the Inviting Members functions and UI
Removing Channels
Using threads
To test this function start by adding a new channel under the Create Channel heading.
Verify that it has been added by checking in Landscape. You can also test it by selecting it from the "Select a Channel" dropdown selector under the "Remove Channels" header. Go ahead and select it from this menu and click "Remove Channel."
Confirm the pop and then verify the channel has been removed from both the drop down menus and your Landscape tab.
Click here for a detailed walkthrough of the Inviting Members functions and UI
Removing Groups
Using threads
Choose your group from "Select a Group" dropdown under the "Remove Group" header and click "Remove Group".
Click OK and verify that the group and its tile has been removed from Landscape.
Click here for a detailed walkthrough of the Inviting Members functions and UI
Scrying Messages
How to scry
This function allows you to scry a variable number of recent messages from a given channel. To test this out go ahead and send a few messages to one of the channels you created. Bonus points if you send a few more from another ship that you added or invited
Now select this channel from the dropdown under "Scrying Messages"
In the "Count" input enter a number of messages to scry out of graph-store
Finally press "Scry Messages" and check the results in the console
Click here for a detailed walkthrough of the Scrying Messages functions and UI