diff --git a/client/README.md b/client/README.md index 15fad423884..aec3f0f8622 100644 --- a/client/README.md +++ b/client/README.md @@ -1,19 +1,19 @@ # Client Build System Installs, stages, and builds the client-side scripts necessary for running the -Galaxy webapp. When started through `run.sh` or any other method that utilizes -`scripts/common_startup.sh`, Galaxy will (since 18.09) _automatically_ build -the client as a part of server startup, when it detects changes, unless that +Galaxy web client. When started through `run.sh` or any other method that +utilizes `scripts/common_startup.sh`, Galaxy will (since 18.09) _automatically_ +build the client as a part of server startup when it detects changes unless that functionality is explicitly disabled. -The base dependencies used are Node.js and Yarn. Galaxy now includes these in -the virtual environment, and they can be accessed by activating that with `. -.venv/bin/activate` from the Galaxy root directory. +The base dependencies used are Node.js and Yarn. Galaxy includes appropriate +versions of these in the virtual environment, and they can be accessed by +activating that with `. .venv/bin/activate` from the Galaxy root directory. -If you'd like to install your own dependencies, on OSX the easiest way to get -set up is using `homebrew` and the command `brew install nodejs yarn`. More -information, including instructions for other platforms, is available at -[https://nodejs.org](https://nodejs.org) and +If you'd like to install your dependencies external to Galaxy, on OSX the +easiest way to get set up is using `homebrew` and the command `brew install +nodejs yarn`. More information, including instructions for other platforms, is +available at [https://nodejs.org](https://nodejs.org) and [https://yarnpkg.com/](https://yarnpkg.com). The Galaxy client build has necessarily grown more complex in the past several @@ -27,11 +27,11 @@ directly on Gitter at There are many moving parts to the client build system, but the entry point for most people is the 'client' rule in the Makefile at the root of the Galaxy -repository. Execute the following to perform a complete build suitable for -local development, including dependency staging, style building, script -processing, and bundling. This is a development-specific build which includes -extra debugging features, and excludes several production optimizations made -during the build process. +repository. Execute the following to perform a complete build suitable for local +development, including dependency staging, style building, script processing, +and bundling. This is a development-specific build that includes extra debugging +features and excludes several production optimizations made during the build +process. make client @@ -53,39 +53,31 @@ and these should not be committed. When you're actively developing, it is convenient to have the client automatically rebuild every time you save a file. You can do this using: - make client-watch - -This will first stage client dependencies, initiate a build, and then will -watch for changes in any of the galaxy client source files. When a file is -changed, the client will automatically rebuild, after which you can refresh -your browser to see changes. - -For even more rapid development you can use the webpack development server, -which takes advantage of hot module replacement (HMR). This technique allows -swapping out of javascript modules while the application is running without -requiring a full page reload most of the time, at least in the more modern -parts of the application. - -The command below starts a special webpack dev server after a client -build. - make client-dev-server -This will start up an extra client development server running on port 8081. -Open your browser to http://localhost:8081 (instead of the default 8080 that -Galaxy would run on), and you should see Galaxy like normal. Except now, when -you change client code it'll automatically rebuild *and* reload the relevant -portion of the application for you. Lastly, if you -are running Galaxy at a location other than the default, you can specify a -different proxy target (in this example, port 8000) using the GALAXY_URL -environment variable: +Or, with the package scripts from this `client` directory: + + yarn run develop + +This will start up an extra client development server running on port 8081. Open +your browser to `http://localhost:8081` (instead of the default 8080 that Galaxy +would run on), and you should see Galaxy like normal. Except now, when you +change client code it'll automatically rebuild _and_ reload the relevant portion +of the application for you. Lastly, if you are running Galaxy at a location +other than the default, you can specify a different proxy target (in this +example, port 8000) using the GALAXY_URL environment variable: GALAXY_URL="http://localhost:8000" make client-dev-server -Sometimes you want to run your local UI against a remote Galaxy server. This is also possible, if you enable `CHANGE_ORIGIN` flag +Sometimes you want to run your local UI against a remote Galaxy server. This is +also possible if you set the `CHANGE_ORIGIN` environment variable: CHANGE_ORIGIN=true GALAXY_URL="https://usegalaxy.org/" make client-dev-server +You can also specify a particular port to bind the dev server to: + + WEBPACK_PORT=8083 yarn run develop + ## Running a Separate Server When developing the client it can be helpful to run a local server for the @@ -94,17 +86,22 @@ commands. This command will run galaxy without building the client: make skip-client +Or by setting the following environment variable and running Galaxy however you +prefer: + + GALAXY_SKIP_CLIENT_BUILD=1 ./run.sh + ## Changing Styles/CSS -Galaxy uses Sass for its styling, which is a superset of CSS that compiles down -to regular CSS. Most Galaxy styling source (.scss) files are kept in -`client/src/style/scss`. There are additionally style blocks alongside some Vue -components -- styles that are particular to that individual component and do -not apply site-wide. +Galaxy uses Sass for globally applied styling, which is a superset of CSS that +compiles down to regular CSS. Most Galaxy styling source (.scss) files are kept +in `client/src/style/scss`. Many components will also have local style blocks +containing styles that are particular to that individual component and do not +apply site-wide. On build, the compiled css bundle is served at `/static/style/base.css`. -As mentioned above, `make client` will rebuild styles, as a part of the webpack +As mentioned above, `make client` will rebuild styles as a part of the webpack build. For iterative development, "Watch Mode" rebuilds as described above do include style changes. @@ -142,8 +139,8 @@ directory. This is what happens during a complete client build. During client-side development, it is more convenient to have granular testing options. The various testing scripts are defined inside package.json within the -client folder, and are called with `yarn` as demonstrated in the -following commands. +client folder and are called with `yarn` as demonstrated in the following +commands. This is what CI is going to run, and also what 'make client-test' invokes, executing all the client tests: @@ -154,7 +151,7 @@ You can also bypass qunit and single-run all of the jest tests like so: yarn run jest -Or, if you really want to run just the qunit tests: +Or, if you want to run just the qunit tests: yarn run qunit diff --git a/client/webpack.config.js b/client/webpack.config.js index e4729ccc555..f9493e6ec7c 100644 --- a/client/webpack.config.js +++ b/client/webpack.config.js @@ -250,6 +250,7 @@ module.exports = (env = {}, argv = {}) => { allowedHosts: process.env.GITPOD_WORKSPACE_ID ? "all" : "auto", devMiddleware: { publicPath: "/static/dist", + writeToDisk: true, }, hot: true, port: process.env.WEBPACK_PORT || 8081, diff --git a/doc/source/dev/run_tests_help.txt b/doc/source/dev/run_tests_help.txt index 4e002913339..5e646326027 100644 --- a/doc/source/dev/run_tests_help.txt +++ b/doc/source/dev/run_tests_help.txt @@ -75,8 +75,8 @@ Run a specific selenium test (under Linux or Mac OS X after installing geckodriv Run a selenium test against a running server while watching client (fastest iterating on client tests): ./run.sh & # run Galaxy on 8080 - make client-watch & # watch for client changes - export GALAXY_TEST_EXTERNAL=http://localhost:8080/ # Target tests at server. + make client-dev-server & # watch for client changes + export GALAXY_TEST_EXTERNAL=http://localhost:8081/ # Target tests at server. . .venv/bin/activate # source the virtualenv so can skip run_tests.sh. pytest lib/galaxy_test/selenium/test_workflow_editor.py::TestWorkflowEditor::test_data_input