Merge pull request #867 from dannyrb/docs/monorepo-updates-3

docs: monorepo updates

README.md

@@ -29,7 +29,7 @@
 [![All Contributors](https://img.shields.io/badge/all_contributors-10-orange.svg?style=flat-square)](#contributors)
 <!-- prettier-ignore-end -->
 
-## What?
+## About
 
 The OHIF Medical Imaging Viewer is for viewing medical images. It can retrieve
 and load images from most sources and formats; render sets in 2D, 3D, and
@@ -216,11 +216,11 @@ more about it in our [Architecture Documentation][ohif-architecture].
 These projects comprise the
 
 | Name                            | Description                                                                                          | Links             |
-| ------------------------------- | ----------- | ----- |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------- |
-| [@ohif/core][platform-core]     |             | NPM   |
+| [@ohif/core][platform-core]     | Business logic and classes that model the data, services, and extensions that are framework agnostic | [NPM][core-npm]   |
-| [@ohif/i18n][platform-i18n]     |             | NPM   |
+| [@ohif/i18n][platform-i18n]     | Language files and small API for wrapping component/ui text for translations                         | [NPM][i18n-npm]   |
-| [@ohif/viewer][platform-viewer] |             | NPM   |
+| [@ohif/viewer][platform-viewer] | The OHIF Viewer. Where we consume and configure all platform library's and extensions                | [NPM][viewer-npm] |
-| [@ohif/ui][platform-ui]         |             | NPM   |
+| [@ohif/ui][platform-ui]         | Reusable React components we consume and compose to build our Viewer's UI                            | [NPM][ui-npm]     |
 
 ### Extensions
 
@@ -229,12 +229,12 @@ customize and configure these extensions, and you can even create your own. You
 can [read more about extensions here][ohif-extensions].
 
 | Name                                                           | Description                                             | Links                  |
-| -------------------------------------------------------------- | ----------- | ----- |
+| -------------------------------------------------------------- | ------------------------------------------------------- | ---------------------- |
-| [@ohif/extension-cornestone][extension-cornerstone]            |             | NPM   |
+| [@ohif/extension-cornestone][extension-cornerstone]            | 2D image viewing, annotation, and segementation tools   | [NPM][cornerstone-npm] |
-| [@ohif/extension-dicom-html][extension-dicom-html]             |             | NPM   |
+| [@ohif/extension-dicom-html][extension-dicom-html]             | Support for viewing DICOM SR as rendered HTML           | [NPM][html-npm]        |
-| [@ohif/extension-dicom-microscopy][extension-dicom-microscopy] |             | NPM   |
+| [@ohif/extension-dicom-microscopy][extension-dicom-microscopy] | Whole slide microscopy viewing                          | [NPM][microscopy-npm]  |
-| [@ohif/extension-dicom-pdf][extension-dicom-pdf]               |             | NPM   |
+| [@ohif/extension-dicom-pdf][extension-dicom-pdf]               | View DICOM wrapped PDFs in a viewport                   | [NPM][pdf-npm]         |
-| [@ohif/extension-vtk][extension-vtk]                           |             | NPM   |
+| [@ohif/extension-vtk][extension-vtk]                           | Volume rendering, reconstruction, and 3D visualizations | [NPM][vtk-npm]         |
 
 ## Acknowledgments
 
@@ -304,13 +304,22 @@ MIT © [OHIF](https://github.com/OHIF)
 [extensions-url]: https://docs.ohif.org/advanced/extensions.html
 <!-- Platform -->
 [platform-core]: platform/core/README.md
+[core-npm]: https://www.npmjs.com/package/@ohif/core
 [platform-i18n]: platform/i18n/README.md
+[i18n-npm]: https://www.npmjs.com/package/@ohif/i18n
 [platform-ui]: platform/ui/README.md
+[ui-npm]: https://www.npmjs.com/package/@ohif/ui
 [platform-viewer]: platform/viewer/README.md
+[viewer-npm]: https://www.npmjs.com/package/@ohif/viewer
 <!-- Extensions -->
 [extension-cornerstone]: extensions/cornerstone/README.md
+[cornerstone-npm]: https://www.npmjs.com/package/@ohif/extension-cornerstone
 [extension-dicom-html]: extensions/dicom-html/README.md
+[html-npm]: https://www.npmjs.com/package/@ohif/extension-dicom-html
 [extension-dicom-microscopy]: extensions/dicom-microscopy/README.md
+[microscopy-npm]: https://www.npmjs.com/package/@ohif/extension-dicom-microscopy
 [extension-dicom-pdf]: extensions/dicom-pdf/README.md
+[pdf-npm]: https://www.npmjs.com/package/@ohif/extension-dicom-pdf
 [extension-vtk]: extensions/vtk/README.md
+[vtk-npm]: https://www.npmjs.com/package/@ohif/extension-vtk
 <!-- prettier-ignore-end -->

docs/latest/README.md

@@ -1,7 +1,7 @@
 <div class='row'>
 	<div class='column' style='text-align: right; padding: 0 20px'>
-		<strong>Looking for a Deploy Preview?</strong>
+		<strong>Looking for a Live Demo?</strong>
-		<a onclick="function redirect() { window.location.href='/demo/'; } redirect();">Deploy Preview for Viewer</a>
+		<a href="http://viewer.ohif.org/">Preview The OHIF Viewer</a>
 	</div>
 	<div class='column' style='text-align: left; padding: 0 20px'>
 		<a href="https://www.netlify.com">
@@ -33,7 +33,7 @@ yourself unable to extend the viewer for your purposes, please reach out via our
 [GitHub issues][gh-issues]. We are actively seeking feedback on ways to improve
 our integration and extension points.
 
-## Where to Next?
+## Where to next?
 
 Check out these helpful links:
 

docs/latest/essentials/data-source.md

@@ -35,10 +35,10 @@ For our purposes, we will be using `Orthanc`, but you can see a list of
 _Not sure if you have `docker` installed already? Try running `docker --version`
 in command prompt or terminal_
 
-> If you are using `Docker Toolbox` you need to change the _proxy_ parameter in
+> If you are using `Docker Toolbox` you need to change the _PROXY_DOMAIN_
-> _package.json_ to http://192.168.99.100:8042 or the ip docker-machine ip
+> parameter in _platform/viewer/package.json_ to http://192.168.99.100:8042 or
-> throws. This is the value [`react-scripts`][react-proxy] uses to proxy
+> the ip docker-machine ip throws. This is the value [`WebPack`][webpack-proxy]
-> requests
+> uses to proxy requests
 
 ### Running Orthanc
 
@@ -51,8 +51,9 @@ yarn run orthanc:up
 
 _Upload your first Study:_
 
-1. Navigate to [Orthanc's web interface](http://localhost:8899) at
+1. Navigate to
-   `http://localhost:8899` in a web browser.
+   [Orthanc's web interface](http://localhost:8042/app/explorer.html) at
+   `http://localhost:8042/app/explorer.html` in a web browser.
 2. In the top right corner, click "Upload"
 3. Click "Select files to upload..." and select one or more DICOM files
 4. Click "Start the upload"
@@ -60,17 +61,20 @@ _Upload your first Study:_
 #### Orthanc: Learn More
 
 You can see the `docker-compose.yml` file this command runs at
-[`<project-root>/platform/viewer/.recipes/Nginx-Orthanc/`](https://github.com/OHIF/Viewers/tree/master/platform/viewer/.recipes/Nginx-Orthanc),
+[`<project-root>/.docker/Nginx-Orthanc/`][orthanc-docker-compose], and more on
-and more on Orthanc for Docker in [Orthanc's documentation][orthanc-docker].
+Orthanc for Docker in [Orthanc's documentation][orthanc-docker].
 
 ### Connecting to Orthanc
 
 Now that we have a local Orthanc instance up and running, we need to configure
 our web application to connect to it. Open a new terminal window, navigate to
-this project's root directory, and run:
+this repository's root directory, and run:
 
 ```bash
-# If you haven't already, restore dependencies
+# If you haven't already, enable yarn workspaces
+yarn config set workspaces-experimental true
+
+# Restore dependencies
 yarn install
 
 # Run our dev command, but with the local orthanc config
@@ -87,18 +91,24 @@ is running the `dev:orthanc` script in our project's `package.json`. That script
 is:
 
 ```js
-cross-env PORT=5000 APP_CONFIG=config/docker_nginx-orthanc.js react-scripts start
+cross-env NODE_ENV=development PROXY_TARGET=/dicom-web PROXY_DOMAIN=http://localhost:8042 APP_CONFIG=config/docker_nginx-orthanc.js webpack-dev-server --config .webpack/webpack.pwa.js -w
 ```
 
-- `cross-env` sets two environment variables
+- `cross-env` sets three environment variables
-  - PORT: 5000
+  - PROXY_TARGET: `/dicom-web`
+  - PROXY_DOMAIN: `http://localhost:8042`
   - APP_CONFIG: `config/docker_nginx-orthanc.js`
-- `react-scripts` runs it's `start` script. This is [the de-facto
+- `webpack-dev-server` runs using the `.webpack/webpack.pwa.js` configuration
-  way][cra-start] to run a "Create React App" in development mode.
+  file. It will watch for changes and update as we develop.
+
+`PROXY_TARGET` and `PROXY_DOMAIN` tell our development server to proxy requests
+to `Orthanc`. This allows us to bypass CORS issues that normally occur when
+requesting resources that live at a different domain.
 
 The `APP_CONFIG` value tells our app which file to load on to `window.config`.
-By default, our app uses the file at `<project-root>/public/config/default.js`.
+By default, our app uses the file at
-Here is what that configuration looks like:
+`<project-root>/platform/viewer/public/config/default.js`. Here is what that
+configuration looks like:
 
 ```js
 window.config = {
@@ -145,8 +155,8 @@ _Feel free to make a Pull Request if you want to add to this list._
 [dcmjs-org]: https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/wado
 [dicom-web]: https://en.wikipedia.org/wiki/DICOMweb
 [storescu]: http://support.dcmtk.org/docs/storescu.html
-[cra-start]: https://github.com/facebook/create-react-app#npm-start-or-yarn-start
+[webpack-proxy]: https://webpack.js.org/configuration/dev-server/#devserverproxy
-[react-proxy]: https://facebook.github.io/create-react-app/docs/proxying-api-requests-in-development#configuring-the-proxy-manually
+[orthanc-docker-compose]: https://github.com/OHIF/Viewers/tree/master/.docker/Nginx-Orthanc
 <!-- Archives -->
 [dcm4chee]: https://github.com/dcm4che/dcm4chee-arc-light
 [dcm4chee-docker]: https://github.com/dcm4che/dcm4chee-arc-light/wiki/Running-on-Docker

docs/latest/essentials/getting-started.md

@@ -24,8 +24,7 @@ graphic that illustrates this setup][triangular-workflow].
 Alternatively, if you intend to use the OHIF Viewer as a starting point, and you
 aren't as concerned with syncing updates, then follow these steps:
 
-1. Navigate to the [OHIF/Viewers/tree/react][ohif-viewers-react-repo] repository
+1. Navigate to the [OHIF/Viewers][ohif-viewers] repository
-   and branch
 2. Click `Clone or download`, and then `Download ZIP`
 3. Use the contents of the `.zip` file as a starting point for your viewer
 
@@ -39,6 +38,8 @@ aren't as concerned with syncing updates, then follow these steps:
 
 - [Node.js & NPM](https://nodejs.org/en/)
 - [Yarn](https://yarnpkg.com/en/)
+- Yarn workspaces should be enabled:
+  - `yarn config set workspaces-experimental true`
 
 ### Kick the tires
 
@@ -50,21 +51,18 @@ following commands:
 yarn install
 
 # Start local development server
-yarn start
+yarn run dev
 ```
 
 You should see the following output:
 
 ```bash
-Compiled successfully!
+@ohif/viewer: i ｢wds｣: Project is running at http://localhost:3000/
+@ohif/viewer: i ｢wds｣: webpack output is served from /
+@ohif/viewer: i ｢wds｣: Content not from webpack is served from D:\code\ohif\Viewers\platform\viewer
+@ohif/viewer: i ｢wds｣: 404s will fallback to /index.html
 
-You can now view ohif-viewer in the browser.
+# And a list of all generated files
-
-  Local:            http://localhost:3000/
-  On Your Network:  http://10.74.20.83:3000/
-
-Note that the development build is not optimized.
-To create a production build, use yarn build.
 ```
 
 ### 🎉 Celebrate 🎉
@@ -81,15 +79,17 @@ To create a production build, use yarn build.
 
 ```bash
 # Build static assets to host a PWA
-yarn run build:web
+yarn run build
 
-# Build packaged output
+# Build packaged output (script-tag use)
 yarn run build:package
 ```
 
 ## Next Steps
 
-...
+Take a look at the sidebar. Depending on how you intend to use The OHIF Viewer,
+different topics may be more pertinent than others. At a minimum, reading "The
+Essentials" and the deployment recipes should be a good starting point.
 
 ## Troubleshooting
 
@@ -111,5 +111,5 @@ yarn run build:package
 [sync-changes]: https://help.github.com/en/articles/syncing-a-fork
 [triangular-workflow]: https://github.blog/2015-07-29-git-2-5-including-multiple-worktrees-and-triangular-workflows/#improved-support-for-triangular-workflows
 [ohif-viewers-repo]: https://github.com/OHIF/Viewers
-[ohif-viewers-react-repo]: https://github.com/OHIF/Viewers/tree/react
+[ohif-viewers]: https://github.com/OHIF/Viewers
 <!-- prettier-ignore-end -->

docs/latest/essentials/installation.md

@@ -5,38 +5,52 @@ processes:
 
 ```bash
 # Static Asset output: For deploying PWAs
-yarn run build:web
+yarn run build
 
 # Single `.js` script, for embedding viewer into existing apps
 yarn run build:package
 ```
 
-## create-react-app (PWA)
+## Progressive Web Application (PWA)
 
-> [create-react-app](https://github.com/facebook/create-react-app) provides
+> [Progressive Web Apps][pwa] are a new breed of web applications that meet the
-> pre-configured build process for developing front-end applications with
+> [following requirements][pwa-checklist]. Notably, targeting a PWA allows us
-> [React](https://reactjs.org/).
+> provide a reliable, fast, and engaging experience across different devices and
+> network conditions.
 
-The ohif-viewer package can be run as a create-react-app application. This is
+The OHIF Viewer is maintained as a [monorepo][monorepo]. We use WebPack to build
-useful for development, debugging, or evolving the OHIF Viewer into your own
+the many small static assets that comprise our application. Also generated is an
-custom imaging application.
+`index.html` that will serve as an entry point for loading configuration and the
+application, as well as a `service-worker` that can intelligently cache files so
+that subsequent requests are from the local file system instead of over the
+network.
 
 You can read more about this particular strategy in our
 [Build for Production Deployment Guide](./../deployment/recipes/build-for-production.md)
 
-## Rollup (Packaged Script)
+## Commonjs Bundle (Packaged Script)
 
-> [Rollup](https://rollupjs.org/guide/en) is a module bundler for JavaScript. It
+The [@ohif/viewer][viewer-npm] package is built with WebPack to provide a React
-> uses the new standardized format for code modules included in the ES6 revision
+component that can be dropped into a larger application. The `OHIFViewer`
-> of JavaScript.
+component is the entire viewer, configurable via React `props`. This is useful
+for including the OHIF Viewer in a larger web application, as the entire
+application can be provided via a `<script>` tag with no build process required.
 
-The [ohif-viewer](https://www.npmjs.com/package/ohif-viewer) package can be
+The bundle is not as performant or as optimized as the PWA build. It includes
-built with Rollup to provide a set of React components which can be dropped into
+fonts, styles, and the core extensions. If you find yourself facing performance
-a larger application. Specifically, the ohif-viewer package provides a React
+issues, you may wish to tweak what's included in this bundle or switch to the
-component named `OHIFViewer` which is the entire viewer, configurable via React
+PWA build.
-`props`. This is useful for including the OHIF Viewer in a larger web
-application, as the entire application can be provided via a `<script>` tag with
-no build process required.
 
 You can read more about this particular strategy in our
 [Embedded Viewer Deployment Guide](./../deployment/recipes/embedded-viewer.md)
+
+<!--
+  Links
+  -->
+
+<!-- prettier-ignore-start -->
+[pwa]: https://developers.google.com/web/progressive-web-apps/
+[pwa-checklist]: https://developers.google.com/web/progressive-web-apps/checklist
+[monorepo]: https://github.com/OHIF/Viewers/issues/768
+[viewer-npm]: https://www.npmjs.com/package/@ohif/viewer
+<!-- prettier-ignore-end -->

package.json

@@ -12,13 +12,15 @@
   },
   "scripts": {
     "cm": "npx git-cz",
-    "dev": "lerna run dev:viewer --stream",
-    "dev:project": ".scripts/dev.sh",
     "build": "lerna run build:viewer --stream",
     "build:ci": "lerna run build:viewer:ci --stream",
     "build:demo": "lerna run build:viewer:demo --stream",
     "build:package": "lerna run build:viewer:package --stream",
     "build:package-all": "lerna run build:package --parallel --stream",
+    "dev": "lerna run dev:viewer --stream",
+    "dev:project": ".scripts/dev.sh",
+    "dev:orthanc": "lerna run dev:orthanc --stream",
+    "orthanc:up": "docker-compose -f .docker/Nginx-Orthanc/docker-compose.yml up",
     "test": "yarn run test:unit",
     "test:unit": "jest --collectCoverage",
     "test:unit:ci": "lerna run test:unit:ci --parallel --stream",

platform/viewer/.webpack/webpack.pwa.js

@@ -23,10 +23,13 @@ const PUBLIC_DIR = path.join(__dirname, '../public');
 const HTML_TEMPLATE = process.env.HTML_TEMPLATE || 'index.html';
 const PUBLIC_URL = process.env.PUBLIC_URL || '/';
 const APP_CONFIG = process.env.APP_CONFIG || 'config/default.js';
+const PROXY_TARGET = process.env.PROXY_TARGET;
+const PROXY_DOMAIN = process.env.PROXY_DOMAIN;
 
 module.exports = (env, argv) => {
   const baseConfig = webpackBase(env, argv, { SRC_DIR, DIST_DIR });
   const isProdBuild = process.env.NODE_ENV === 'production';
+  const hasProxy = PROXY_TARGET && PROXY_DOMAIN;
 
   const mergedConfig = merge(baseConfig, {
     devtool: isProdBuild ? 'source-map' : 'cheap-module-eval-source-map',
@@ -111,6 +114,11 @@ module.exports = (env, argv) => {
     },
   });
 
+  if (hasProxy) {
+    mergedConfig.devServer.proxy = {};
+    mergedConfig.devServer.proxy[PROXY_TARGET] = PROXY_DOMAIN;
+  }
+
   if (!isProdBuild) {
     mergedConfig.plugins.push(new webpack.HotModuleReplacementPlugin());
 

platform/viewer/package.json

@@ -23,10 +23,9 @@
     "build:viewer:demo": "cross-env NODE_ENV=production APP_CONFIG=config/demo.js HTML_TEMPLATE=rollbar.html node --max_old_space_size=4096 ./../../node_modules/webpack/bin/webpack.js --progress --config .webpack/webpack.pwa.js",
     "build:viewer:package": "yarn run build:package",
     "dev": "cross-env NODE_ENV=development webpack-dev-server --config .webpack/webpack.pwa.js -w",
-    "dev:orthanc": "cross-env NODE_ENV=development APP_CONFIG=config/docker_nginx-orthanc.js react-scripts start",
+    "dev:orthanc": "cross-env NODE_ENV=development PROXY_TARGET=/dicom-web PROXY_DOMAIN=http://localhost:8042 APP_CONFIG=config/docker_nginx-orthanc.js webpack-dev-server --config .webpack/webpack.pwa.js -w",
     "dev:viewer": "yarn run dev",
     "start": "yarn run dev",
-    "orthanc:up": "docker-compose -f docker/Nginx-Orthanc/docker-compose.yml up",
     "test:e2e": "cypress open",
     "test:unit": "jest --watchAll",
     "test:unit:ci": "jest --ci --runInBand --collectCoverage"