From 35bc6749faa5a4f60e140eb0e2261ac0739c3f09 Mon Sep 17 00:00:00 2001 From: Zac Butko Date: Tue, 2 Aug 2022 11:58:34 -0500 Subject: [PATCH 01/10] Code block navigation docstrings --- .../esm-config/src/navigation/navigate.ts | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/packages/framework/esm-config/src/navigation/navigate.ts b/packages/framework/esm-config/src/navigation/navigate.ts index 043d254ee..bf4cbf7d9 100644 --- a/packages/framework/esm-config/src/navigation/navigate.ts +++ b/packages/framework/esm-config/src/navigation/navigate.ts @@ -25,12 +25,14 @@ export interface NavigateOptions { * }; * ``` * Example return values: - * navigate({ to: "/some/path" }); => window.location.assign("/some/path") - * navigate({ to: "https://single-spa.js.org/" }); => window.location.assign("https://single-spa.js.org/") - * navigate({ to: "${openmrsBase}/some/path" }); => window.location.assign("/openmrs/some/path") - * navigate({ to: "/openmrs/spa/foo/page" }); => navigateToUrl("/openmrs/spa/foo/page") - * navigate({ to: "${openmrsSpaBase}/bar/page" }); => navigateToUrl("/openmrs/spa/bar/page") - * navigate({ to: "/${openmrsSpaBase}/baz/page" }) => navigateToUrl("/openmrs/spa/baz/page") + * ```js + * navigate({ to: "/some/path" }); // => window.location.assign("/some/path") + * navigate({ to: "https://single-spa.js.org/" }); // => window.location.assign("https://single-spa.js.org/") + * navigate({ to: "${openmrsBase}/some/path" }); // => window.location.assign("/openmrs/some/path") + * navigate({ to: "/openmrs/spa/foo/page" }); // => navigateToUrl("/openmrs/spa/foo/page") + * navigate({ to: "${openmrsSpaBase}/bar/page" }); // => navigateToUrl("/openmrs/spa/bar/page") + * navigate({ to: "/${openmrsSpaBase}/baz/page" }) // => navigateToUrl("/openmrs/spa/baz/page") + * ``` * * @param to The target path or URL. Supports templating with 'openmrsBase', 'openmrsSpaBase', * and any additional template parameters defined in `templateParams`. From 312ab0087996200845b284fa7e1a7fee78e24084 Mon Sep 17 00:00:00 2001 From: Zac Butko Date: Tue, 2 Aug 2022 14:00:02 -0500 Subject: [PATCH 02/10] Some tips for staying up to date --- docs/getting_started/setup.md | 44 ++++++++++++++++++++ packages/framework/esm-framework/docs/API.md | 16 +++---- 2 files changed, 53 insertions(+), 7 deletions(-) diff --git a/docs/getting_started/setup.md b/docs/getting_started/setup.md index 92044db76..c1acee5e3 100644 --- a/docs/getting_started/setup.md +++ b/docs/getting_started/setup.md @@ -125,3 +125,47 @@ If you're using import map overrides on a server that uses HTTPS, you must use ` You will need to convince it that there is no security risk. In Chrome, enabling the "allow insecure localhost" flag (chrome://flags/#allow-insecure-localhost) can help. + +## Staying Up To Date + +Staying current with the code base is important to make sure we have correct versions of the app-shell, core libraries, or other microfrontends which all know how to talk to each other. Often pulling the latest versions is necessary to fix some critical bugs which were found or to use some new feature which was built. For the OpenMRS project there are several places we should look to make sure our application is kept up to date. If you are having trouble running code locally when it appears to be working on the server, consider taking any or all of these upgrade steps. +### Updating core libraries + +If you notice your app suddenly stop working there is a chance that some core library has changed. The main dependencies shared by all OpenMRS microfrontends are `openmrs` and `@openmrs/esm-framework`. + +```sh +yarn upgrade openmrs @openmrs/esm-framework +git restore package.json # resets version numbers to "next" +``` + +After updating these core libraries be sure to restart your development server + +### Updating current branch + +It's good practice to merge the main branch into your working branch often, at least once a week. This way, if anyone else has made changes to the app dependencies or fixed any bugs you will be able to get these benefits. Also, this prevent merge conflicts when trying to make a PR if your files are behind the main branch. + +```sh +git checkout main +git pull +git checkout [my-branch-name] +git merge main +``` + +### Refreshing importmap +Sometimes the modules being pointed to by the importmap have been updated. If your local development setup is using an old importmap consider replacing the static versions with more recent versions. Another alternative here is to use a dynamic importmap when starting your local server + +```sh +# an example of pointing a local development server to a dynamic importmap +yarn start --importmap "https://spa-modules.nyc3.digitaloceanspaces.com/import-map.json" +``` + +### Clearing out the browser cache + +By default modules are cached by your browser for 30 days. This is thanks to a configuration setting on the server. This is a fine setting for end users, but as developers we often need the latest version of a core module or microfrontend as soon as it comes out. The easiest way to do this is to open your browser's implementer tools, going to the "Network" tab and checking "Disable Cache". Then, force reload the page. You should get brand new javascript files from the server. After you have refreshed the page to replace your cached script files, you can uncheck the "Disable Cache" option to improve the application behavior, and not re-download script files on every reload. + +How to open browser developer tools (chrome) +open-devtools-chrome + +How to disable asset (javascript, css) cache (chrome) +disable-cache-chrome + diff --git a/packages/framework/esm-framework/docs/API.md b/packages/framework/esm-framework/docs/API.md index 94f4b4b4e..30b9c5e82 100644 --- a/packages/framework/esm-framework/docs/API.md +++ b/packages/framework/esm-framework/docs/API.md @@ -2719,12 +2719,14 @@ const submitHandler = () => { }; ``` Example return values: -navigate({ to: "/some/path" }); => window.location.assign("/some/path") -navigate({ to: "https://single-spa.js.org/" }); => window.location.assign("https://single-spa.js.org/") -navigate({ to: "${openmrsBase}/some/path" }); => window.location.assign("/openmrs/some/path") -navigate({ to: "/openmrs/spa/foo/page" }); => navigateToUrl("/openmrs/spa/foo/page") -navigate({ to: "${openmrsSpaBase}/bar/page" }); => navigateToUrl("/openmrs/spa/bar/page") -navigate({ to: "/${openmrsSpaBase}/baz/page" }) => navigateToUrl("/openmrs/spa/baz/page") +```js +navigate({ to: "/some/path" }); // => window.location.assign("/some/path") +navigate({ to: "https://single-spa.js.org/" }); // => window.location.assign("https://single-spa.js.org/") +navigate({ to: "${openmrsBase}/some/path" }); // => window.location.assign("/openmrs/some/path") +navigate({ to: "/openmrs/spa/foo/page" }); // => navigateToUrl("/openmrs/spa/foo/page") +navigate({ to: "${openmrsSpaBase}/bar/page" }); // => navigateToUrl("/openmrs/spa/bar/page") +navigate({ to: "/${openmrsSpaBase}/baz/page" }) // => navigateToUrl("/openmrs/spa/baz/page") +``` #### Parameters @@ -2738,7 +2740,7 @@ navigate({ to: "/${openmrsSpaBase}/baz/page" }) => navigateToUrl("/openmrs/spa/b #### Defined in -[packages/framework/esm-config/src/navigation/navigate.ts:42](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-config/src/navigation/navigate.ts#L42) +[packages/framework/esm-config/src/navigation/navigate.ts:44](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-config/src/navigation/navigate.ts#L44) ___ From 3078c791171f11f492bb9713ba598685c6a17bc3 Mon Sep 17 00:00:00 2001 From: Zac Butko Date: Tue, 2 Aug 2022 14:08:48 -0500 Subject: [PATCH 03/10] Some clarification --- docs/getting_started/setup.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/getting_started/setup.md b/docs/getting_started/setup.md index c1acee5e3..0743d3444 100644 --- a/docs/getting_started/setup.md +++ b/docs/getting_started/setup.md @@ -128,7 +128,7 @@ that there is no security risk. In Chrome, enabling the "allow insecure localhos ## Staying Up To Date -Staying current with the code base is important to make sure we have correct versions of the app-shell, core libraries, or other microfrontends which all know how to talk to each other. Often pulling the latest versions is necessary to fix some critical bugs which were found or to use some new feature which was built. For the OpenMRS project there are several places we should look to make sure our application is kept up to date. If you are having trouble running code locally when it appears to be working on the server, consider taking any or all of these upgrade steps. +Staying current with the code base is important to make sure we the latest fixes, latest features, and the correct API to develop against. When developing a microfrontend your code will depend on app-shell and core libraries and sometimes other microfrontends. For the OpenMRS project there are several places we should look to make sure our application is kept up to date. If you are having trouble running code locally when it appears to be working on the server ([dev3](https://dev3.openmrs.org/openmrs/spa)), consider taking any or all of these upgrade steps. ### Updating core libraries If you notice your app suddenly stop working there is a chance that some core library has changed. The main dependencies shared by all OpenMRS microfrontends are `openmrs` and `@openmrs/esm-framework`. @@ -142,7 +142,7 @@ After updating these core libraries be sure to restart your development server ### Updating current branch -It's good practice to merge the main branch into your working branch often, at least once a week. This way, if anyone else has made changes to the app dependencies or fixed any bugs you will be able to get these benefits. Also, this prevent merge conflicts when trying to make a PR if your files are behind the main branch. +It's good practice to merge the main branch into your working branch often, at least once a week. This way, if anyone else has made changes to the app dependencies or fixed any bugs you will be able to get these benefits. Also, this prevents merge conflicts when trying to make a PR if your files are behind the main branch. ```sh git checkout main @@ -152,6 +152,7 @@ git merge main ``` ### Refreshing importmap + Sometimes the modules being pointed to by the importmap have been updated. If your local development setup is using an old importmap consider replacing the static versions with more recent versions. Another alternative here is to use a dynamic importmap when starting your local server ```sh @@ -161,7 +162,7 @@ yarn start --importmap "https://spa-modules.nyc3.digitaloceanspaces.com/import-m ### Clearing out the browser cache -By default modules are cached by your browser for 30 days. This is thanks to a configuration setting on the server. This is a fine setting for end users, but as developers we often need the latest version of a core module or microfrontend as soon as it comes out. The easiest way to do this is to open your browser's implementer tools, going to the "Network" tab and checking "Disable Cache". Then, force reload the page. You should get brand new javascript files from the server. After you have refreshed the page to replace your cached script files, you can uncheck the "Disable Cache" option to improve the application behavior, and not re-download script files on every reload. +By default the module javascript files are cached by your browser for 30 days. This is thanks to a [configuration setting](https://github.com/openmrs/openmrs-contrib-ansible-docker-compose/blob/c36115ca22b8fb842f8cf0ff745d1d35a4567912/files/emr-3-dev/proxy.conf#L97) on the server. This is a fine setting for end users, and caching is useful to make sure we don't need to download the entire app again with each reload, but as developers we often need the latest version of a core module or microfrontend as soon as it comes out. The easiest way to trigger a re-download of the app javascript files is to open your browser's implementer tools, going to the "Network" tab and checking "Disable Cache". Then, force reload the page. You should get brand new javascript files from the server. After you have refreshed the page to replace your cached script files, you can uncheck the "Disable Cache" option to improve the application behavior and not re-download script files on every reload. How to open browser developer tools (chrome) open-devtools-chrome From 90c073b5b9484e87f75f4e0e686be8df7c189f1d Mon Sep 17 00:00:00 2001 From: Zac Butko Date: Tue, 2 Aug 2022 14:36:10 -0500 Subject: [PATCH 04/10] Updated pictures --- docs/getting_started/setup.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/getting_started/setup.md b/docs/getting_started/setup.md index 0743d3444..73f61e015 100644 --- a/docs/getting_started/setup.md +++ b/docs/getting_started/setup.md @@ -126,7 +126,7 @@ You will need to convince it that there is no security risk. In Chrome, enabling the "allow insecure localhost" flag (chrome://flags/#allow-insecure-localhost) can help. -## Staying Up To Date +## Staying Up To Date, Troubleshooting Staying current with the code base is important to make sure we the latest fixes, latest features, and the correct API to develop against. When developing a microfrontend your code will depend on app-shell and core libraries and sometimes other microfrontends. For the OpenMRS project there are several places we should look to make sure our application is kept up to date. If you are having trouble running code locally when it appears to be working on the server ([dev3](https://dev3.openmrs.org/openmrs/spa)), consider taking any or all of these upgrade steps. ### Updating core libraries @@ -165,8 +165,13 @@ yarn start --importmap "https://spa-modules.nyc3.digitaloceanspaces.com/import-m By default the module javascript files are cached by your browser for 30 days. This is thanks to a [configuration setting](https://github.com/openmrs/openmrs-contrib-ansible-docker-compose/blob/c36115ca22b8fb842f8cf0ff745d1d35a4567912/files/emr-3-dev/proxy.conf#L97) on the server. This is a fine setting for end users, and caching is useful to make sure we don't need to download the entire app again with each reload, but as developers we often need the latest version of a core module or microfrontend as soon as it comes out. The easiest way to trigger a re-download of the app javascript files is to open your browser's implementer tools, going to the "Network" tab and checking "Disable Cache". Then, force reload the page. You should get brand new javascript files from the server. After you have refreshed the page to replace your cached script files, you can uncheck the "Disable Cache" option to improve the application behavior and not re-download script files on every reload. How to open browser developer tools (chrome) -open-devtools-chrome +open-devtools-chrome How to disable asset (javascript, css) cache (chrome) -disable-cache-chrome +disable-cache-chrome +### Restarting your computer + +Its possible for browser caches to not get cleared properly, or else for applications to be left in an inconsistent state which causes them to run poorly, slowly, or not at all. Sometimes these issues are only recoverable with restarting your computer + + > *Did you turn it off and then on again? From 28a916d48218df066a75ada79a778711a8840e28 Mon Sep 17 00:00:00 2001 From: Zac Butko Date: Tue, 2 Aug 2022 15:10:03 -0500 Subject: [PATCH 05/10] Move to own page --- docs/_sidebar.md | 1 + docs/getting_started/setup.md | 50 ------------------------- docs/getting_started/troubleshooting.md | 49 ++++++++++++++++++++++++ 3 files changed, 50 insertions(+), 50 deletions(-) create mode 100644 docs/getting_started/troubleshooting.md diff --git a/docs/_sidebar.md b/docs/_sidebar.md index dfa103fa1..346b4754d 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -4,6 +4,7 @@ - Getting started - [Prerequisite Knowledge](/getting_started/prerequisites.md) - [Setup](/getting_started/setup.md) + - [Staying Current & Troubleshooting](/getting_started/troubleshooting.md) - [Contributing](/getting_started/contributing.md) - [Release and Deployment](/getting_started/release_and_deployment.md) - [Tour of a Frontend Module](/getting_started/tour.md) diff --git a/docs/getting_started/setup.md b/docs/getting_started/setup.md index 73f61e015..92044db76 100644 --- a/docs/getting_started/setup.md +++ b/docs/getting_started/setup.md @@ -125,53 +125,3 @@ If you're using import map overrides on a server that uses HTTPS, you must use ` You will need to convince it that there is no security risk. In Chrome, enabling the "allow insecure localhost" flag (chrome://flags/#allow-insecure-localhost) can help. - -## Staying Up To Date, Troubleshooting - -Staying current with the code base is important to make sure we the latest fixes, latest features, and the correct API to develop against. When developing a microfrontend your code will depend on app-shell and core libraries and sometimes other microfrontends. For the OpenMRS project there are several places we should look to make sure our application is kept up to date. If you are having trouble running code locally when it appears to be working on the server ([dev3](https://dev3.openmrs.org/openmrs/spa)), consider taking any or all of these upgrade steps. -### Updating core libraries - -If you notice your app suddenly stop working there is a chance that some core library has changed. The main dependencies shared by all OpenMRS microfrontends are `openmrs` and `@openmrs/esm-framework`. - -```sh -yarn upgrade openmrs @openmrs/esm-framework -git restore package.json # resets version numbers to "next" -``` - -After updating these core libraries be sure to restart your development server - -### Updating current branch - -It's good practice to merge the main branch into your working branch often, at least once a week. This way, if anyone else has made changes to the app dependencies or fixed any bugs you will be able to get these benefits. Also, this prevents merge conflicts when trying to make a PR if your files are behind the main branch. - -```sh -git checkout main -git pull -git checkout [my-branch-name] -git merge main -``` - -### Refreshing importmap - -Sometimes the modules being pointed to by the importmap have been updated. If your local development setup is using an old importmap consider replacing the static versions with more recent versions. Another alternative here is to use a dynamic importmap when starting your local server - -```sh -# an example of pointing a local development server to a dynamic importmap -yarn start --importmap "https://spa-modules.nyc3.digitaloceanspaces.com/import-map.json" -``` - -### Clearing out the browser cache - -By default the module javascript files are cached by your browser for 30 days. This is thanks to a [configuration setting](https://github.com/openmrs/openmrs-contrib-ansible-docker-compose/blob/c36115ca22b8fb842f8cf0ff745d1d35a4567912/files/emr-3-dev/proxy.conf#L97) on the server. This is a fine setting for end users, and caching is useful to make sure we don't need to download the entire app again with each reload, but as developers we often need the latest version of a core module or microfrontend as soon as it comes out. The easiest way to trigger a re-download of the app javascript files is to open your browser's implementer tools, going to the "Network" tab and checking "Disable Cache". Then, force reload the page. You should get brand new javascript files from the server. After you have refreshed the page to replace your cached script files, you can uncheck the "Disable Cache" option to improve the application behavior and not re-download script files on every reload. - -How to open browser developer tools (chrome) -open-devtools-chrome - -How to disable asset (javascript, css) cache (chrome) -disable-cache-chrome - -### Restarting your computer - -Its possible for browser caches to not get cleared properly, or else for applications to be left in an inconsistent state which causes them to run poorly, slowly, or not at all. Sometimes these issues are only recoverable with restarting your computer - - > *Did you turn it off and then on again? diff --git a/docs/getting_started/troubleshooting.md b/docs/getting_started/troubleshooting.md new file mode 100644 index 000000000..8ee469bf1 --- /dev/null +++ b/docs/getting_started/troubleshooting.md @@ -0,0 +1,49 @@ +# Staying Current & Troubleshooting + +Staying current with the code base is important to make sure we the latest fixes, latest features, and the correct API to develop against. When developing a microfrontend your code will depend on app-shell and core libraries and sometimes other microfrontends. For the OpenMRS project there are several places we should look to make sure our application is kept up to date. If you are having trouble running code locally when it appears to be working on the server ([dev3](https://dev3.openmrs.org/openmrs/spa)), consider taking any or all of these upgrade steps. +## Updating core libraries + +If you notice your app suddenly stop working there is a chance that some core library has changed. The main dependencies shared by all OpenMRS microfrontends are `openmrs` and `@openmrs/esm-framework`. + +```sh +yarn upgrade openmrs @openmrs/esm-framework +git restore package.json # resets version numbers to "next" +``` + +After updating these core libraries be sure to restart your development server + +## Updating current branch + +It's good practice to merge the main branch into your working branch often, at least once a week. This way, if anyone else has made changes to the app dependencies or fixed any bugs you will be able to get these benefits. Also, this prevents merge conflicts when trying to make a PR if your files are behind the main branch. + +```sh +git checkout main +git pull +git checkout [my-branch-name] +git merge main +``` + +## Refreshing importmap + +Sometimes the modules being pointed to by the importmap have been updated. If your local development setup is using an old importmap consider replacing the static versions with more recent versions. Another alternative here is to use a dynamic importmap when starting your local server + +```sh +# an example of pointing a local development server to a dynamic importmap +yarn start --importmap "https://spa-modules.nyc3.digitaloceanspaces.com/import-map.json" +``` + +## Clearing out the browser cache + +By default the module javascript files are cached by your browser for 30 days. This is thanks to a [configuration setting](https://github.com/openmrs/openmrs-contrib-ansible-docker-compose/blob/c36115ca22b8fb842f8cf0ff745d1d35a4567912/files/emr-3-dev/proxy.conf#L97) on the server. This is a fine setting for end users, and caching is useful to make sure we don't need to download the entire app again with each reload, but as developers we often need the latest version of a core module or microfrontend as soon as it comes out. The easiest way to trigger a re-download of the app javascript files is to open your browser's implementer tools, going to the "Network" tab and checking "Disable Cache". Then, force reload the page. You should get brand new javascript files from the server. After you have refreshed the page to replace your cached script files, you can uncheck the "Disable Cache" option to improve the application behavior and not re-download script files on every reload. + +How to open browser developer tools (chrome) +open-devtools-chrome + +How to disable asset (javascript, css) cache (chrome) +disable-cache-chrome + +## Restarting your computer + +Its possible for browser caches to not get cleared properly, or else for applications to be left in an inconsistent state which causes them to run poorly, slowly, or not at all. Sometimes these issues are only recoverable with restarting your computer + + > *Did you turn it off and then on again?* From 25a353ca1f6e9af1c91c710be86a3b5c81f0daf2 Mon Sep 17 00:00:00 2001 From: Zac Butko Date: Mon, 15 Aug 2022 11:11:43 -0700 Subject: [PATCH 06/10] Better markdown --- packages/framework/esm-config/src/navigation/navigate.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/framework/esm-config/src/navigation/navigate.ts b/packages/framework/esm-config/src/navigation/navigate.ts index bf4cbf7d9..108452de3 100644 --- a/packages/framework/esm-config/src/navigation/navigate.ts +++ b/packages/framework/esm-config/src/navigation/navigate.ts @@ -17,14 +17,14 @@ export interface NavigateOptions { /** * Calls `location.assign` for non-SPA paths and [navigateToUrl](https://single-spa.js.org/docs/api/#navigatetourl) for SPA paths * - * Example usage: + * #### Example usage: * ```js * const config = useConfig(); * const submitHandler = () => { * navigate({ to: config.links.submitSuccess }); * }; * ``` - * Example return values: + * #### Example return values: * ```js * navigate({ to: "/some/path" }); // => window.location.assign("/some/path") * navigate({ to: "https://single-spa.js.org/" }); // => window.location.assign("https://single-spa.js.org/") From e619c09a46faae965ed738c7368ca1ac5168d100 Mon Sep 17 00:00:00 2001 From: Zac Butko Date: Mon, 15 Aug 2022 13:16:41 -0700 Subject: [PATCH 07/10] Markdown update --- packages/framework/esm-framework/docs/API.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/framework/esm-framework/docs/API.md b/packages/framework/esm-framework/docs/API.md index 250b69c4c..ffa4aac54 100644 --- a/packages/framework/esm-framework/docs/API.md +++ b/packages/framework/esm-framework/docs/API.md @@ -2722,14 +2722,14 @@ ___ Calls `location.assign` for non-SPA paths and [navigateToUrl](https://single-spa.js.org/docs/api/#navigatetourl) for SPA paths -Example usage: +#### Example usage: ```js const config = useConfig(); const submitHandler = () => { navigate({ to: config.links.submitSuccess }); }; ``` -Example return values: +#### Example return values: ```js navigate({ to: "/some/path" }); // => window.location.assign("/some/path") navigate({ to: "https://single-spa.js.org/" }); // => window.location.assign("https://single-spa.js.org/") @@ -2751,7 +2751,7 @@ navigate({ to: "/${openmrsSpaBase}/baz/page" }) // => navigateToUrl("/openmrs/sp #### Defined in -[packages/framework/esm-config/src/navigation/navigate.ts:44](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-config/src/navigation/navigate.ts#L44) +[packages/framework/esm-config/src/navigation/navigate.ts:44](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-config/src/navigation/navigate.ts#L44) ___ From 5fe3f52ea0e09126e7437dea1d6aafdc8111bd44 Mon Sep 17 00:00:00 2001 From: Zac Butko Date: Mon, 15 Aug 2022 14:45:23 -0700 Subject: [PATCH 08/10] Changes per Brandon --- docs/_sidebar.md | 1 - docs/getting_started/troubleshooting.md | 49 ---------------- docs/main/faq.md | 58 +++++++++++++++++-- .../esm-config/src/navigation/navigate.ts | 2 + packages/framework/esm-framework/docs/API.md | 4 +- 5 files changed, 57 insertions(+), 57 deletions(-) delete mode 100644 docs/getting_started/troubleshooting.md diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 17b3f88d6..1ae6bc5ba 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -4,7 +4,6 @@ - Getting started - [Prerequisite Knowledge](/getting_started/prerequisites.md) - [Setup](/getting_started/setup.md) - - [Staying Current & Troubleshooting](/getting_started/troubleshooting.md) - [Contributing](/getting_started/contributing.md) - [Release and Deployment](/getting_started/release_and_deployment.md) - [Tour of a Frontend Module](/getting_started/tour.md) diff --git a/docs/getting_started/troubleshooting.md b/docs/getting_started/troubleshooting.md deleted file mode 100644 index 8ee469bf1..000000000 --- a/docs/getting_started/troubleshooting.md +++ /dev/null @@ -1,49 +0,0 @@ -# Staying Current & Troubleshooting - -Staying current with the code base is important to make sure we the latest fixes, latest features, and the correct API to develop against. When developing a microfrontend your code will depend on app-shell and core libraries and sometimes other microfrontends. For the OpenMRS project there are several places we should look to make sure our application is kept up to date. If you are having trouble running code locally when it appears to be working on the server ([dev3](https://dev3.openmrs.org/openmrs/spa)), consider taking any or all of these upgrade steps. -## Updating core libraries - -If you notice your app suddenly stop working there is a chance that some core library has changed. The main dependencies shared by all OpenMRS microfrontends are `openmrs` and `@openmrs/esm-framework`. - -```sh -yarn upgrade openmrs @openmrs/esm-framework -git restore package.json # resets version numbers to "next" -``` - -After updating these core libraries be sure to restart your development server - -## Updating current branch - -It's good practice to merge the main branch into your working branch often, at least once a week. This way, if anyone else has made changes to the app dependencies or fixed any bugs you will be able to get these benefits. Also, this prevents merge conflicts when trying to make a PR if your files are behind the main branch. - -```sh -git checkout main -git pull -git checkout [my-branch-name] -git merge main -``` - -## Refreshing importmap - -Sometimes the modules being pointed to by the importmap have been updated. If your local development setup is using an old importmap consider replacing the static versions with more recent versions. Another alternative here is to use a dynamic importmap when starting your local server - -```sh -# an example of pointing a local development server to a dynamic importmap -yarn start --importmap "https://spa-modules.nyc3.digitaloceanspaces.com/import-map.json" -``` - -## Clearing out the browser cache - -By default the module javascript files are cached by your browser for 30 days. This is thanks to a [configuration setting](https://github.com/openmrs/openmrs-contrib-ansible-docker-compose/blob/c36115ca22b8fb842f8cf0ff745d1d35a4567912/files/emr-3-dev/proxy.conf#L97) on the server. This is a fine setting for end users, and caching is useful to make sure we don't need to download the entire app again with each reload, but as developers we often need the latest version of a core module or microfrontend as soon as it comes out. The easiest way to trigger a re-download of the app javascript files is to open your browser's implementer tools, going to the "Network" tab and checking "Disable Cache". Then, force reload the page. You should get brand new javascript files from the server. After you have refreshed the page to replace your cached script files, you can uncheck the "Disable Cache" option to improve the application behavior and not re-download script files on every reload. - -How to open browser developer tools (chrome) -open-devtools-chrome - -How to disable asset (javascript, css) cache (chrome) -disable-cache-chrome - -## Restarting your computer - -Its possible for browser caches to not get cleared properly, or else for applications to be left in an inconsistent state which causes them to run poorly, slowly, or not at all. Sometimes these issues are only recoverable with restarting your computer - - > *Did you turn it off and then on again?* diff --git a/docs/main/faq.md b/docs/main/faq.md index fd4b14360..9fe9040aa 100644 --- a/docs/main/faq.md +++ b/docs/main/faq.md @@ -1,20 +1,66 @@ # Frequently Asked Questions +## Troubleshooting Local Dev Environment + +It's important to keep your working code base current with the latest fixes, latest features, and library APIs to develop against. When developing a frontend module your code will depend on the app shell and core libraries, and sometimes other frontend modules. If you are having trouble running code locally when it appears to be working on the server ([dev3](https://dev3.openmrs.org/openmrs/spa)), try the following. + + +### How do I keep my local dev server up to date? + +Just pull the repository you want to work on and run `yarn` or `npm install`. +That will install the latest dependencies, which includes `openmrs`, which is +the tool that runs the dev server. + +For help with pulling the latest code see the [community help page](https://wiki.openmrs.org/display/docs/Using+Git) for basic git commands. + ### I'm not seeing the latest `@openmrs/esm-framework`. How do I update the dependency? -In a repository using Yarn: +If you notice your app suddenly stop working, it might be because a core library has changed in the app shell on the server you are developing against. The main dependencies shared by all OpenMRS frontend modules are `openmrs` and `@openmrs/esm-framework`. They can be updated like this: ```sh -yarn upgrade @openmrs/esm-framework openmrs # to upgrade +yarn up openmrs @openmrs/esm-framework openmrs # to upgrade git checkout package.json # to reset the version specifiers to 'next' yarn # to re-create the lockfile ``` -### How do I keep my local dev server up to date? +## Refreshing importmap -Just pull the repository you want to work on and run `yarn` or `npm install`. -That will install the latest dependencies, which includes `openmrs`, which is -the tool that runs the dev server. +The static importmap file used by `openmrs develop` is manually updated and therefore often out of date containing old versions of the frontend modules. You can submit a PR to update [that file](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/shell/esm-app-shell/src/assets/importmap.json), or you can use an import map from the internet like so: + +```sh +yarn start --importmap "https://spa-modules.nyc3.digitaloceanspaces.com/import-map.json" +``` + + +### Clearing out the browser cache + +By default the server [tells your browser](https://github.com/openmrs/openmrs-contrib-ansible-docker-compose/blob/c36115ca22b8fb842f8cf0ff745d1d35a4567912/files/emr-3-dev/proxy.conf#L97) to cache JavaScript files for 30 days. You can [bypass your browser's cache](https://en.wikipedia.org/wiki/Wikipedia:Bypass_your_cache) when refreshing the page. If you want to keep the cache disabled while you are developing, open your browser's developer tools, go to the "Network" tab, and check "Disable Cache." The cache will only be disabled while the developer tools are open, and only for the page that they are attached to. + +How to open browser developer tools (chrome) +open-devtools-chrome + +How to disable asset (javascript, css) cache (chrome) +disable-cache-chrome + +### Clear local package cache + +Although yarn is very good at maintaining its dependency list as specified in `yarn.lock` it is possible for the `node_modules` folder containing library packages to get corrupted. You can manually remove the the `node_modules` folder and rebuild it with `yarn` + +```sh +rm -rf node_modules/ +yarn +``` + +This will only delete the root `node_modules` folder. You may also want to delete the `node_modules` of all packages in a monorepo. If the monorepo has Lerna you can simply run `npx lerna clean` followed by `yarn`. Otherwise delete these manually, then run `yarn`. + +Yarn is smart and will quickly compile the new `node_modules` folder from its internal cache. If you are worried that yarn has cached an invalid version of a package you can clear yarn cache to force it to download the packages again + +```sh +yarn cache clean +``` + + +## Further Info ### How do I find out where the code I need to work on is? diff --git a/packages/framework/esm-config/src/navigation/navigate.ts b/packages/framework/esm-config/src/navigation/navigate.ts index 108452de3..5ed1430e0 100644 --- a/packages/framework/esm-config/src/navigation/navigate.ts +++ b/packages/framework/esm-config/src/navigation/navigate.ts @@ -19,6 +19,7 @@ export interface NavigateOptions { * * #### Example usage: * ```js + * @example * const config = useConfig(); * const submitHandler = () => { * navigate({ to: config.links.submitSuccess }); @@ -26,6 +27,7 @@ export interface NavigateOptions { * ``` * #### Example return values: * ```js + * @example * navigate({ to: "/some/path" }); // => window.location.assign("/some/path") * navigate({ to: "https://single-spa.js.org/" }); // => window.location.assign("https://single-spa.js.org/") * navigate({ to: "${openmrsBase}/some/path" }); // => window.location.assign("/openmrs/some/path") diff --git a/packages/framework/esm-framework/docs/API.md b/packages/framework/esm-framework/docs/API.md index ffa4aac54..64877851e 100644 --- a/packages/framework/esm-framework/docs/API.md +++ b/packages/framework/esm-framework/docs/API.md @@ -2724,6 +2724,7 @@ Calls `location.assign` for non-SPA paths and [navigateToUrl](https://single-spa #### Example usage: ```js +@example const config = useConfig(); const submitHandler = () => { navigate({ to: config.links.submitSuccess }); @@ -2731,6 +2732,7 @@ const submitHandler = () => { ``` #### Example return values: ```js +@example navigate({ to: "/some/path" }); // => window.location.assign("/some/path") navigate({ to: "https://single-spa.js.org/" }); // => window.location.assign("https://single-spa.js.org/") navigate({ to: "${openmrsBase}/some/path" }); // => window.location.assign("/openmrs/some/path") @@ -2751,7 +2753,7 @@ navigate({ to: "/${openmrsSpaBase}/baz/page" }) // => navigateToUrl("/openmrs/sp #### Defined in -[packages/framework/esm-config/src/navigation/navigate.ts:44](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-config/src/navigation/navigate.ts#L44) +[packages/framework/esm-config/src/navigation/navigate.ts:46](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-config/src/navigation/navigate.ts#L46) ___ From 2ad356174f70e1394267646f9ecfc6c876c91b65 Mon Sep 17 00:00:00 2001 From: Zac Butko Date: Mon, 15 Aug 2022 16:50:12 -0700 Subject: [PATCH 09/10] Some more hax --- docs/main/faq.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/main/faq.md b/docs/main/faq.md index 9fe9040aa..c544baad4 100644 --- a/docs/main/faq.md +++ b/docs/main/faq.md @@ -94,3 +94,18 @@ npx openmrs start --backend "https://emr-v2.test.icrc.org/" --add-cookie "MRHSes ``` The cookie must be obtained by you and strongly depends on the used backend. + + +## Dev hacks + +### Turn on dev tools + +```js +localStorage.setItem('openmrs:devtools', true) +``` + +### Manually set an importmap override + +```js +localStorage.setItem("import-map-override:@openmrs/esm-form-entry-app", "http://localhost:4200/openmrs-esm-form-entry-app.js"); +``` From de07ebb4633b7a305b13a775d617f7e1d17e2e4e Mon Sep 17 00:00:00 2001 From: Ian <52504170+ibacher@users.noreply.github.com> Date: Tue, 16 Aug 2022 09:22:11 -0400 Subject: [PATCH 10/10] Remove reference to NPM, since we don't use it --- docs/main/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/main/faq.md b/docs/main/faq.md index c544baad4..d85fc3a37 100644 --- a/docs/main/faq.md +++ b/docs/main/faq.md @@ -7,7 +7,7 @@ It's important to keep your working code base current with the latest fixes, lat ### How do I keep my local dev server up to date? -Just pull the repository you want to work on and run `yarn` or `npm install`. +Just pull the repository you want to work on and run `yarn`. That will install the latest dependencies, which includes `openmrs`, which is the tool that runs the dev server.