shrub/pkg/interface/CONTRIBUTING.md

Introduction

Thanks for your interest in contributing to the Urbit interface. This section specifically focuses on Landscape development. Landscape lets you integrate your ship with front-end web applications accessed through the browser. It has a core set of applications that accept contributions.

Related to Landscape is Gall, the Arvo vane that controls userspace applications. Landscape applications will usually make good use of Gall, but it's not strictly required if a Landscape application is not interacting with ships directly.

Contributing to Landscape applications

To begin developing on Landscape, find the urbitrc-sample file found at urbit/pkg/interface/config/urbitrc-sample. Copy it as urbitrc. Open it using your preferred code editor and you should see the following:

module.exports = {
  URBIT_PIERS: [
    "/Users/user/ships/zod/home",
  ],
  herb: false,
  URL: 'http://localhost:80'
};

This file is the configuration file for your front-end development environment. Let's walk through it.

The first line, listing piers, specifies which piers to copy the JS files into. By default, the development environment won't copy files into any pier, even if you've set the pier in urbitrc.

If you want to copy the JS files into your ship, as it would run in a regular user environment, uncomment these lines in pkg/interface/config/webpack.dev.js:

// uncomment to copy into all piers
//
// return Promise.all(this.piers.map(pier => {
//   const dst = path.resolve(pier, 'app/landscape/js/index.js');
//   copyFile(src, dst).then(() => {
//     if(!this.herb) {
//       return;
//     }
//     pier = pier.split('/');
//     const desk = pier.pop();
//     return exec(`herb -p hood -d '+hood/commit %${desk}' ${pier.join('/')}`);
//   });
// }));

And then set your pier in urbitrc (ensure it ends in /home). The herb option in your urbitrc will automatically commit the changes to your ship if you have herb installed (see pkg/herb).

For most developers, if you are making changes to Landscape without any back-end changes on the Urbit ship itself, and you have an Urbit ship running already, you don't have to boot a development ship. You can simply set up the dev server for the development environment and point it at your running ship.

To do this, set the URL property in your urbitrc and replace it with the URL of the urbit that you are testing on. For example, a development ship by default lives at localhost:80 so our urbitrc would have:

module.exports = {
  URL: 'http://localhost:80'
}

Then get everything installed:

## go to urbit's interface directory and install the required tooling
cd urbit/pkg/interface
npm install

## Start your development server
npm run start

You can then access a hot reloaded version of the interface at http://localhost:9000.

If you set the URL to your running ship, like http://sampel-palnet.arvo.network, then you can use your actual ship while running local-only development changes.

As previously stated, if your changes require back-end development (front-end and Gall changes, for example), or you just want an empty development environment, you'll want to create a development ship.

Creating a development ship

nix and git-lfs should be installed at this point, and have been used to make build the project.

First follow the instructions for fake ~zod initialization.

Once your fake ship is running and you see

~zod:dojo>

in your console, be sure to 'mount' your ship's working state (what we call 'desks') to your local machine via the |mount % command. This will ensure that code you modify locally can be committed to your ship and initialized.

To set up urbit's Javascript environment, you'll need node (ideally installed via nvm) and webpack, which will be installed via node.

If you want to copy the code into your ship, perform the following steps:

## go to urbit's interface directory and install the required tooling
cd urbit/pkg/interface
npm install

## Build the JS code
npm run build:dev

If you want to run the JavaScript code in a dev server, you can simply set the URL in your urbitrc to localhost:80 and npm run start instead.

If you set your pier in urbitrc, and uncommented the code in the webpack config, then once the build process is running, commit on your ship to copy the changed JS code in:

|commit %home

Your urbit should take a moment to process the changes, and will emit a >=. Refreshing your browser will display the newly-rendered interface.

Once you are done editing code, and wish to commit changes to git, stop your process. Do not commit compiled code, but submit the source code for review.

Please also ensure your pull request fits our standards for Git hygiene.

Linting

The Urbit interface uses Eslint to lint the JavaScript code. To install the linter and for usage through the command, do the following:

$ cd ./pkg/interface
$ npm install
$ npm run lint

To use the linter, run npm scripts

$ npm run lint # lints all files in `interface`
$ npm run lint-file ./src/apps/chat/**/*.js # lints all .js files in `interface/chat`
$ npm run lint-file ./src/chat/app.js # lints a single chosen file

Gall

Presently, Gall documentation is still in progress, but a good reference. For examples of Landscape apps that use Gall, see the code for Chat and Publish.

Creating your own applications

If you'd like to create your own application for Landscape, the easiest way to get started is using the create-landscape-app repository template. It provides a brief wizard when you run it with npm start, and has good documentation for its everyday use -- just create a repo using its template, install and then start it, and you'll soon be up and running.