Making RDKit minimallib (JS lib) available through the npm package manager (#4086)

* Npm publishing files - v1 in progress * refactor .gitignore and package.json * 2021.3.1-beta.0 * edit readme * 2021.3.1-beta.1 * first version of read me and small tweak to docker build * rdkit spelling uniform in readme * 2021.3.1-beta.2 * update TOC * add file to .gitignore * 2021.3.1-beta.3 * add additional comment * add back real readme * add release tag example * edit comment in git ignore * add a link to unpkg.com * 2021.3.1-beta.4 * final tweak to readme * 2021.3.1-beta.5 * fix typo * 2021.3.1-beta.6 * additional edits to README.md * 2021.3.1-beta.7 * last minor readme edit * 2021.3.1-beta.8 * add badges * 2021.3.1-beta.9 * point homepage to minimallib readme * 2021.3.1-beta.10 * 2021.3.1-beta.11 * make the js file the entry point * 2021.3.1-beta.12 * fix release without dist * 2021.3.1-beta.13 * add license badge to readme * 2021.3.1-beta.14 * apply all reviews getting started html file is now official demo use npm version with --no-git-tag-version use placeholder for version in npm package add new line in all files edit description and authors in package.json * update live demo to be the getting started page * add logging of version in readme example * apply new set of review fix author field for good add back demo.html edit readme accordingly edit dockerfile to include GettingStarted.html in dist * include proper getting started file in build * edit publish process based on new PLACEHOLDER version * update version in readme * update toc * add back placeholder * remove ugly readme warning
2026-06-03 21:44:30 +08:00 · 2021-04-29 02:24:23 -04:00
parent f4c7d341e7
commit 55b8ab9b76
8 changed files with 224 additions and 10 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -108,3 +108,8 @@ __pycache__/
 /rdkit/ML/Data/test_data/testgeneral.dat.pkl
 /rdkit/ML/Data/test_data/testquant.qdat.pkl
 .DS_Store
+
+# JS distribution or temp files
+Code/MinimalLib/dist
+MAIN_RDKIT_README*
+node_modules
--- a/Code/MinimalLib/README.md
+++ b/Code/MinimalLib/README.md
@@ -1,11 +1,143 @@
-# JavaScript wrappers for the RDKit
+# RDKit for JavaScript (Official)

-**Note** These wrappers should be considered experimental. The API is not yet stable and may change from release to release.
+[![Azure build Status](https://dev.azure.com/rdkit-builds/RDKit/_apis/build/status/rdkit.rdkit?branchName=master)](https://dev.azure.com/rdkit-builds/RDKit/_build/latest?definitionId=1&branchName=master)
+[![Documentation Status](https://readthedocs.org/projects/rdkit/badge/?version=latest)](https://unpkg.com/@rdkit/rdkit@v2021.3.1-release/Code/MinimalLib/dist/GettingStartedInJS.html)
+[![License](https://img.shields.io/github/license/rdkit/rdkit)](https://github.com/rdkit/rdkit/blob/master/license.txt)
+[![NPM Latest Version](https://img.shields.io/npm/v/@rdkit/rdkit)](https://www.npmjs.com/package/@rdkit/rdkit)
+[![NPM Weekly Downloads](https://img.shields.io/npm/dw/@rdkit/rdkit)](https://www.npmjs.com/package/@rdkit/rdkit)
+[![NPM Monthly Downloads](https://img.shields.io/npm/dm/@rdkit/rdkit)](https://www.npmjs.com/package/@rdkit/rdkit)
+[![NPM Yearly Downloads](https://img.shields.io/npm/dy/@rdkit/rdkit)](https://www.npmjs.com/package/@rdkit/rdkit)
+[![NPM Total Downloads](https://img.shields.io/npm/dt/@rdkit/rdkit?label=total%20downloads)](https://www.npmjs.com/package/@rdkit/rdkit)

-The idea here is to allow the RDKit to be used from JavaScript so that we can add chemical capabilities to web applications.
-Rather than attempting a comprehensive wrapper (like RDKitJS), this exposes a small set of key functionality. I think the general approach, including this actual library, can be useful for other wrapper projects in the future.
+## Table of contents
+
+  - [Introduction](#introduction)
+  - [Install](#install)
+  - [Using the RDKit package assets](#using-the-rdkit-package-assets)
+    - [Option 1: Use the npm package distribution files](#option-1-use-the-npm-package-distribution-files)
+    - [Option 2: Use the remote distribution files from unpkg.com](#option-2-use-the-remote-distribution-files-from-unpkgcom)
+  - [Running RDKit in your JavaScript code](#running-rdkit-in-your-javascript-code)
+  - [Usage](#usage)
+  - [Live demos](#live-demos)
+  - [Contributing](#contributing)
+    - [Preparing a new release of the package](#preparing-a-new-release-of-the-package)
+    - [Releasing a new beta version of the package](#releasing-a-new-beta-version-of-the-package)
+
+## Introduction
+
+**Note: This package should be considered experimental. The API is not yet stable and may change from release to release.**
+
+The idea of this package is to allow the [RDKit](https://github.com/rdkit/rdkit) to be used from JavaScript so that we can add chemical capabilities to web applications.  
+
+Rather than attempting a comprehensive wrapper (like the old [RDKitJS](https://github.com/rdkit/RDKitjs)), this exposes a small set of key functionality. I think the general approach, including this actual library, can be useful for other wrapper projects in the future.

 This initial set of functionality is not complete, but it is intended to already be directly useful.

-The `Dockerfile` in the `docker/` shows how to setup an appropriate environment and build the wrappers.
+## Install

+```bash
+npm i @rdkit/rdkit
+```  
+
+## Using the RDKit package assets
+
+### Option 1: Use the npm package distribution files
+
+Once you have the RDKit package installed in your node modules, copy the following distribution files anywhere in your deployed assets.
+
+- `node_modules/@rdkit/rdkit/CodeMinimalLib/dist/RDKit_minimal.js`
+- `node_modules/@rdkit/rdkit/CodeMinimalLib/dist/RDKit_minimal.wasm`
+
+**NOTE: Both files must be copied at the same location in your deployed assets for the library to work properly.**
+
+### Option 2: Use the remote distribution files from [unpkg.com](https://unpkg.com/)
+
+- `https://unpkg.com/@rdkit/rdkit@2021.3.1-beta.13/Code/MinimalLib/dist/RDKit_minimal.js`
+- `https://unpkg.com/@rdkit/rdkit@2021.3.1-beta.13/Code/MinimalLib/dist/RDKit_minimal.wasm`
+
+## Running RDKit in your JavaScript code
+
+To use RDKit, load the javascript file and instantiate the wasm module inside the `head` tag of your `index.html`, before you run your application code:
+
+```html
+<head>
+    <!-- ...other files and HTML tags... -->
+    <!-- Load the RDKit JS file -->
+    <script src="https://unpkg.com/@rdkit/rdkit@2021.3.1-beta.13/Code/MinimalLib/dist/RDKit_minimal.js"></script>
+    <!-- Instantiate the WASM module. The inline script below could live elsewhere inside your application code. -->
+    <script>
+        window.initRDKitModule()
+            .then(function(RDKit) {
+                console.log("RDKit version: " + RDKit.version());
+                window.RDKit = RDKit;
+                /**
+                 * The RDKit module is now loaded.
+                 * You can use it anywhere.
+                 */
+            })
+            .catch(() => {
+                // handle loading errors here...
+            });
+    </script>
+    <!-- ...your application code goes here... -->
+</head>
+
+```
+
+## Usage
+
+See the getting started demo at https://unpkg.com/@rdkit/rdkit@v2021.3.1-release/Code/MinimalLib/dist/GettingStartedInJS.html .
+
+Follow the examples of this page to see the various ways to use the JavaScript release of RDKit.
+
+## Live demos
+
+- From this npm package: https://unpkg.com/@rdkit/rdkit@v2021.3.1-release/Code/MinimalLib/dist/GettingStartedInJS.html
+- From this npm package: https://unpkg.com/@rdkit/rdkit@v2021.3.1-release/Code/MinimalLib/dist/demo.html
+
+## Contributing
+
+### Preparing a new release of the package
+
+Make sure you are at the root of the [RDKit](https://github.com/rdkit/rdkit) GitHub project, and on the branch and version of the project you want to release. **Note that no commits should occur during the release process.**
+
+#### Step 1: Set the release version in package.json
+
+```bash
+npm --no-git-tag-version version <semver version matching an RDKit release>
+# Example npm --no-git-tag-version version 2021.3.1
+```
+
+#### Step 2: Build the distribution files
+
+```bash
+npm run build -- <RDKit git release tag name>
+# Example: npm run build -- Release_2021_03_1
+```
+
+This command will default to using the `master` branch if no version is provided. Also, checkout the `build_rdkitjs.sh` file and the minimallib `Dockerfile` to see how things are tied together.
+
+#### Step 3: Publish the package to npm
+
+Once you have verified that the distribution files have been properly added in `Code/MinimalLib/dist`, publish the package:
+
+```bash
+npm publish --access public
+```  
+
+#### Step 4: Set back the placeholder version in package.json
+
+```bash
+npm run resetVersion
+```
+
+And you're done!
+
+### Releasing a new beta version of the package
+
+The process is the same as publishing a regular version, but the version specified and the npm publish command change slightly:
+
+```bash
+npm --no-git-tag-version version 2021.3.1-beta.0 # specify beta number in version here
+npm publish --beta --access public # specify npm that it's a beta version
+```
--- a/Code/MinimalLib/demo/demo.html
+++ b/Code/MinimalLib/demo/demo.html
@@ -184,4 +184,4 @@

 </body>

-</html>
+</html>
--- a/Code/MinimalLib/docker/Dockerfile
+++ b/Code/MinimalLib/docker/Dockerfile
@@ -1,5 +1,5 @@
-FROM debian:buster
-MAINTAINER Greg Landrum <greg.landrum@t5informatics.com>
+FROM debian:buster as build-stage
+LABEL maintainer="Greg Landrum <greg.landrum@t5informatics.com>"

 RUN apt-get update && apt-get upgrade -y && apt install -y \
  curl \
@@ -34,10 +34,11 @@ RUN ./emsdk update-tags && \
 RUN mkdir /src
 WORKDIR /src
 ENV RDBASE=/src/rdkit
-ARG RDKIT_BRANCH=master
+ARG RDKIT_BRANCH=${RDKIT_BRANCH:-master}
 RUN git clone https://github.com/rdkit/rdkit.git
 WORKDIR $RDBASE
-RUN git checkout $RDKIT_BRANCH
+RUN git fetch --all --tags && \
+  git checkout $RDKIT_BRANCH

 RUN mkdir build
 WORKDIR build
@@ -65,3 +66,10 @@ RUN make -j2 RDKit_minimal && \
 # run the tests
 WORKDIR /src/rdkit/Code/MinimalLib/tests
 RUN nodejs tests.js
+
+# Copy js and wasm rdkit files to use in browser
+# This feature requires the BuildKit backend
+# https://docs.docker.com/engine/reference/commandline/build/#custom-build-outputs
+FROM scratch as export-stage
+COPY --from=build-stage /src/rdkit/Code/MinimalLib/demo /
+COPY --from=build-stage /src/rdkit/Code/MinimalLib/docs /
--- a/Code/MinimalLib/scripts/build_rdkitjs.sh
+++ b/Code/MinimalLib/scripts/build_rdkitjs.sh
@@ -0,0 +1,19 @@
+set -e
+
+# Clean and create distribution folder
+MINIMALLIB_OUTPUT_PATH="Code/MinimalLib/dist"
+rm -rf $MINIMALLIB_OUTPUT_PATH
+mkdir -p $MINIMALLIB_OUTPUT_PATH
+
+# Build distribution files
+RDKIT_BRANCH=${1:-master}
+echo "Building distribution files for release $RDKIT_BRANCH"
+DOCKER_BUILDKIT=1 docker build --no-cache -f Code/MinimalLib/docker/Dockerfile --build-arg RDKIT_BRANCH=$RDKIT_BRANCH -o $MINIMALLIB_OUTPUT_PATH .
+
+# Make files executable
+chmod a+rwx $MINIMALLIB_OUTPUT_PATH/RDKit_minimal.js
+chmod a+rwx $MINIMALLIB_OUTPUT_PATH/RDKit_minimal.wasm
+
+# Log build completed
+echo "Build completed"
+echo "MinimalLib distribution files are at $MINIMALLIB_OUTPUT_PATH"
--- a/Code/MinimalLib/scripts/npm_postpublish.sh
+++ b/Code/MinimalLib/scripts/npm_postpublish.sh
@@ -0,0 +1,4 @@
+# NOTE: this script goes along with the npm_prepublish.sh script
+rm README.md # rm temp minimallib README
+mv MAIN_RDKIT_README.md README.md
+mv MAIN_RDKIT_README README
--- a/Code/MinimalLib/scripts/npm_prepublish.sh
+++ b/Code/MinimalLib/scripts/npm_prepublish.sh
@@ -0,0 +1,6 @@
+# include minimallib readme during npm publish process
+# not main RDKit readme
+# NOTE: this script goes along with the npm_postpublish.sh script
+mv README.md MAIN_RDKIT_README.md
+mv README MAIN_RDKIT_README
+cp Code/MinimalLib/README.md README.md
--- a/package.json
+++ b/package.json
@@ -0,0 +1,40 @@
+{
+  "name": "@rdkit/rdkit",
+  "version": "PLACEHOLDER",
+  "description": "JavaScript distribution of cheminformatics functionality from the RDKit - a C++ library for cheminformatics.",
+  "main": "Code/MinimalLib/dist/RDKit_minimal.js",
+  "scripts": {
+    "build": "bash Code/MinimalLib/scripts/build_rdkitjs.sh",
+    "prepublish": "bash Code/MinimalLib/scripts/npm_prepublish.sh",
+    "postpublish": "bash Code/MinimalLib/scripts/npm_postpublish.sh",
+    "resetVersion": "jq '.version = \"PLACEHOLDER\"' package.json > temp && mv temp package.json",
+    "test": "echo \"Tests are run during the docker build. See https://github.com/rdkit/rdkit/blob/master/Code/MinimalLib/docker/Dockerfile .\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rdkit/rdkit.git"
+  },
+  "keywords": [
+    "javascript",
+    "c-plus-plus",
+    "cheminformatics",
+    "rdkit",
+    "wasm"
+  ],
+  "author": "Greg Landrum and the RDKit contributors",
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/rdkit/rdkit/issues"
+  },
+  "homepage": "https://github.com/rdkit/rdkit/blob/master/Code/MinimalLib/README.md",
+  "files": [
+    "license.txt",
+    "package.json",
+    "ReleaseNotes.md",
+    "README.md",
+    "Code/MinimalLib/dist/demo.html",
+    "Code/MinimalLib/dist/GettingStartedInJS.html",
+    "Code/MinimalLib/dist/RDKit_minimal.js",
+    "Code/MinimalLib/dist/RDKit_minimal.wasm"
+  ]
+}