Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
187 lines (122 loc) · 8.64 KB

DEVELOPMENT.md

File metadata and controls

187 lines (122 loc) · 8.64 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. assemble-desk.sh vendors the base-dev/landscape dependencies into desk-deps/ (gitignored — see peru.yaml) and layers them with our desk/ into the ship's mounted groups desk:

./scripts/assemble-desk.sh ~/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.

  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. Assemble the %landscape desk (it is built from upstream, not via peru):
    1. From urbit/urbit: rsync -avL --delete pkg/base-dev/* ~/urbit/zod/landscape/
    2. From tloncorp/landscape: rsync -avL desk/* ~/urbit/zod/landscape/
  5. Assemble the %groups desk from this repo. assemble-desk.sh vendors its base-dev and landscape dependencies into desk-deps/ via peru, then layers desk-deps/ + desk/ into the mounted desk:
    1. ./scripts/assemble-desk.sh ~/urbit/zod/groups
  6. Commit and install landscape on local ~zod:
    1. |commit %landscape
    2. |install our %landscape
  7. 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)

E2E Testing

To test locally you need:

  1. Install openjdk21 if you don't have it on your system already.
  2. Install Maestro.
  3. Make sure your repo is up to date with pnpm i and pod install from /apps/tlon-mobile/ios
  4. Run pnpm ios:release from /apps/tlon-mobile.
  5. Wait until the app has booted in the simulator.
  6. Run maestro tests from the root of the repository with the following arguments: maestro test -e URL={URL} -e CODE={CODE} -e EMAIL={EMAIL} -e PASSWORD={PASSWORD} .maestro/00-start.yaml
    1. {URL} should be a self-hosted ship's URL
    2. {CODE} should be the code that goes with that ship
    3. {EMAIL} should be the email of a Tlon hosted account
    4. {PASSWORD} should be the corresponding password for that account

To write tests run:

maestro studio

You can use this to inspect whatever view you have loaded in the simulator. Clicking on elements will suggest selectors/commands to use in your tests. Full set of commands are here: https://maestro.mobile.dev/api-reference/commands

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