[NOTE]

December 9, 2021 · View on GitHub

= https://github.com/input-output-hk/web-common[Common web development library] :email: plutus@iohk.io :author: Input Output HK Limited :toc: left :reproducible:

This library is a collection of helpers used by various web apps in the Plutus and Marlowe ecosystem.

== Working with the project

=== How to submit an issue

Issues can be filed in the https://github.com/input-output-hk/web-common/issues[GitHub Issue tracker].

[[how-to-develop]] === How to develop and contribute to the project

See link:CONTRIBUTING{outfilesuffix}[CONTRIBUTING], which describes our processes in more detail including development environments;

=== How to depend on the project from another PureScript project

This repo contains IO Global's standard psc package set. It extends the latest package set from psc-package and adds a few of our own packages to the set (inluding web-common its self). In your project's packages.dhall, you can set this project's package set as your upstream package set, and override or add additional packages if you need to:

let upstream = https://github.com/input-output-hk/purescript-web-common/releases/download/v1.0.0/packages.dhall

You will then be able to install any package on the latest psc-package set, as well as json-helpers, servant-support, web-common, and markdown via spago install.

=== How to override this dependency locally

If you are working on web-common locally, and want to test out your changes in a project, you can override the package locally using spago, which makes local development much more convenient. In your project's packages.dhall, simply add the following to your upstream declaration:

-- This assumes you have this repo cloned in a sibling directory to -- the one that contains your PureScript project's packages.dhall file.

let upstream = https://github.com/input-output-hk/purescript-web-common/releases/download/v1.0.0/packages.dhall with web-common = ../purescript-web-common/spago.dhall as Location

=== How to depend on this project from another NPM project

You can install this project as a NPM dependency with.

npm install --save-dev @input-output-hk/web-common

This is necessary if you want to use the CSS, HTML, or JavaScript dependencies bundled in this project.

=== How to publish a new release of the library After merging the different pull requests that makes a release you need to figure the next version number of the library using semantic versioning. In the main branch, an administrator of this repository needs to:

  1. Update the web-common addition in the package.dhall to use the next version number.
  2. Commit the changes
  3. Run npm version <major | minor | patch> which will create a new commit with the version bumped in package.json and a new tag for that version
  4. Push the commits and tags with git push && git push --tags
  5. Create a new release in GitHub for the new tag. Add packages.dhall to the new release as an attachment
  6. Update the package.dhall of referencing projects.

=== How to use the shared webpack config

This project includes a standard WebPack config that can be customized to fit your projects needs. First, you need to install the NPM package:

npm install --save-dev @input-output-hk/web-common

Then, in your project's webpack.config.js, you can use it as follows:

const path = require("path"); const { webpackConfig, purescriptRule } = require("purescript-web-common");

// extra source folders your project uses. test, src, .spago, and generated are // automatically included. const pursSources = [ "web-common-plutus/src//*.purs", "web-common-playground/src//*.purs", ];

const dist = path.join(__dirname, "dist");

