Urbit Developer Examples

This repo contains the source for the following examples presented in the
Urbit developer documentation:

In the documentation that follows, the following shorthands are used:

• /path/to/X/: The path to directory X on your local machine.
• example-directory: The directory of an example in the source tree of this
  repository (see the table above).
• example-desk: The Urbit desk name of an example in this repository (see
  the table above).

Install

Each developer example is hosted on ~pocwet and available for direct install
via Urbit software distribution. To install the example on your ship, enter the
following commands into your ship's webterm or dojo:

|install ~pocwet %example-desk
|mount %example-desk

You can then view the files associated with this example on your machine at the
file path /path/to/ship/example-desk. Please note that this method will only
install Hoon files; to view and experiment with React front-end files, please
read on.

Build

First-time Setup

To build one of these example from scratch (which is essential for React
development), follow these instructions:

1. Download and extract the repo source code from GitHub, e.g.
   at /path/to/repo-source/.
2. Follow the instructions for creating a fake ship, e.g.
   hosting it at /path/to/fake-ship/.
3. When booting up your fake ship, take note of the following line in
   the introductory digest:

   http: web interface live on http://localhost:XYZ
   

   The XYZ string on this line is port number your ship is using for its HTTP
   interface. Save this string for use in the subsequent steps.
4. In your fake ship's dojo, enter the following commands:

   |new-desk %example-desk
   |mount %example-desk
   

5. In a separate terminal session, enter the following commands:

   rm -rI /path/to/fake-ship/example-desk/*
   cp -RL /path/to/repo-source/example-directory/full-desk/* /path/to/fake-ship/example-desk/

6. Back in your fake ship's dojo, enter the following commands:

   |commit %example-desk
   |install our %example-desk
   

7. Again in your fake ship's dojo, run the following command and copy the
   result:

   +code
   

   This is your fake ship's password, which will be used for authentication
   from your web browser.
8. Open a web browser and navigate to the HTTP address discussed in step 3.
9. Paste the ship's password from step 7 into the form that appears and hit
   enter.
10. If the installation was successful, you should see a tile for the example
    on the home page that appears.

If the example has a React interface, further follow these instructions to
set up a locally-hosted front-end interface:

11. In a terminal session, enter the following commands (where XYZ is from
    step 3):

    cd /path/to/repo-source/example-directory/ui/
    npm install
    echo "VITE_SHIP_URL=http://127.0.0.1:XYZ" >> .env.local
    npm run dev

    The final command will generate a text digest containing a line of the form:

    > Local: http://localhost:ABC/apps/example-desk/
    

    The web address listed here is hosting location for your local React
    interface. Save this string for use in the subsequent steps.
12. Open a web browser and navigate to the web address from the step 11.
    If the local hosting was successful, you should see the interface for the
    example in your browser.

Editing and Rebuilding

Once the base infrastructure for an example project is in place, making changes
is very simple.

For React front-end development, just make sure to run npm run dev in a
terminal and to visit the output "local" address for testing; the page will
automatically update as you edit your React files.

For Sail front-end development and back-end development, the process is only
slightly more complicated:

1. If you're editing the files in-place (i.e. in
   /path/to/fake-ship/example-desk/), you can skip this step. If you're
   editing files from the source tree
   (i.e. in /path/to/repo-source/example-directory/full-desk/), you'll need
   to copy the files to your ship with the following terminal commands:

   rm -rI /path/to/fake-ship/example-desk/*
   cp -RL /path/to/repo-source/example-directory/full-desk/* /path/to/fake-ship/example-desk/

2. From within your fake ship's dojo, enter one of the following command
   sequences based on your changes:
   • If you didn't make any changes to the example app's data model:

     |commit %example-desk
     

   • If you did make changes to the example app's data model (e.g. via /sur
     file changes, app state changes, etc.):

     |nuke %example-desk
     |commit %example-desk