From 6486a18e394ff8189d5cbc388a07837aa79bbd92 Mon Sep 17 00:00:00 2001 From: Byron Wall Date: Fri, 20 Aug 2021 16:10:09 -0400 Subject: [PATCH 1/9] chore(README.md): add more comprehensive instructions for developing the application kit bundles in readme --- README.md | 81 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 63 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 41396d2e20..fc88b2fc34 100644 --- a/README.md +++ b/README.md @@ -23,13 +23,70 @@ $ npx @commercetools-frontend/create-mc-app my-new-custom-application-project -- ## Developing application-kit packages -Install the dependencies (uses yarn workspaces): +### Initial Installation -```bash -$ yarn -``` +1. Clone this repo + + ```bash + $ git clone https://github.com/commercetools/merchant-center-application-kit.git + ``` + +2. Add necessary environment variables + + > In the vscode file tree or the terminal, navigate to `merchant_center_application_kit/playground`, open `.env.local.template`, and add these values: + + ```bash + MC_API_URL="https://mc-api.europe-west1.gcp.commercetools.com" # for prod + APP_ID="" # can be an empty string for dev + CTP_INITIAL_PRODUCT_KEY= # the name of any project you have access to on prod/stage + ``` + + > In the vscode filetree or the terminal, change `.env.local.template` filename to `.env.local` + +3. Build and run the application kit + + > In a new terminal window, navigate to the project root directory - `/merchant_center_application_kit` - and run: + + ```bash + $ yarn && yarn prebuild && yarn build && yarn build:watch + ``` + + > Confirm that the watch is running successfully, you should see: + + ```bash + > "info @commercetools-frontend/application-shell waiting for changes..." + >... + ``` + +4. Build and run the [playground application](./playground): + + > In a new terminal window, navigate to the project root directory - `/merchant_center_application_kit`, and run: + + ```bash + $ `yarn playground:build && yarn playground:start` + ``` -To run the tests: + > This should open a browser window and the standard merchant cernter login prompt, login using your account, and then the playground should load in the browser if permissions are set correctly (I am unclear on what those perms are or how to set them, so this is completely theoretical on my part at this point) + +### RUNNING THE APP KIT AND PLAYGROUND AFTER INITIAL INSTALLATION + +- Open 2 terminal windows + + - In the first terminal run + + ```bash + $ yarn build:watch + ``` + + - Once the watch process has completed and is listening,in the second terminalm window run + + ```bash + $ yarn playground:start + ``` + + > The playground application consumes the app-kit dependencies as es modules, which means you need to bundle the packages first. We recommend to bundle the packages in watch mode in one terminal process and start the playground app in another terminal process. + +## To run the tests: ```bash $ yarn test @@ -38,7 +95,7 @@ $ yarn test $ yarn test:watch ``` -Build the application bundles +## To Build the application bundles: ```bash $ yarn build @@ -47,18 +104,6 @@ $ yarn build $ yarn build:bundles:watch ``` -Start the [playground application](./playground): - -> NOTE: the playground application consumes the app-kit dependencies's es modules, which means you need to bundle the packages first. We recommend to bundle the packages in watch mode in one terminal process and start the playground app in another terminal process. - -```bash -// Terminal process 1 -$ yarn build:bundles:watch - -// Terminal process 2 -$ yarn playground:start -``` - ## Documentation Please look at the single packages in [`packages` folder](./packages) for documentation specific of each package. From 8d2d1fb9dfc42328d1b7ddebac019c88ad3b6390 Mon Sep 17 00:00:00 2001 From: Byron Wall <87667330+ByronDWall@users.noreply.github.com> Date: Fri, 20 Aug 2021 16:49:38 -0400 Subject: [PATCH 2/9] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fc88b2fc34..51ac16327b 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ $ npx @commercetools-frontend/create-mc-app my-new-custom-application-project -- 2. Add necessary environment variables - > In the vscode file tree or the terminal, navigate to `merchant_center_application_kit/playground`, open `.env.local.template`, and add these values: + > Navigate to `merchant_center_application_kit/playground`, duplicate `.env.local.template`, name the duplicate `.env.local` and add these values: ```bash MC_API_URL="https://mc-api.europe-west1.gcp.commercetools.com" # for prod From fc075101453e1fb3a52da9ae4ce4218241c322ae Mon Sep 17 00:00:00 2001 From: Byron Wall Date: Fri, 20 Aug 2021 18:31:39 -0400 Subject: [PATCH 3/9] chore(README.md): update docs for consistency/readablility --- README.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 51ac16327b..525964d5a6 100644 --- a/README.md +++ b/README.md @@ -41,8 +41,6 @@ $ npx @commercetools-frontend/create-mc-app my-new-custom-application-project -- CTP_INITIAL_PRODUCT_KEY= # the name of any project you have access to on prod/stage ``` - > In the vscode filetree or the terminal, change `.env.local.template` filename to `.env.local` - 3. Build and run the application kit > In a new terminal window, navigate to the project root directory - `/merchant_center_application_kit` - and run: @@ -63,7 +61,7 @@ $ npx @commercetools-frontend/create-mc-app my-new-custom-application-project -- > In a new terminal window, navigate to the project root directory - `/merchant_center_application_kit`, and run: ```bash - $ `yarn playground:build && yarn playground:start` + $ yarn playground:build && yarn playground:start ``` > This should open a browser window and the standard merchant cernter login prompt, login using your account, and then the playground should load in the browser if permissions are set correctly (I am unclear on what those perms are or how to set them, so this is completely theoretical on my part at this point) @@ -80,9 +78,9 @@ $ npx @commercetools-frontend/create-mc-app my-new-custom-application-project -- - Once the watch process has completed and is listening,in the second terminalm window run - ```bash - $ yarn playground:start - ``` + ```bash + $ yarn playground:start + ``` > The playground application consumes the app-kit dependencies as es modules, which means you need to bundle the packages first. We recommend to bundle the packages in watch mode in one terminal process and start the playground app in another terminal process. From 1b53cf8acb901918bea53ee078d6d1db6f079e89 Mon Sep 17 00:00:00 2001 From: Byron Wall Date: Mon, 23 Aug 2021 08:58:17 -0400 Subject: [PATCH 4/9] chore(README.md): fix typos and indentation in readme --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 525964d5a6..2e98cc7ab5 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,8 @@ $ npx @commercetools-frontend/create-mc-app my-new-custom-application-project -- ### RUNNING THE APP KIT AND PLAYGROUND AFTER INITIAL INSTALLATION +> The playground application consumes the app-kit dependencies as es modules, which means you need to bundle the packages first. We recommend to bundle the packages in watch mode in one terminal process and start the playground app in another terminal process. + - Open 2 terminal windows - In the first terminal run @@ -76,14 +78,12 @@ $ npx @commercetools-frontend/create-mc-app my-new-custom-application-project -- $ yarn build:watch ``` - - Once the watch process has completed and is listening,in the second terminalm window run + - Once the watch process has completed and is listening, in the second terminal window run ```bash $ yarn playground:start ``` - > The playground application consumes the app-kit dependencies as es modules, which means you need to bundle the packages first. We recommend to bundle the packages in watch mode in one terminal process and start the playground app in another terminal process. - ## To run the tests: ```bash From b800d3c65a6131a31ad00a158c957663704a3a73 Mon Sep 17 00:00:00 2001 From: Byron Wall Date: Mon, 23 Aug 2021 09:56:01 -0400 Subject: [PATCH 5/9] chore(README.md): it's CTP_INITIAL_PROJECT_KEY, not CTP_INITIAL_PRODUCT_KEY --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2e98cc7ab5..e508dbc572 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ $ npx @commercetools-frontend/create-mc-app my-new-custom-application-project -- ```bash MC_API_URL="https://mc-api.europe-west1.gcp.commercetools.com" # for prod APP_ID="" # can be an empty string for dev - CTP_INITIAL_PRODUCT_KEY= # the name of any project you have access to on prod/stage + CTP_INITIAL_PROJECT_KEY= # the name of any project you have access to on prod/stage ``` 3. Build and run the application kit From 6c40c94a3aa266a494ca9e57959de718e2236905 Mon Sep 17 00:00:00 2001 From: Jonathan Creasman Date: Mon, 30 Aug 2021 10:40:41 -0400 Subject: [PATCH 6/9] chore(README.md): update documentation with another step about removing the fake permission --- README.md | 49 +++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 43 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index e508dbc572..1587fe3661 100644 --- a/README.md +++ b/README.md @@ -56,15 +56,52 @@ $ npx @commercetools-frontend/create-mc-app my-new-custom-application-project -- >... ``` -4. Build and run the [playground application](./playground): +4. Remove fake permission: + > `PERMISSIONS.ViewPlaygroundStateMachines` which is required by playground is a fake permission and you might need to remove it + > in order to be able to run and view the application. You'll need to remove it twice in `custom-application-config.mjs` and once in + > `routes.js` so that `permissions` is just an empty object: - > In a new terminal window, navigate to the project root directory - `/merchant_center_application_kit`, and run: +`custom-application-config.mjs` - ```bash - $ yarn playground:build && yarn playground:start - ``` +```bash + permissions: [PERMISSIONS.ViewPlaygroundStateMachines], + submenuLinks: [ + { + uriPath: 'echo-server', + permissions: [PERMISSIONS.ViewPlaygroundStateMachines], + defaultLabel: '${intl:en:Menu.EchoServer}', + labelAllLocales: [ + { + locale: 'en', + value: '${intl:en:Menu.EchoServer}', + }, + { + locale: 'de', + value: '${intl:de:Menu.EchoServer}', + }, + ], + }, + ], +``` + +`routes.js` + +````bash + const canViewStateMachines = useIsAuthorized({ + demandedPermissions: [PERMISSIONS.ViewPlaygroundStateMachines], + }); + ``` + + +5. Build and run the [playground application](./playground): + +> In a new terminal window, navigate to the project root directory - `/merchant_center_application_kit`, and run: + +```bash +$ yarn playground:build && yarn playground:start +```` - > This should open a browser window and the standard merchant cernter login prompt, login using your account, and then the playground should load in the browser if permissions are set correctly (I am unclear on what those perms are or how to set them, so this is completely theoretical on my part at this point) +> This should open a browser window and the standard merchant cernter login prompt, login using your account, and then the playground should load in the browser if permissions are set correctly (I am unclear on what those perms are or how to set them, so this is completely theoretical on my part at this point) ### RUNNING THE APP KIT AND PLAYGROUND AFTER INITIAL INSTALLATION From 33da242834570686b9f22fe60ecbebdcd901b355 Mon Sep 17 00:00:00 2001 From: Jonathan Creasman Date: Mon, 30 Aug 2021 10:54:27 -0400 Subject: [PATCH 7/9] chore(README.md): update documentation with another step about removing the fake permission --- README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1587fe3661..e0e79e4732 100644 --- a/README.md +++ b/README.md @@ -86,12 +86,11 @@ $ npx @commercetools-frontend/create-mc-app my-new-custom-application-project -- `routes.js` -````bash +```bash const canViewStateMachines = useIsAuthorized({ demandedPermissions: [PERMISSIONS.ViewPlaygroundStateMachines], }); - ``` - +``` 5. Build and run the [playground application](./playground): @@ -99,7 +98,7 @@ $ npx @commercetools-frontend/create-mc-app my-new-custom-application-project -- ```bash $ yarn playground:build && yarn playground:start -```` +``` > This should open a browser window and the standard merchant cernter login prompt, login using your account, and then the playground should load in the browser if permissions are set correctly (I am unclear on what those perms are or how to set them, so this is completely theoretical on my part at this point) From 101b461c23fd06cd26d44e3827cec97d68300d84 Mon Sep 17 00:00:00 2001 From: Jonathan Creasman Date: Mon, 30 Aug 2021 10:56:03 -0400 Subject: [PATCH 8/9] chore(README.md): update documentation with another step about removing the fake permission --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e0e79e4732..792dee833c 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,7 @@ $ npx @commercetools-frontend/create-mc-app my-new-custom-application-project -- 4. Remove fake permission: > `PERMISSIONS.ViewPlaygroundStateMachines` which is required by playground is a fake permission and you might need to remove it > in order to be able to run and view the application. You'll need to remove it twice in `custom-application-config.mjs` and once in - > `routes.js` so that `permissions` is just an empty object: + > `routes.js` so that `permissions`/`demandedPermissions` are just empty objects: `custom-application-config.mjs` From 7fef0fa46d2a213a7a3192c2ac0f37efd000d41b Mon Sep 17 00:00:00 2001 From: Byron Wall Date: Tue, 21 Sep 2021 15:19:45 -0400 Subject: [PATCH 9/9] chore(README.md): update README based on feedback and retrying running playground application from a fresh pull of the repository --- README.md | 101 +++++++++++++++++++++++------------------------------- 1 file changed, 43 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 792dee833c..b0ec3087c8 100644 --- a/README.md +++ b/README.md @@ -25,84 +25,69 @@ $ npx @commercetools-frontend/create-mc-app my-new-custom-application-project -- ### Initial Installation -1. Clone this repo +1. Add necessary environment variables - ```bash - $ git clone https://github.com/commercetools/merchant-center-application-kit.git - ``` - -2. Add necessary environment variables - - > Navigate to `merchant_center_application_kit/playground`, duplicate `.env.local.template`, name the duplicate `.env.local` and add these values: - - ```bash - MC_API_URL="https://mc-api.europe-west1.gcp.commercetools.com" # for prod - APP_ID="" # can be an empty string for dev - CTP_INITIAL_PROJECT_KEY= # the name of any project you have access to on prod/stage - ``` + Navigate to `merchant_center_application_kit/playground`, duplicate `.env.local.template`, name the duplicate `.env.local` and add the necessary values. -3. Build and run the application kit +2. Build and run the application kit - > In a new terminal window, navigate to the project root directory - `/merchant_center_application_kit` - and run: + First build the application. In a new terminal window, navigate to the project root directory and run: ```bash - $ yarn && yarn prebuild && yarn build && yarn build:watch + $ yarn build ``` - > Confirm that the watch is running successfully, you should see: + Once the build is complete, you can run the application in watch mode by running: ```bash - > "info @commercetools-frontend/application-shell waiting for changes..." - >... + $ yarn build:watch ``` -4. Remove fake permission: - > `PERMISSIONS.ViewPlaygroundStateMachines` which is required by playground is a fake permission and you might need to remove it - > in order to be able to run and view the application. You'll need to remove it twice in `custom-application-config.mjs` and once in - > `routes.js` so that `permissions`/`demandedPermissions` are just empty objects: +3. Update Playground Permissions: -`custom-application-config.mjs` + `PERMISSIONS.ViewPlaygroundStateMachines` is not necessary and you might need to remove it in order to be able to view the application. + You'll need to remove it twice in `custom-application-config.mjs` and once in `routes.js` so that `permissions`/`demandedPermissions` are empty arrays: -```bash - permissions: [PERMISSIONS.ViewPlaygroundStateMachines], - submenuLinks: [ - { - uriPath: 'echo-server', - permissions: [PERMISSIONS.ViewPlaygroundStateMachines], - defaultLabel: '${intl:en:Menu.EchoServer}', - labelAllLocales: [ - { - locale: 'en', - value: '${intl:en:Menu.EchoServer}', - }, - { - locale: 'de', - value: '${intl:de:Menu.EchoServer}', - }, - ], - }, - ], -``` + `custom-application-config.mjs` -`routes.js` + ```bash + permissions: [], + submenuLinks: [ + { + uriPath: 'echo-server', + permissions: [], + defaultLabel: '${intl:en:Menu.EchoServer}', + labelAllLocales: [ + { + locale: 'en', + value: '${intl:en:Menu.EchoServer}', + }, + { + locale: 'de', + value: '${intl:de:Menu.EchoServer}', + }, + ], + }, + ], + ``` -```bash - const canViewStateMachines = useIsAuthorized({ - demandedPermissions: [PERMISSIONS.ViewPlaygroundStateMachines], - }); -``` + `routes.js` -5. Build and run the [playground application](./playground): + ```bash + const canViewStateMachines = useIsAuthorized({ + demandedPermissions: [], + }); + ``` -> In a new terminal window, navigate to the project root directory - `/merchant_center_application_kit`, and run: +4. Build and run the [playground application](./playground): -```bash -$ yarn playground:build && yarn playground:start -``` + In a new terminal window, navigate to the project root directory and run: -> This should open a browser window and the standard merchant cernter login prompt, login using your account, and then the playground should load in the browser if permissions are set correctly (I am unclear on what those perms are or how to set them, so this is completely theoretical on my part at this point) + ```bash + $ yarn playground:start + ``` -### RUNNING THE APP KIT AND PLAYGROUND AFTER INITIAL INSTALLATION +### Running the App Kit and Playground After Initial Installation > The playground application consumes the app-kit dependencies as es modules, which means you need to bundle the packages first. We recommend to bundle the packages in watch mode in one terminal process and start the playground app in another terminal process.