Update frontend contribution doc with start proxy instructions and np…

…m daily practices (#3142)

frontend/README.md

@@ -1,45 +1,58 @@
 # Kubeflow Pipelines Management Frontend
 
-## Develop
+## Tools you need
 
-You need `npm`, install dependencies using `npm ci` (`npm ci` makes sure your
-installed dependencies have the exact same version as others).
+You need `node v12` and `npm`.
+Recommend installing `node` and `npm` using https://github.com/nvm-sh/nvm. After installing nvm,
+you can install `node v12` by `nvm install 12`.
 
-If you made any changes to protos (see backend/README), you'll need to
-regenerate the Typescript client library from swagger. We use
-swagger-codegen-cli@2.4.7, which you can get
-[here](https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.7/).
-Make sure the jar file is somewhere on your path with the name
-swagger-codegen-cli.jar, then run `npm run apis`.
+## Node and npm daily usages
 
-You can then do `npm start` to run a static file server at port 3000 that
-watches the source files. This also adds a mock backend api server handler to
-webpack-dev-server so it can serve basic api calls, as well as a mock
-webserver to handle the Single Page App requests, which redirects api
-requests to the aforementioned mock api server. For example, requesting the
-pipelines page sends a fetch request to
+Install dependencies by `npm ci`. It makes sure your installed dependencies have
+the exact same version as others, comparing to `npm install`. (Usually, you just
+need to run this once, but after others updated package-lock.json, you need to
+run `npm ci` again to get package updates.)
+
+Run `npm install --save <package>` (or `npm i -S <package>` for short) to install runtime dependencies.
+Run `npm install --save-dev <package>` (or `npm i -D <package>` for short) to install dev dependencies.
+
+You can learn more about npm in https://docs.npmjs.com/about-npm/.
+
+## Start frontend development server
+
+You can then do `npm start` to run a webpack dev server at port 3000 that
+watches the source files. It also redirects api requests to localhost:3001. For
+example, requesting the pipelines page sends a fetch request to
 http://localhost:3000/apis/v1beta1/pipelines, which is proxied by the
-webserver to the api server at http://localhost:3001/apis/v1beta1/pipelines,
-which will return the list of pipelines currently defined in the mock
-database.
+webserver to http://localhost:3001/apis/v1beta1/pipelines,
+which should return the list of pipelines.
+
+Follow the next section to start an api mock/proxy server to let localhost:3001
+respond to api requests.
 
-### Using a real cluster as backend
+## Start api mock/proxy server
 
-#### Common steps
+### Api mock server
 
-1. First configure your `kubectl` to talk to your KFP standalone cluster.
-2. `npm start` to start a webpack dev server, it is configured to proxy api requests to localhost:3001. The following step will start a proxy that handles api requests proxied to localhost:3001.
+This is the easiest one to start, but it does not support all apis during
+development.
 
-#### Special step that depend on what you want to do
+Run `npm run mock:api` to start a mock backend api server handler so it can
+serve basic api calls. 
 
-| What to develop?        | Who handles API requests? | Script to run                                                  | Extra notes                                                        |
-| ----------------------- | ------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------ |
-| Client UI               | standalone deployment     | `NAMESPACE=kubeflow npm run start:proxy-standalone`            |                                                                    |
-| Client UI + Node server | standalone deployment     | `NAMESPACE=kubeflow npm run start:proxy-standalone-and-server` | You need to rerun the script every time you edit node server code. |
+### Proxy to a real cluster
 
-TODO: figure out and document how to use a Kubeflow deployment to develop UI.
+This requires you already have a real KFP cluster, you can proxy requests to it.
 
-**Production Build:**
+Before you start, configure your `kubectl` to talk to your KFP cluster.
+
+Then it depends on what you want to develop:
+| What to develop?        | Script to run                                                  | Extra notes                                                        |
+| ----------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------ |
+| Client UI               | `NAMESPACE=kubeflow npm run start:proxy`            |                                                                    |
+| Client UI + Node server | `NAMESPACE=kubeflow npm run start:proxy-and-server` | You need to rerun the script every time you edit node server code. |
+
+## Production Build
 You can do `npm run build` to build the frontend code for production, which
 creates a ./build directory with the minified bundle. You can test this bundle
 using `server/server.js`. Note you need to have an API server running, which
@@ -49,7 +62,7 @@ you can then feed its address (host + port) as environment variables into
 The mock API server and the mock webserver can still be used with the
 production UI code by running `npm run mock:api` and `npm run mock:server`.
 
-**Container Build:**
+## Container Build
 
 You can also do `npm run docker` if you have docker installed to build an
 image containing the production bundle and the server pieces. In order to run
@@ -69,18 +82,12 @@ To understand more what prettier is: [What is Prettier](https://prettier.io/docs
 
 - For vscode, install the plugin "Prettier - Code formatter" and it will pick
   this project's config automatically.
-  Recommend setting the following in [settings.json](https://code.visualstudio.com/docs/getstarted/settings#_settings-file-locations) for vscode to autoformat + organize import on save.
+  Recommend setting the following in [settings.json](https://code.visualstudio.com/docs/getstarted/settings#_settings-file-locations) for vscode to autoformat on save.
   ```
   "[typescript]": {
-      "editor.codeActionsOnSave": {
-          "source.organizeImports": true,
-      },
       "editor.formatOnSave": true,
   },
   "[typescriptreact]": {
-      "editor.codeActionsOnSave": {
-          "source.organizeImports": true,
-      },
       "editor.formatOnSave": true,
   },
   ```
@@ -94,3 +101,12 @@ Run `npm run format`.
 
 If there's some code that you don't want being formatted by prettier, follow
 guide [here](https://prettier.io/docs/en/ignore.html). (Most likely you don't need this.)
+
+## Api client code generation
+
+If you made any changes to protos (see backend/README), you'll need to
+regenerate the Typescript client library from swagger. We use
+swagger-codegen-cli@2.4.7, which you can get
+[here](https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.7/).
+Make sure the jar file is somewhere on your path with the name
+swagger-codegen-cli.jar, then run `npm run apis`.

frontend/package.json

@@ -48,8 +48,8 @@
     "mock:api": "ts-node-dev -O '{\"module\": \"commonjs\"}' mock-backend/mock-api-server.ts 3001",
     "mock:server": "node server/dist/server.js build",
     "postinstall": "cd ./server && npm ci && cd ../mock-backend && npm ci",
-    "start:proxy-standalone": "./start-proxy-standalone.sh",
-    "start:proxy-standalone-and-server": "./start-proxy-standalone-and-server.sh",
+    "start:proxy": "./scripts/start-proxy.sh",
+    "start:proxy-and-server": "./scripts/start-proxy-and-server.sh",
     "start": "react-scripts-ts start",
     "sync-backend-sample-config": "node scripts/sync-backend-sample-config.js",
     "test": "react-scripts-ts test --env=jsdom",