diff --git a/javascript/README.md b/javascript/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..5c2c96b2ec78bbc71cd9bcc44538a1c2dffb6e01
--- /dev/null
+++ b/javascript/README.md
@@ -0,0 +1,25 @@
+Olm
+===
+
+Example:
+
+    var alice = new Olm.Account();
+    var bob = new Olm.Account();
+    alice.create();
+    bob.create();
+    bob.generate_one_time_keys(1);
+
+    var bobs_id_keys = JSON.parse(bob.identity_keys());
+    var bobs_id_key = bobs_id_keys.curve25519;
+    var bobs_ot_keys = JSON.parse(bob.one_time_keys());
+    for (key in bobs_ot_keys.curve25519) {
+        var bobs_ot_key = bobs_ot_keys.curve25519[key];
+    }
+
+    alice_session = new Olm.Session();
+    alice_session.create_outbound(alice, bobs_id_key, bobs_ot_key);
+    alice_message = a_session.encrypt("Hello");
+
+    bob_session.create_inbound(bob, bob_message);
+    var plaintext = bob_session.decrypt(message_1.type, bob_message);
+    bob.remove_one_time_keys(bob_session);
diff --git a/javascript/package.json b/javascript/package.json
new file mode 100644
index 0000000000000000000000000000000000000000..efcdaa5a733abe12515fda9c55b3d0dbbc2d949a
--- /dev/null
+++ b/javascript/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "olm",
+  "version": "0.1.0",
+  "description": "An implementation of a well known cryptographic ratchet",
+  "main": "olm.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/matrix-org/olm.git"
+  },
+  "keywords": [
+    "matrix-org"
+  ],
+  "author": "matrix.org",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/matrix-org/olm/issues"
+  },
+  "homepage": "https://github.com/matrix-org/olm#readme"
+}