diff --git a/packages/@jsonql/koa/package.json b/packages/@jsonql/koa/package.json
index b235f8936201ab025b4ca840333ccffe05761bf3..05a56909d1442816077cb64f1f05d16ffac2c617 100644
--- a/packages/@jsonql/koa/package.json
+++ b/packages/@jsonql/koa/package.json
@@ -49,8 +49,8 @@
   "dependencies": {
     "debug": "^4.1.1",
     "fs-extra": "^8.1.0",
-    "jsonql-constants": "^1.8.9",
-    "jsonql-koa": "^1.4.3",
+    "jsonql-constants": "^1.8.10",
+    "jsonql-koa": "^1.4.4",
     "jsonql-params-validator": "^1.4.11",
     "koa": "^2.11.0",
     "koa-bodyparser": "^4.2.1",
@@ -58,7 +58,7 @@
     "yargs": "^14.2.0"
   },
   "optionalDependencies": {
-    "jsonql-ws-server": "^1.3.6"
+    "jsonql-ws-server": "^1.4.0"
   },
   "bin": {
     "jsonql-koa-cli": "./cli.js"
diff --git a/packages/koa/index.js b/packages/koa/index.js
index 494992ecb96c89c69a417e758ab851ded6a845bf..99e4751d8e9365a4323f2c1051a8ce9a5013de0c 100644
--- a/packages/koa/index.js
+++ b/packages/koa/index.js
@@ -14,11 +14,11 @@ import {
   publicMethodMiddleware,
   initMiddleware
 }  from './src/middlewares'
-import { configCheck } from './src/options'
+import { configCheck, preConfigCheck } from './src/options'
 import { getDebug }  from './src/utils'
 const debug = getDebug('main')
 // main
-export function jsonqlKoa(config = {}) {
+function jsonqlKoa(config = {}) {
   // first check the config
   const opts = configCheck(config)
   debug('[jsonql-koa] init opts', opts)
@@ -46,12 +46,5 @@ export function jsonqlKoa(config = {}) {
   return compose(middlewares)
 }
 
-/**
- * We export an extra interface to the config check because when we hook up the
- * ws server, there is a problem with waiting for the contract
- * @param {object} config configuration
- * @return {object} checked configuration
- */
-export function preConfigCheck(config) {
-  return configCheck(config)
-}
+// export these two now
+export { jsonqlKoa, preConfigCheck }
diff --git a/packages/koa/package.json b/packages/koa/package.json
index 395a750be896e780871c6956fd9fecc46963a2e1..24dbe4a9f72c06caac0eaaf2c6319c9835297aca 100644
--- a/packages/koa/package.json
+++ b/packages/koa/package.json
@@ -1,6 +1,6 @@
 {
   "name": "jsonql-koa",
-  "version": "1.4.4",
+  "version": "1.4.5",
   "description": "jsonql Koa middleware",
   "main": "main.js",
   "module": "index.js",
diff --git a/packages/koa/src/options/index.js b/packages/koa/src/options/index.js
index 41aeea7c3b6abf0241af4f576be0eab047072adb..cacb9620a741b5a7f124bd6fad38ae6220400b6a 100644
--- a/packages/koa/src/options/index.js
+++ b/packages/koa/src/options/index.js
@@ -87,3 +87,20 @@ export function configCheck(config = {}) {
   // return opts;
   return injectToFn(opts, CHECKED_KEY, now)
 }
+
+/**
+ * new methods for when using it combine with the jsonql-ws-server
+ * @param {object} wsDefaultOptions from the other config
+ * @param {object} wsConstProps from the other config
+ * @param {object} config supply by the user
+ */
+export function preConfigCheck(wsDefaultOptions, wsConstProps, config = {}) {
+  const _defaultOptions = _.merge({}, appProps, wsDefaultOptions)
+  const _constProps = _.merge({}, wsConstProps, constProps)
+  const now = Date.now()
+
+  const fn = chainFns(checkConfig, applyGetContract, applyAuthOptions)
+  const opts = fn(config, _defaultOptions, _constProps)
+  // return opts;
+  return injectToFn(opts, CHECKED_KEY, now)
+}
diff --git a/packages/koa/tests/config.test.js b/packages/koa/tests/config.test.js
index 35bec24dcdda35ca77219ccc3bdfece27d704342..6dea537dfcb6b0e1aee8cc989753cd91d9e06a24 100644
--- a/packages/koa/tests/config.test.js
+++ b/packages/koa/tests/config.test.js
@@ -56,7 +56,7 @@ test('It should have privateKey and publicKey when set useJwt = true', async t =
 })
 
 test(`It should now have an extra property __checked__`, t => {
-  const opts = preConfigCheck()
+  const opts = preConfigCheck({}, {})
   debug(opts[CHECKED_KEY])
   t.truthy(opts[CHECKED_KEY])
 })
diff --git a/packages/ws-server/README.md b/packages/ws-server/README.md
index ff6b9b4cc8d01ec325b1af69baf55c28ca466e8a..cb88b651816435356247c5a5bca56f5d0b11f1e6 100644
--- a/packages/ws-server/README.md
+++ b/packages/ws-server/README.md
@@ -6,12 +6,35 @@ This is not mean to use as standalone server (although you can)
 
 This is included as optional dependencies as one of the following module:
 
-- [@jsonql/koa](https://npmjs.com/package/@jsonql/koa) complete Node server side setup with Koa 
+- [@jsonql/koa](https://npmjs.com/package/@jsonql/koa) complete Node server side setup with Koa
 - @jsonql/express (in development)
 
 Please check our main documentation site at [jsonql.org](https://jsonql.js.org)
 for further information
 
+## Note
+
+The module can work as a standalone WebSocket server.
+
+```js
+const http = require('http')
+const fsx = require('fs-extra')
+const { jsonqlWsServer } = require('jsonql-ws-server')
+const server = http.createServer()
+// when using this as standalone, you need to include the contract from somewhere
+const config = {
+  contract: fsx.readJsonSync('path/to/public.json')
+}
+// init
+jsonqlWsServer(config, server)
+  .then(() => {
+    // start up the server
+    server.listen(PORT)
+  })
+```
+
+But this is not recommended.
+
 ---
 
 [NEWBRAN LTD UK](https://newbran.ch)
diff --git a/packages/ws-server/index.js b/packages/ws-server/index.js
index 794fb0e50252d3ff21941fadb9a77f760202cf7f..d94ffa4319240cb16b87587daf70ccc1395db257 100644
--- a/packages/ws-server/index.js
+++ b/packages/ws-server/index.js
@@ -1,6 +1,12 @@
 // Not going to use the koa-socket-2 due to it's lack of support namespace
 // which is completely useless for us if there is no namespace
-const { checkOptions, wsSetup, wsCreateServer } = require('./src')
+const {
+  checkConfig,
+  wsServerDefaultOptions,
+  wsServerConstProps,
+  wsSetup,
+  wsCreateServer
+} = require('./src')
 const { getDebug } = require('./src/share/helpers')
 const { JsonqlError } = require('jsonql-errors')
 const debug = getDebug('main')
@@ -13,9 +19,9 @@ const debug = getDebug('main')
  * @param {object} config.server this is the http/s server that required to bind to the socket to run on the same connection
  * @return {mixed} return the undelying socket server instance for further use
  */
-module.exports = function jsonqlWsServer(config, server) {
+function jsonqlWsServer(config, server) {
   // @TODO check the options
-  return checkOptions(config)
+  return checkConfig(config)
     .then(opts => {
       const nspObj = wsCreateServer(opts, server)
       return Reflect.apply(wsSetup, null, [opts, nspObj])
@@ -25,3 +31,6 @@ module.exports = function jsonqlWsServer(config, server) {
       throw new JsonqlError('jsonqlWsServer', err)
     })
 }
+
+// breaking change we export it as a name module
+module.exports = { jsonqlWsServer, wsServerDefaultOptions, wsServerConstProps }
diff --git a/packages/ws-server/package.json b/packages/ws-server/package.json
index f9aab9d21868aceafd30738b03997d7f3f86dc46..a8a3e322f5c29bc34d0d1996e3c23a438dd3408b 100755
--- a/packages/ws-server/package.json
+++ b/packages/ws-server/package.json
@@ -1,6 +1,6 @@
 {
   "name": "jsonql-ws-server",
-  "version": "1.3.6",
+  "version": "1.4.0",
   "description": "Setup WebSocket server for the jsonql to run on the same host, automatic generate public / private channel using contract",
   "main": "index.js",
   "files": [
@@ -32,18 +32,18 @@
     "debug": "^4.1.1",
     "esm": "^3.2.25",
     "fs-extra": "^8.1.0",
-    "jsonql-constants": "^1.8.9",
-    "jsonql-errors": "^1.1.3",
+    "jsonql-constants": "^1.8.10",
+    "jsonql-errors": "^1.1.5",
     "jsonql-jwt": "^1.3.3",
     "jsonql-params-validator": "^1.4.11",
     "jsonql-resolver": "^0.9.4",
-    "jsonql-utils": "^0.8.1",
+    "jsonql-utils": "^0.8.3",
     "lodash": "^4.17.15",
     "ws": "^7.2.0"
   },
   "devDependencies": {
     "ava": "^2.4.0",
-    "jsonql-contract": "^1.7.21",
+    "jsonql-contract": "^1.8.4",
     "open": "^7.0.0"
   },
   "ava": {
diff --git a/packages/ws-server/src/index.js b/packages/ws-server/src/index.js
index baf1739a99d0676ddc3e276f3a495dbaeef0d7e5..142ea0b70b949c7099cd944b8cebc8e8acff5189 100644
--- a/packages/ws-server/src/index.js
+++ b/packages/ws-server/src/index.js
@@ -1,10 +1,14 @@
 // re-export here
 const { wsSetup, wsCreateServer } = require('./core')
-const checkOptions = require('./check-options')
+const { checkConfig, defaultOptions, constProps } = require('./options')
 
 // re-export
 module.exports = {
-  checkOptions,
+  // rename them
+  wsServerDefaultOptions: defaultOptions,
+  wsServerConstProps: constProps,
+  // rest of the exports
+  checkConfig,
   wsSetup,
   wsCreateServer
 }
diff --git a/packages/ws-server/src/check-options/index.js b/packages/ws-server/src/options/index.js
similarity index 91%
rename from packages/ws-server/src/check-options/index.js
rename to packages/ws-server/src/options/index.js
index f7c4af83a8df52b10d89eb14899ece10e73e7a30..8f1a6fe3967ce2adbe4cf7c41d1d903af38f817b 100644
--- a/packages/ws-server/src/check-options/index.js
+++ b/packages/ws-server/src/options/index.js
@@ -72,14 +72,15 @@ const constProps = {
   privateKey: false,
   secret: false,
   publicNamespace: PUBLIC_KEY,
-  privateNamespace: PRIVATE_KEY
+  privateNamespace: PRIVATE_KEY,
+  initContract: false // this is from the koa middleware
 }
 
 /**
  * @param {object} config user supply
  * @return {object} promise resolve the opts
  */
-module.exports = function(config) {
+function checkConfig(config) {
   return checkConfigAsync(config, defaultOptions, constProps)
     .then(getContract)
     // processing the key
@@ -97,3 +98,7 @@ module.exports = function(config) {
       return opts;
     })
 }
+
+// breaking change export as name also the options for merge with the upstream server
+
+module.exports = { checkConfig, defaultOptions, constProps }
diff --git a/packages/ws-server/src/share/get-contract.js b/packages/ws-server/src/share/get-contract.js
index 6d34396fd494449eae6091c446e94f71f501e834..b607ac27f7e8f994dc1f01b1b42dde09f563483d 100644
--- a/packages/ws-server/src/share/get-contract.js
+++ b/packages/ws-server/src/share/get-contract.js
@@ -34,6 +34,11 @@ function getContractFromFile(config) {
   return new Promise((resolver, rejecter) => {
     c = readContract(contractDir)
     if (!c) {
+      if (config.initContract && config.initContract.then) {
+        // this is a pending promise
+        return config.initContract.then(resolver)
+      }
+      /* the last fallback */
       setTimeout(() => {
         c = readContract(contractDir)
         if (c) {
diff --git a/packages/ws-server/tests/fixtures/browser-test-setup.js b/packages/ws-server/tests/fixtures/browser-test-setup.js
index bdf92d6cff7181daef191f98a804a7e43b66a8e8..62c1eca0e87e31cf626e489785f181c6f677efac 100644
--- a/packages/ws-server/tests/fixtures/browser-test-setup.js
+++ b/packages/ws-server/tests/fixtures/browser-test-setup.js
@@ -19,9 +19,9 @@ console.log(app['jsonql'].onConnection)
 default_io.on('chat message', function(msg){
   console.info('got a message', msg);
   if (msg === 'terminate') {
-    clearTimeout(timer);
+    clearTimeout(timer)
   }
-  default_io.emit('chat message', msg);
+  default_io.emit('chat message', msg)
 })
 
 // hijack the connnection for all channels
diff --git a/packages/ws-server/tests/fixtures/full-setup.js b/packages/ws-server/tests/fixtures/full-setup.js
index efb15c7ccda63805619a088b80413b89f0b2b340..e3dc0121b10e4d6ccb4343dad512788523d5e05e 100644
--- a/packages/ws-server/tests/fixtures/full-setup.js
+++ b/packages/ws-server/tests/fixtures/full-setup.js
@@ -5,7 +5,7 @@ const { getDebug } = require('../../lib/share/helpers')
 const debug = getDebug('test:full-setup')
 const resolverDir = join(__dirname, 'resolvers')
 
-const wsServer = require('../../index')
+const { jsonqlWsServer } = require('../../index')
 const http = require('http')
 
 // start
@@ -22,7 +22,7 @@ module.exports = function(_config = {}) {
   }
   const opts = Object.assign(config, _config)
   return new Promise(resolver => {
-    wsServer(opts, server)
+    jsonqlWsServer(opts, server)
       .then(io => {
         debug('socket setup completed')
         resolver({
diff --git a/packages/ws-server/tests/fixtures/server.js b/packages/ws-server/tests/fixtures/server.js
index 28997b958f06b7e42b8f519e64c4422e57781eb1..1e253252ca21b29ac0c74e0716f8827f10604d34 100644
--- a/packages/ws-server/tests/fixtures/server.js
+++ b/packages/ws-server/tests/fixtures/server.js
@@ -8,7 +8,7 @@ const { JSONQL_PATH } = require('jsonql-constants')
 const resolverDir = join(__dirname, 'resolvers')
 const contractDir = join(__dirname, 'contract')
 
-const wsServer = require('../../index')
+const { jsonqlWsServer } = require('../../index')
 
 // start
 const server = http.createServer(function(req, res) {
@@ -20,7 +20,7 @@ const server = http.createServer(function(req, res) {
 module.exports = function(extra = {}) {
   // extra.contract = extra.contract || contract;
   return new Promise(resolver => {
-    wsServer(
+    jsonqlWsServer(
       Object.assign({
         resolverDir,
         contractDir,