7. Developing with the Studio Client Workspace

This workspace is based on TypeScript and the package manager pnpm. The following sections describe how to build and develop with it.

Required Tools

You have to install the following tools to build the workspace:

Node.js

You need Node.js in a supported version (see http://bit.ly/cmcc-12-supported-environments) to build the studio-client workspace. See https://nodejs.org/en/

pnpm

While Node.js provides a build-in package manager for npm packages, alternative package managers are also supported. CoreMedia workspaces use an alternative package manager called pnpm. See https://pnpm.io/installation for details or install it directly via npm (replace <VERSION> with the supported pnpm version, for example 8.1, see http://bit.ly/cmcc-12-supported-environments):

npm install -g pnpm@<VERSION>

Sencha Cmd

Sencha Cmd in a supported version (see http://bit.ly/cmcc-12-supported-environments) is required for building the Studio client applications and JooUnit tests. See https://www.sencha.com/products/extjs/cmd-download/

Note

Make sure that all these tools are available in your PATH variable.

Sencha Cmd does not support Java 17. Please either use a Sencha Cmd installation with an included JRE (currently only offered for Windows and macOS) or make sure to set the environment variable INSTALL4J_JAVA_HOME_OVERRIDE to a JRE 11 installation.

Configuration

Your pnpm client first needs to be authenticated to the CoreMedia npm registry in order to download CoreMedia packages (see Section 3.1, “Prerequisites” in Blueprint Developer Manual ).

Building the Workspace

Once you have installed and configured the required tools, you can build the Studio client packages. Invoke the following commands from the apps/studio-client folder of your Blueprint workspace:

pnpm install
pnpm -r run build

The install command will download all dependencies required to actually build the workspace while the build command will compile all the sources into the corresponding output folders. In case the build fails with any Sencha Cmd specific error make sure to check the notes above.

Starting the Studio Client

After the build was successful start the Studio client using the start script:

cd global/studio
pnpm run start

This requires a local Studio server running at http://localhost:41080. In order to provide a custom location for the studio server, you can provide a custom URL to the start script:

pnpm run start --proxyTargetUri=http://some-host/studio

For a list of all available parameters call the start script with --help.

The start script will output a message including the URL under which you can access the studio-client from the browser for local development.

Rebuild on changes

If you made file changes you will need to call the build script again. In most cases, you only need to build the package which contains the changed files. The whole workspace has only to be rebuild after checking out a new branch, for example.

Build a single package by running the build script from the folder of the package:

cd apps/main/blueprint-forms
pnpm run build

Note

There also is a way to build a package and/or its dependencies/dependents with a single command. Please consult https://pnpm.io/filtering for further information. The following chapters in this manual might make use of these filters.

Keep in mind that building a package with the build script does not automatically clean up deleted files in the output folders. To clean up the output folder of a package, use the clean script:

cd apps/main/blueprint-forms
pnpm run clean

However, depending on what has been changed it might be necessary to rebuild all packages or at least the package including its dependents. Typical situations are:

Most changes can be immediately seen after a browser reload. However, general changes in configuration and dependencies (including the workspace) require rerunning the start script.

Automatically rebuild on changes

All Jangaroo projects also have a watch script which can be used to automatically track changes inside a package (and optionally its dependencies inside the workspace). You can start the watch task for a single package using the following command:

cd apps/main/blueprint-forms
pnpm run watch

This will automatically rebuild the project if any changes have been detected inside the src or sencha folders.

By using the command line parameter --skipInitialBuild you can prevent that the package is build initially, for example, if you have already built the whole workspace and did not make any changes yet.

The watch script can not only track changes inside a single package but also track changes of its dependencies inside the workspace if the parameter --recursive is passed. As the watch task only knows about Jangaroo projects this however is limited to packages containing a Jangaroo project. The watcher will not trigger any custom build scripts.

The most common case is watching the apps packages in global/studio including its dependencies. To avoid rebuilding the whole dependency tree first, the --skipInitialBuild comes in handy here:

cd global/studio
pnpm run watch --recursive --skipInitialBuild

Note

As a convenience feature, the watcher will recompile the CSS of a (base) app contained inside the workspace if any changes to SCSS files inside sencha/sass have been detected. This comes in handy when making many changes to styling as building the CSS of an Ext JS application requires only a fraction of the normal build time.

As the watch task itself can be configured by the jangaroo.config.js file and it is contained inside a dependency it has some limitations:

Running tests

Tests are not automatically run when triggering the build script. You need to invoke the test script provided in every package containing Jest tests and/or JooUnit tests. To run all the tests of all packages in the workspace use the following command:

pnpm -r run test

If a package does not contain a test script it will be ignored.

The execution will immediately exit with a non-zero exit code as son as any test error occurs. In case you want to execute all tests, regardless of previous failures, you can pass the parameter --testFailureExitCode to the test:

pnpm -r run test --testFailureExitCode 0

Test setup failures will still lead to a non-zero exit code in that case. The only difference is that the execution will not be interrupted because there were test failures. This might become handy in CI environments to collect the JUnit test reports every package provides in the build folder.

The Jest test report can be found in build/jest/junit.xml and the JooUnit test report can be found in build/joounit/junit.xml accordingly.

IDE Support

One of the rationales behind using TypeScript is to make the good parts of static typing, such as getting reliable and useful IDE support, available for the dynamic language JavaScript. This section shows how to properly configure syntax assist for JetBrains products but also for Microsoft Visual Studio Code.

JetBrains

Recent versions of the JetBrains IDEs IntelliJ IDEA Ultimate and WebStorm have built-in support for TypeScript and JavaScript development. Make sure that you activate the plugin providing support for TypeScript and JavaScript. It might also be handy to activate support for Node.js.

Also make sure that the setting Node interpreter is properly set up in both plugins and points to Node.js in the supported version (see http://bit.ly/cmcc-12-supported-environments).

The TypeScript path of the corresponding plugin should be set to apps/studio-client/node_modules/.pnpm/typescript@x.x.x/node_modules/typescript where x.x.x is the TypeScript version used inside the workspace (usually, there is only one). This folder is created after pnpm install has been called for the first time.

Note

In case the IDE support does not properly work it might help to restart the TypeScript support. Usually this can be done via the footer toolbar by clicking TypeScript x.x.x and clicking Restart TypeScript Service.

If the footer item does not exist or does not show a version this usually indicates that something is not properly configured.

Visual Studio Code

In contrast to JetBrains products, this IDE is available for free and more lightweight by sacrificing some features for code assist (for example, more complex code refactoring).

Make sure to add/enable at least the extensions for JSON, Npm and TypeScript.

Note

Just like when using JetBrains products it might be helpful to restart the TypeScript support if the IDE's does not work as expected. You can achieve this by opening the Command Palette from the View menu item and executing the TypeScript: Restart TS Server command.