Skip to content

Latest commit

 

History

History
164 lines (105 loc) · 7.34 KB

DEVELOPMENT.md

File metadata and controls

164 lines (105 loc) · 7.34 KB
Raw

Development

These instructions are for working on the Tlon app as a developer at Tlon.

Project Structure

  • /desk: The folder containing the desk for %groups. This currently contains the agents necessary for the Tlon app.

  • /apps/tlon-web: Tlon is built primarily using React, Typescript, and Tailwind CSS. Vite ensures that all code and assets are loaded appropriately, bundles the application for distribution and provides a functional dev environment.

Getting Started

To get started working on Tlon, run pnpm install in the root directory.

To develop, you'll need a running ship to point to. To do so you first need to add a .env.local file to the apps/tlon-web directory. This file will not be committed. Adding VITE_SHIP_URL={URL} (where {URL} is the URL of the ship you would like to point to) will allow you to run pnpm dev. This will proxy all requests to the ship except for those powering the interface, which lets you work with live data.

Regardless of what you run to develop, Vite will hot-reload code changes as you work so you don't have to constantly refresh.

Fakezod Development

To get started, make sure your %groups desk is mounted:

|mount %groups

Sync the latest %groups files:

rsync -avL desk/* ~/urbit/zod/groups/

And commit:

|commit %groups

Since %groups has already been released and is now in the pill. It is very unlikely that you would have to create this desk from scratch, but if you do you can follow these instructions or use Tlon's Bouncer utility (requires Ruby 3+).

  1. Clone or pull latest versions of this repo, tloncorp/landscape and urbit/urbit.
  2. Boot a fake ship. Use local networking with -F like so: urbit -F zod
  3. Create and mount the appropriate desks on local ~zod:
    1. |new-desk %landscape
    2. |mount %landscape
    3. |new-desk %groups
    4. |mount %groups
  4. From the urbit/urbit repo:
    1. rsync -avL --delete pkg/base-dev/* ~/urbit/zod/landscape/
    2. rsync -avL --delete pkg/base-dev/* ~/urbit/zod/groups/
  5. From the tloncorp/landscape repo:
    1. rsync -avL desk/* ~/urbit/zod/landscape/
    2. rsync -avL desk-dev/* ~/urbit/zod/groups/
  6. From this repo:
    1. rsync -avL desk/* ~/urbit/zod/groups/
    2. rsync -avL landscape-dev/* ~/urbit/zod/groups/
  7. Commit and install landscape on local ~zod:
    1. |commit %landscape
    2. |install our %landscape
  8. Similarly commit and install Tlon:
    1. |commit %groups
    2. |install our %groups

Deploying

Tlon is distributed via the Urbit network by way of a glob, or a Landscape application bundle. Instructions are as follows:

  1. Run pnpm build in the apps/tlon-web directory, which outputs to /dist.
  2. Create or launch an urbit using the -F flag.
  3. On that urbit, if you don't already have a desk to run from, run |merge %work our %base to create a new desk and mount it with |mount %work.
  4. Now the %work desk is accessible through the host OS's filesystem as a directory of that urbit's pier ie ~/zod/work.
  5. From the repo you can run rsync -avL --delete apps/tlon-web/dist/ ~/zod/work/groups and rsync -avL desk/mar/webmanifest.hoon ~/zod/work/mar/webmanifest.hoon where ~/zod is your fake urbit's pier.
  6. Once completed, run |commit %work on your urbit and you should see your files logged back out from the dojo.
  7. Run =dir /=landscape to switch to the landscape desk directory.
  8. Run -make-glob %work /groups. This will create a glob from the folder where you just added files. It will output to ~/zod/.urb/put.
  9. Navigate to ~/zod/.urb/put you should see a file that looks something like: glob-0v5.fdf99.nph65.qecq3.ncpjn.q13mb.glob. The characters between glob- and .glob are a hash of the glob's contents.
  10. Upload the glob to any publicly available HTTP endpoint that can serve files. This allows the application to be distributed over HTTP.
  11. Once you've uploaded the glob, update the corresponding entry in the docket file at desk/desk.docket-0. Both the full URL and the hash should be updated to match the glob we just created, on the line that looks like this:
glob-http+['https://bootstrap.urbit.org/glob-0v5.fdf99.nph65.qecq3.ncpjn.q13mb.glob' 0v5.fdf99.nph65.qecq3.ncpjn.q13mb]
  1. The docket file containing a pointer to the new glob can now be safely committed and deployed via the Urbit network.

Husky

This project uses husky to run git pre-commit hooks. You may disable Husky by adding HUSKY=0 to your .zshrc or .bashrc.

Glossary

bloc : superuser sects

sects in the bloc set are allowed to make modifications to the group, and its various metadata and permissions

brief : a representation of the last thing we've seen, and how many new items since

cabal : contains the metadata for a role

chat : backend term for a group chat

club : backend term for a multi-DM group (distinct from a chat and a dm)

cordon : represents a group's permissions. open allows anyone to enter but those banned, shut requires requesting to join, afar is a custom policy determined by another agent

curio : represents an item in a collection

dm : backend term for a 1:1 message

flag : composite identifier consisting of ship/group-name used to key state and in routes

fleet : the map of ships that are part of a group

gang : a group invite

heap : a collection

sect : a term representing a role

stash : all heaps we are a part of

vessel : represents the roles a group member has and their join time

bloc : roles that have superuser perms (default is admin)

Cosmos

Run cosmos:

npm run cosmos

Fixtures

Fixtures – Cosmos Docs

Cosmos uses fixture files to generate component previews. You can create fixture files in two ways (from the docs).

  1. End fixture file names with .fixture.{js,jsx,ts,tsx,md,mdx}.
  2. Put fixture files inside __fixtures__.

Fixture files and folders can be nested at any level under /src.

Decorators

Decorators – Cosmos Docs

Many components need to be wrapped with providers or other context to work properly. Cosmos uses a cosmos.decorator.tsx files to share wrappers between components. From the Cosmos docs:

A decorator only applies to fixture files contained in the decorator's directory. Decorators can be composed, in the order of their position in the file system hierarchy (from outer to inner).

How it works

Cosmos runs two servers: a UI wrapper on port 5000, and a renderer on port 5050. The wrapper renders the Cosmos UI, and the renderer renders the actual component previews in an environment that's very close to our standard application environment.

Our setup uses react-cosmos-plugin-vite to configure the renderer. When you start cosmos, it evaluates our vite configuration file, does some module rewiring to replace our main.ts file with its own, and spins up a wrapped vite dev server on a new port.

Cosmos Docs