From 27869a9cf61f0871a8a9695ff03d054585f50ac4 Mon Sep 17 00:00:00 2001 From: dannyrb Date: Thu, 5 Sep 2019 16:24:30 -0400 Subject: [PATCH] docs(configuration): env variables, build commands, templates --- docs/latest/essentials/configuration.md | 65 ++++++++++++++++++++----- 1 file changed, 52 insertions(+), 13 deletions(-) diff --git a/docs/latest/essentials/configuration.md b/docs/latest/essentials/configuration.md index 2b43a55f3..64662abb0 100644 --- a/docs/latest/essentials/configuration.md +++ b/docs/latest/essentials/configuration.md @@ -4,22 +4,47 @@ > one up, check out the [`Data Source` Guide](./data-source.md) or a deployment > recipe that contains an open source Image Archive -## How it Works +## Overview -The configuration for our project is in the `/public/config` directory. Our -build process knows which configuration file to use based on the `APP_CONFIG` -environment variable. By default, its value is -[`default.js`](https://github.com/OHIF/Viewers/blob/master/platform/viewer/public/config/default.js). -When we build, the `%APP_CONFIG%` value in -our[`/public/index.html`](https://github.com/OHIF/Viewers/blob/master/platform/viewer/public/index.html) -file is substituted for the correct configuration file's name. This sets the -`window.config` equal to our configuration file's value. +### Configuration Files + +The configuration for our viewer is in the `platform/viewer/public/config` +directory. Our build process knows which configuration file to use based on the +`APP_CONFIG` environment variable. By default, its value is +[`config/default.js`][default-config]. The majority of the viewer's features, +and registered extension's features, are configured using this file. + +**Embedded Use Note:** + +Alternatively, when using the `commonjs` bundle for embedded use cases, these +same values are what you'll pass to `installViewer` method: + +`OHIFStandaloneViewer.installViewer(window.config)` + +### Environment Variables + +We use environment variables at build and dev time to change the Viewer's +behavior. We can update the `HTML_TEMPLATE` to easily change which extensions +are registered, and specify a different `APP_CONFIG` to connect to an +alternative data source (or even specify different default hotkeys). + +| Environment Variable | Description | Default | +| -------------------- | -------------------------------------------------------------------------------------------------- | ------------------- | +| `HTML_TEMPLATE` | Which [HTML template][html-templates] to use as our web app's entry point. Specific to PWA builds. | `index.html` | +| `PUBLIC_URL` | The route relative to the host that the app will be served from. Specific to PWA builds. | `/` | +| `APP_CONFIG` | Which [configuration file][config-file] to copy to output as `app-config.js` | `config/default.js` | +| `PROXY_TARGET` | When developing, proxy requests that match this pattern to `PROXY_DOMAIN` | `undefined` | +| `PROXY_DOMAIN` | When developing, proxy requests from `PROXY_TARGET` to `PROXY_DOMAIN` | `undefined` | + +### Registering Extensions + +> :warn: Instructions coming soon ## How do I configure my project? The simplest way is to update the existing default config: -_/public/config/default.js_ +_/platform/viewer/public/config/default.js_ ```js window.config = { @@ -47,10 +72,24 @@ You can also create a new config file and specify its path relative to the build output's root by setting the `APP_CONFIG` environment variable. You can set the value of this environment variable a few different ways: -- [Add a temporary environment variable in your shell](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#adding-temporary-environment-variables-in-your-shell) -- [Add environment specific variables in `.env` file(s)](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#adding-development-environment-variables-in-env) +- ~[Add a temporary environment variable in your shell](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#adding-temporary-environment-variables-in-your-shell)~ + - Previous `react-scripts` functionality that we need to duplicate with + `dotenv-webpack` +- ~[Add environment specific variables in `.env` file(s)](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#adding-development-environment-variables-in-env)~ + - Previous `react-scripts` functionality that we need to duplicate with + `dotenv-webpack` - Using the `cross-env` package in an npm script: - `"build": "cross-env APP_CONFIG=config/my-config.js react-scripts build"` -After updating the configuration, `yarn run build:web` to generate updated build +After updating the configuration, `yarn run build` to generate updated build output. + + + + +[default-config]: https://github.com/OHIF/Viewers/blob/master/platform/viewer/public/config/default.js +[html-templates]: https://github.com/OHIF/Viewers/tree/master/platform/viewer/public/html-templates +[config-files]: https://github.com/OHIF/Viewers/tree/master/platform/viewer/public/config +