Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mpizenberg/elm-cardano

Elm offchain package for Cardano
https://github.com/mpizenberg/elm-cardano

cardano elm hacktoberfest

Last synced: about 2 months ago
JSON representation

Elm offchain package for Cardano

Awesome Lists containing this project

README 

        
# Elm Cardano



Elm offchain package for Cardano. This project aims to be the friendliest and

most productive way of handling an offchain Cardano frontend. It should be a

perfect match to [Aiken][aiken] for onchain code.



For the time being, the package isn’t published on official elm packages.

So you will find the docs either locally by running elm-doc-preview,

or online at [its static preview page][docs-preview].



[aiken]: https://aiken-lang.org/

[docs-preview]: https://elm-doc-preview.netlify.app/Cardano?repo=mpizenberg%2Felm-cardano&version=elm-doc-preview



## Why elm-cardano?



If you don’t know Elm, you might be tempted to just ignore this,

why use something that isn’t Typescript in 2024?

Well, let me give you the 30s elevator pitch.



Your Elm code will have no runtime exception, so happy users,

and happy maintainers that can focus on building products, not fixing bugs.

Elm is statically typed, with a type system very similar to Aiken one,

and compiler error messages that are so friendly, even Rust was inspired by it.

When your code typechecks, it’s usually working, like in Rust, but even more true in Elm.

Elm packages are very well documented usually.

Every published package has a mandatory check that every exposed function must be documented.

Elm compiles to JavaScript, and has a few ways to interact with,

or be embedded in a regular HTML/JS app.

If you don’t know how, just ask around on the Elm slack, people there are very friendly.



## Quickstart



> Remark: this section aspirational as the elm package is not published yet.



Install the elm-cardano CLI and the Elm package.



```sh

# Install the elm compiler and the elm-cardano CLI

npm install -g elm @mattpiz/elm-cardano



# (Temporary) clone the elm-cardano repo to expose its elm modules

# This step won’t be necessary when the elm package will be published

git clone --depth 1 --branch v0.1.5 https://github.com/mpizenberg/elm-cardano.git



# Initialize a template project in the elm-cardano-starter/ folder

mkdir elm-cardano-starter && cd elm-cardano-starter

npx elm-cardano init

```



This will generate the following template structure:

```sh

.gitignore   # some files to ignore

elm.json     # the elm app config

index.html   # the app web page

src/Main.elm # the elm app

```



Now you simply need to compile the elm app and start a static server.

```sh

# Compile the elm app. This will create some new files.

npx elm-cardano make src/Main.elm --output main.js

# Start a static web server then open your browser

python -m http.server

```



That’s it you are ready to build a Cardano offchain frontend with Elm!

More examples are available in the `examples/` dir of the repo.

More information about this project is also available

in the different documents in the `docs/` dir of the repo.



## Contributions



Contributions are very welcomed! For now things are moving fast so I suggest

discussing first over [TxPipe discord][txpipe-discord], in the

[#elm][elm-cardano-channel] channel.



[txpipe-discord]: https://discord.gg/ZTHcHUy5HY

[elm-cardano-channel]: https://discord.com/channels/946071061567529010/1168602442657697793



The elm-cardano cli is built using the rust language.

To build successfully, it attempts to statically load the WASM files for Aiken UPLC virtual machine.

So we first need to download these files locally, then we can compile (in release).

```sh

# Download the uplc-wasm archive

curl -LO 'https://github.com/mpizenberg/uplc-wasm/releases/download/v0.2.0/my-artifact.zip'

unzip my-artifact.zip -d cli/pkg-uplc-wasm



# Build the elm-cardano cli

cargo build --release

```



Now you can put that `target/release/elm-cardano` binary somewhere in your path.

Or better, put a link to it somewhere in your path.

After doing that, we can install the elm tools.

The simplest way is via npm.

```sh

# Install all the tools:

# elm, elm-format, elm-test, elm-review, elm-watch

npm install

```



You can then run the tools you need by prefixing the command with `npx`.



```sh

# compile the elm package

npx elm make

# run the tests, using the elm-cardano binary for compilation

npx elm-test --compiler elm-cardano

# review the code

npx elm-review

# run the Tx builder example

cd examples/txbuild && npx elm-watch hot

```