module.exports = webpackConfig((env /* will be "development" or "production) => { // Return a webpack config object. This will be merged with the standard // config. return { entry: "./entry.js", output: { path: dist }, module: { // You can include more rules here. Note that rules with the // matching "test" properties will override the same rules defined by // webpackConfig. rules: [ purescriptRule(env, pursSources), ], }, plugins: [ // You can add plugins here. Note that plugins listed here will // override the same plugins defined by webpackConfig. ], }; });

The standard config includes the following settings:

{ output: { filename: "[name].[contenthash].js", pathinfo: true, }, optimization: { runtimeChunk: "single", splitChunks: { cacheGroups: { vendor: { test: /[\/]node_modules[\/]/, name: "vendors", chunks: "all", }, }, }, }, module: { rules: [ { test: /.tsx?/, loader: "ts-loader", }, { test: /\.css/, use: [MiniCssExtractPlugin.loader, "css-loader", "postcss-loader"], }, { test: /.(png|svg|jpg|jpeg|gif|woff|woff2|eot|ttf|otf)$/i, type: "asset/resource", }, ], }, plugins: [ new MiniCssExtractPlugin({ filename: "[name]-[chunkhash].css", chunkFilename: "[id].css", }), ], resolve: { modules: ["node_modules"], extensions: [".purs", ".js", ".ts", ".tsx"], }, resolveLoader: { modules: ["node_modules"], }, stats: { children: false, }, }

In development mode, the following settings are applied:

{ mode: "development", devtool: "eval-cheap-source-map", devServer: { compress: true, port: 8009, stats: "errors-warnings", }, }

While in production, the following settings are applied:

class ErrorReportingPlugin { apply(compiler) { compiler.hooks.done.tap("ErrorReportingPlugin", (stats) => process.stderr.write(stats.toString("errors-only")) ); } }

{ mode: "production", devtool: false, plugins: [new ErrorReportingPlugin()], }

Notice that this configuration includes postcss, which means that you need to create a postcss.config.js file in the root of your project, even if it is a stub config.

[[prerequisites]] ==== Prerequisites

You can build the project either with Nix using the provided nix-shell (recommended) or by installing PureScript and spago.

===== Nix

Install https://nixos.org/nix/[Nix] (recommended). following the instructions on the https://nixos.org/nix/[Nix website].

See <> for further advice on using Nix.

The project is built using nix-build (or nix build if you are a flakes user).

From the project root directory, you can also run nix-shell (or nix develop if you use flakes) to drop into a development shell with all necessary tooling installed. Additionally, Lorri is supported if you are a Lorri user.

===== Non-Nix

You can build some of the Haskell packages without Nix, but this is not recommended and we don't guarantee that these prerequisites are sufficient. If you use Nix, these tools are provided for you via shell.nix, and you do not need to install them yourself.

  • You can install PureScript and Spago using npm or yarn (npm i -g purescript spago or yarn gliobal add purescript spago)

You can build the project with spago build.

[[nix-advice]] == Nix

[[iohk-binary-cache]] === How to set up the IOHK binary caches

Adding the IOHK binary cache to your Nix configuration will speed up builds a lot, since many things will have been built already by our CI.

If you find you are building packages that are not defined in this repository, or if the build seems to take a very long time then you may not have this set up properly.

To set up the cache:

. On non-NixOS, edit /etc/nix/nix.conf and add the following lines: +

substituters = https://hydra.iohk.io https://iohk.cachix.org https://cache.nixos.org/ trusted-public-keys = hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= iohk.cachix.org-1:DpRUyj7h7V830dp/i6Nti+NEO2/nhblbov/8MW7Rqoo= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=

[NOTE]

If you don't have an /etc/nix/nix.conf or don't want to edit it, you may add the nix.conf lines to ~/.config/nix/nix.conf instead. You must be a https://nixos.org/nix/manual/#ssec-multi-user[trusted user] to do this.

. On NixOS, set the following NixOS options: +

nix = { binaryCaches = [ "https://hydra.iohk.io" "https://iohk.cachix.org" ]; binaryCachePublicKeys = [ "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ=" "iohk.cachix.org-1:DpRUyj7h7V830dp/i6Nti+NEO2/nhblbov/8MW7Rqoo=" ]; };

=== Nix on macOS

Nix on macOS can be a bit tricky. In particular, sandboxing is disabled by default, which can lead to strange failures.

These days it should be safe to turn on sandboxing on macOS with a few exceptions. Consider setting the following Nix settings, in the same way as in xref:iohk-binary-cache[previous section]:

sandbox = true extra-sandbox-paths = /System/Library/Frameworks /System/Library/PrivateFrameworks /usr/lib /private/tmp /private/var/tmp /usr/bin/env

[[nix-build-attributes]] === Which attributes to use to build different artifacts

link:./default.nix[default.nix] defines a package set with attributes for all the artifacts you can build from this repository. These can be built using nix build. For example:

nix build -f default.nix docs.site

.Example attributes

  • Project packages: defined inside marlowe.haskell.packages ** e.g. marlowe.haskell.packages.marlowe.components.library

There are other attributes defined in link:./default.nix[default.nix].

== Licensing

You are free to copy, modify, and distribute Marlowe under the terms of the Apache 2.0 license. See the link:./LICENSE[LICENSE] and link:./NOTICE[NOTICE] files for details.