Applet-template

https://github.com/neighbour-hoods/applet-template

applet-template

This repository is a template for creating nh-we applets. It is meant to be cloned and provide the basic repository structure and scripts for developing and testing your nh-we applets.

DISCLAIMER: Please note this is only a template that mostly provides repository structure and helpful npm scripts, you will still need to write your own zome functions, entry types, validation functions, and the relevant tests. To speed up this process you can try the Holochain Scaffolding tool to get basic CRUD functionality and tests scenarios. However, you will still have to implement much of the logic of your application.

getting started

1. set up your development environment by following the steps in Environment Setup, and if you are having issues with nix see Without Nix

2. familiarize yourself with the repository structure and reactive state management documents and the use of two important dependencies: @neighbourhoods/nh-launcher-applet & @neighbourhoods/sensemaker-lite-types

3. Clone this repository & run npm i

4. add your zome code (copy/edit files under to dna, tests and ui folders)

5. replace all instances of provider to match your hApp zome name (including in file or directory names), remember to review the .yaml files too

6. create your applet config and add it to both ./ui/src/appletConfig.ts & ./we-applet/src/appletConfig.ts. See Creating Applet Config

7. build your front end store object (see providerStore.ts)

8. test your UI with npm run start

9. package your applet as a .webhapp file to be imported by nh-we with npm run package

using the holochain scaffolding tool

If you want to use the scaffolding tool to generate your holochain code, you can easily replace the dnas directory in this repository with the dnas directory generated through the scaffolding tool. In the future we hope to have a smoother integration between the two, but for now the steps look like:

1. create a separate repo

2. inside that repo, run hc scaffold example forum (or more specific uses of the command)

3. copy the generated dnas folder and replace the dnas folder in this repository with that one.

4. replace the root level Cargo.toml with the one from the scaffolding tool.

5. you will still need to change references to provider to whatever you are calling your dnas.

testing your applet in NH Launcher

once you are ready to test your applet in we, you will need to run nh-we in developer mode to upload the webhapp file. To do that:

1. git clone nh-launcher
2. git fetch and switch to the develop branch

3. follow steps in the read me (nix develop, npm i, npm run start) to get we running in dev mode (it should launch into the browser)
4. create a we group

5. create your user in the group

6. go to applet library

7. select INSTALL APPLET FROM FILESYSTEM button

8. navigate to you applet .webhapp file and click install

Applet Config

The Applet Config is where the Sensemaker compatible social interactions of your applet are defined, you can specify:

• Dimensions and Ranges: to define in what ways your users can assess (for example, react or rate) your applet resources (computed dimensions can only receive values from Methods)

• ConfigResourceTypes: they allow you to map hApp entry-types to sensemaker resources that can receive assessments

• ConfigMethods: they allow performing computations on top of existing input_dimensions into an output_dimension, following a program brick (find more about the supported bricks at this link).
• ConfigThresholds: they define how a Cultural Context will filter resources to be shown

• ConfigCulturalContexts: these allow the SenseMaker to filter and order resources according to rules defined in Thresholds and ordered according to order_by.

• AppletConfigInput: this object holds together all defined configurations for your Applet.

In the future we are providing a visual Wizard to make the creationg of such config files easier.

Environment Setup

1. Install the holochain dev environment (using nix): https://developer.holochain.org/docs/install/ (see https://hackmd.io/BKCt3FckSiSDJ4aSJ1Ur6A for a more comprehensive guide, especially if you are used to using nix-shell and default.nix)
2. Enable Nix commands and Nix flakes for your use:

mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

1. Clone this repo and cd inside of it.

2. Enter the nix shell by running this in the root folder of the repository:

This will install all the needed dependencies in your local environment, including holochain, hc and npm.

Run all the other instructions in this README from inside this nix environment, otherwise they won't work.

Without Nix

It is possible to work with these repos without nix, but you will need to install the needed cargo packages to your local system. Run the following commands:

cargo install holochain --version 0.1.0
cargo install lair_keystore --version 0.2.3
cargo install holochain_cli_launch --version 0.0.11
cargo install holochain_scaffolding_cli --version 0.1.6

make sure they are properly installed with:

holochain --version
lair-keystore --version
hc-launch --version
hc-scaffold --version

Running the DNA tests

Building the DNA

Package

To package the web happ:

You'll have the provider.webhapp in workdir. This is what you should distribute so that the Neighbourhoods Launcher can install it.

You will also have its subcomponent provider.happ in the same folder`.

Documentation

This repository is using this tooling:

• NPM Workspaces: npm v7's built-in monorepo capabilities.
• hc: Holochain CLI to easily manage Holochain development instances.
• Holochain scaffolding: Scaffolding tool used to create simple hApps.
• @holochain/tryorama: test framework.
• @holochain/client: client library to connect to Holochain from the UI.
• @holochain-playground/cli: introspection tooling to understand what's going on in the Holochain nodes.