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
set up your development environment by following the steps in Environment Setup, and if you are having issues with nix see Without Nix
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
Clone this repository & run
npm i
add your zome code (copy/edit files under to
dna
,tests
andui
folders)replace all instances of
provider
to match your hApp zome name (including in file or directory names), remember to review the.yaml
files toocreate your applet config and add it to both
./ui/src/appletConfig.ts
&./we-applet/src/appletConfig.ts
. See Creating Applet Configbuild your front end store object (see
providerStore.ts
)test your UI with
npm run start
package your applet as a
.webhapp
file to be imported by nh-we withnpm 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:
create a separate repo
inside that repo, run
hc scaffold example forum
(or more specific uses of the command)copy the generated
dnas
folder and replace thednas
folder in this repository with that one.replace the root level
Cargo.toml
with the one from the scaffolding tool.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:
git clone
nh-launcher
git fetch and switch to the
develop
branchfollow 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)create a we group
create your user in the group
go to applet library
select
INSTALL APPLET FROM FILESYSTEM
buttonnavigate to you applet
.webhapp
file and clickinstall
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
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
anddefault.nix
)Enable Nix commands and Nix flakes for your use:
Clone this repo and
cd
inside of it.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:
make sure they are properly installed with:
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.
Last updated