Add extNamespace Property

Iterate over all your custom Studio Client module POMs: Add a property extNamespace to the configuration of jangaroo-maven-plugin. The extNamespace should specify the longest common ActionScript package name prefix of all classes contained in that package. This is important to keep TypeScript import identifiers concise. Since these already use the npm package name, the common ActionScript package prefix would be redundant.

For example, if your module contains classes with ActionScript fully-qualified names com.acme.studio.foo.Foo, com.acme.studio.foo.bar.FooBar and com.acme.studio.bar.Bar, and the npm package name of the module will be "@acme/studio", setting the common prefix to "com.acme.studio" would result in the import identifiers for the three classes being "@acme/studio/foo/Foo", "@acme/studio/foo/bar/FooBar" and "@acme/studio/bar/Bar", respectively.

Not setting an extNamespace at all would result in long, redundant import identifiers like "@acme/studio/com/acme/studio/foo/bar/FooBar". This is why we require an extNamespace to be set. If you are determined to not set an extNamespace, you can switch off the check in blueprint-parent/pom.xml via the property extNamespaceRequired. Configuring an 'extNamespace' in a module where there are some ActionScript or MXML files whose fully-qualified name does not start with that prefix will result in a build error. You must choose another 'extNamespace' or change the fully-qualified names (rename refactoring) so that they start with the prefix.

Finish this step by committing all added extNamespace properties, so that you can start the next step with a clean state:

$ git add -A
$ git commit -m "Complement extNamespace values"

Enable All Extensions

Enable all extensions, so that disabled extensions with Studio Client modules are converted, too.

$ cd workspace-configuration/extensions

Save current extension enabling state to restore it after conversion:

$ mvn extensions:list -DextensionsFile=extensions.txt

Enable all extensions:

$ mvn extensions:sync "-Denable=*"

Return to the top workspace directory:

$ cd ../..

Patch Studio Client blueprint-parent POM (2107.3 only)

For the Pre-Release, a minor adjustment is necessary to reference the matching CoreMedia core artifacts. In file apps/studio-client/blueprint-parent/pom.xml, complement the XML element <npmDependencyOverrides> (line 523) by the following entry:

  <npmDependencyOverride>
    <search>^(@coremedia/studio-client[.].*):.*$</search>
    <replace>$1:^${cm.studio-client.core.version}-${jangaroo.version}</replace>
  </npmDependencyOverride>

Alternatively, to automate this, you can use the following sed command:

$ sed -i 's#^\(\s*\)</npmDependencyOverride>#\1</npmDependencyOverride>\n\1<npmDependencyOverride>\n\1  <search>^(@coremedia/studio-client[.].*):.*$</search>\n\1  <replace>$1:^${cm.studio-client.core.version}-${jangaroo.version}</replace>\n\1</npmDependencyOverride>#' apps/studio-client/blueprint-parent/pom.xml

Invoke Workspace Conversion Tool

Next, the workspace conversion tool is invoked. It is integrated into the 4.1 version of Jangaroo, and as such invoked through Maven.

Change into the Studio Client workspace:

$ cd apps/studio-client

Invoke the conversion tool:

$ mvn clean install net.jangaroo:jangaroo-maven-plugin:4.1.15:convert-workspace -DskipTests -Dmaven.compiler.migrateToTypeScript -Dmaven.compiler.suppressCommentedActionScriptCode -DprojectExtensionWorkspacePath=$PWD -DconvertedWorkspaceTarget=../studio-client-ts -Djangaroo.version=4.1.15 -Djangaroo.libs.version=4.1.7

Caution

Under Windows, $PWD must be replaced by %CD%.

This runs for a few minutes, generating an npm package under '../studio-client-ts' for each Maven module of your workspace, as well as some global files directly in '../studio-client-ts'.

If the conversion finishes without error, copy the generated workspace over the former Studio Client workspace.

Return to the top workspace directory:

$ cd ../..

Remove module reference to Studio Client Maven project in root POM:

$ sed -i '/<module>apps\/studio-client<\/module>/d' pom.xml

Remove old Studio Client workspace:

$ git restore apps/studio-client
$ git rm -r apps/studio-client/
$ rm -rf apps/studio-client/

Move new Studio Client workspace to its final destination:

$ mv apps/studio-client-ts apps/studio-client

Reformat TypeScript Code

The generated TypeScript code keeps some formatting of the original ActionScript/MXML code. To end up with cleanly formatted code, you should run a "linter" tool. Since this is invoked through pnpm, you must first initialize the workspace, only then you can run the linter:

$ cd apps/studio-client
$ pnpm install
$ pnpm -r run lint --no-bail

The preconfigured linter rules (.eslintrc.js) take care of standardized indentation, spacing before and after certain keywords or tokens, replacing var by let or const as appropriate and consolidating and sorting imports, removing unused ones.

Return to the top workspace directory:

$ cd ../..

Disable Previously Disabled Extensions

After conversion, the enabled/disabled state of your workspace extensions should be restored.

Change into the extensions directory:

$ cd workspace-configuration/extensions

This change applies to 2107.3 only, in newer AMPs, its has already been applied. Extend extension tool configuration in its pom.xml by the apps/studio-client npm workspace root:

$ sed -i -E 's#(\s*)<projectRoot>../..</projectRoot>#\1<projectRoots>\n\1  <projectRoot>../..</projectRoot>\n\1  <projectRoot>../../apps/studio-client</projectRoot>\n\1</projectRoots>#' pom.xml

Alternatively, if you want to change this manually, in the pom.xml, replace the line

<projectRoot>../..</projectRoot>

by the lines

<projectRoots>
  <projectRoot>../..</projectRoot>
  <projectRoot>../../apps/studio-client</projectRoot>
</projectRoots>

Invoke the extensions tool to restore the former state:

$ mvn extensions:sync -Dextensions-maven-plugin.version=4.5.1 -DextensionsFile=extensions.txt

Remove the extensions file, as it is no longer needed:

$ rm extensions.txt

Again, return to the top workspace directory:

$ cd ../..

Save Workspace State

Now would be a good point to save your work by committing it on your v11 upgrade branch.

Add all changed and new files and commit everything:

$ git add -A
$ git commit -m "Conversion of Studio Client to TypeScript"

Build the Converted Workspace

The generated npm workspace should now work and can be built the way a CoreMedia v11 Studio Client is built from now on. Follow the prerequisites given in Section 3.1, “Prerequisites for the Upgrade”. Optionally consult the updated Blueprint Developer Manual and Studio Developer Manual for more information.

Change into the Studio Client workspace:

$ cd apps/studio-client

To build the workspace, run

$ pnpm install
$ pnpm -r run build

Both commands output several messages, should not report (fatal) errors and end with a success message. In case of errors, please double-check you followed the instruction up to this point, check the CoreMedia help center for updates or contact CoreMedia support.

Note

During the build some files might get changed or created, for example, tsconfig.json files. This is normal and expected. Commit these changes into your workspace.

Start Converted Studio Client

Next, try to start your Studio Client from npm for the first time. You need a running 2107 Studio Server to do so, either on your local machine or on any server reachable from your machine.

If Studio Server runs locally, the command to start the local Studio Client server is

$ pnpm -r run start --filter ./apps/main/app

If Studio (Server) runs under some URL https://studio.acme.com/, the command must be complemented like this:

$ pnpm -r run start --filter ./apps/main/app -- --proxyTargetUri=https://studio.acme.com/

In any case, you can now open the given Studio Client URL http://localhost:3000 in a supported browser (Firefox, Microsoft Edge, any Chromium-based browser for development) and you should see a 2107 Studio that looks exactly as before.