Moving HTML5 Applications To Application Frontend ...

This blog walks you through the changes you need to make when transitioning an MTA-based HTML5 application from the hosting services of HTML5 Repository and the managed approuter to the new Application Frontend service, and explains why the transition is worthwhile.

A Quick Recap: What Is Application Frontend?

Application Frontend is a SaaS application on SAP BTP for hosting, serving, and operating frontend applications. It was introduced as part of the SAP Build release and is designed to be a single point of entry for UI application management — bringing back the simplicity from the Neo HTML5 Runtime to the multi-cloud environment.

Check out this introduction blog for more details Introducing Application Frontend Service.

Key benefits of using Application Frontend

Versioning: Neo-style multi-version support with multiple active versions and a configurable default. You can test a new version in production without disrupting existing users.
Faster deployments: Deployments complete in seconds via CLI or API, ideal for fast dev test cycles.
Full application lifecycle control: Manage, monitor, and operate applications from the BTP Cockpit, CLI, or API — with observability and fine-grained control per application.

Simpler MTA setup: The destination-content module and all its service key scaffolding disappear — fewer modules, fewer service keys, and less configuration to maintain.
Visibility into used services: A “binding-like” behavior provides a clear view from the cockpit or CLI into the dependencies of your application.

And many other features that make your development experience easier.

Should you fancy using Application Frontend and like to move an existing application already deployed to the HTML5 Repository to Application Frontend, here are the steps to do it.

What Changes Are Needed?

Moving your application from HTML5 Repo to Application Frontend requires some changes in the application deployment and routing descriptors – the mta.yaml and xs-app.json.

The main change is in the mta.yaml which becomes much simpler – Application Frontend eliminates the need for instance-level destinations for storing credentials.

With HTML5 Repo, credentials for required services such as XSUAA, Workflow, and other services had to be exposed as destinations so the managed approuter could reach them. This required a dedicated module that created service keys and mapped them to instance-level destinations (module myApp-destination-content in the example below).

With Application Frontend, service credentials are stored directly within the application. You bind your services (XSUAA, Workflow, etc.) directly to the app-content module, and Application Frontend takes care of the rest.

The result: fewer modules, fewer service keys, and less configuration to maintain.

Note: the following example refers to an older work mode used with HTML5 repository service. If you already use the newer methodology where credentials destination is not used anymore, you can skip steps 1 and 2.

Your Current MTA Descriptor (html5-apps-repo)

Let's look at a sample MTA descriptor for deploying an HTML5 application. The application uses a destination to a backend service, an XSUAA instance, and the Workflow service.

_schema-version: "3.2"
ID: myApp
version: 0.0.1

modules:
  # Module that creates instance-level destinations with credentials
  - name: myApp-destination-content
    type: com.sap.application.content
    requires:
      - name: myApp-destination
        parameters:
          content-target: true
      - name: myApp-html-repo-host
        parameters:
          service-key:
            name: myApp-html-repo-host-key
      - name: myApp-xsuaa
        parameters:
          service-key:
            name: myApp-xsuaa-key
      - name: myApp-workflow-service
        parameters:
          service-key:
            name: myApp-workflow-key
    parameters:
      content:
        instance:
          destinations:
            # Destination with app-host credentials
            - Name: myApp-html-repo-host-destination
              ServiceInstanceName: myApp-html5-app-host-service
              ServiceKeyName: myApp-html-repo-host-key
              sap.cloud.service: business.solution.service
              Authentication: OAuth2UserTokenExchange
            # Destination with XSUAA credentials
            - Name: myApp-xsuaa-destination
              ServiceInstanceName: myApp-xsuaa-service
              ServiceKeyName: myApp-xsuaa-key
              sap.cloud.service: business.solution.service
            # Destination pointing to Workflow reuse service instance
            - Name: myApp-workflow-destination
              Authentication: OAuth2UserTokenExchange
              ServiceInstanceName: myApp-workflow-service
              ServiceKeyName: myApp-workflow-key
          existing_destinations_policy: ignore
    build-parameters:
      no-source: true

  # Module that deploys HTML5 application content
  - name: myApp-app-content
    type: com.sap.application.content
    path: .
    requires:
      - name: myApp-html5-repo-host
        parameters:
          content-target: true
    build-parameters:
      build-result: resources
      requires:
        - artifacts:
            - html5-app.zip
          name: html5-app
          target-path: resources/

  # HTML5 application module
  - name: html5-app
    type: html5
    path: html5-app
    build-parameters:
      build-result: dist
      builder: custom
      commands:
        - npm install
        - npm run build:cf
      supported-platforms: []

resources:
  # Destination service instance 
  - name: myApp-destination
    type: org.cloudfoundry.managed-service
    parameters:
      config:
        HTML5Runtime_enabled: true
        init_data:
          instance:
            destinations:
              # Destination to the backend service
              - Authentication: NoAuthentication
                Name: backend-api
                ProxyType: Internet
                Type: HTTP
                URL: https://backend-api.example.com
            existing_destinations_policy: update
        version: 1.0.0
      service: destination
      service-plan: lite

  # HTML5 Repo app-host service instance
  - name: myApp-html5-repo-host
    type: org.cloudfoundry.managed-service
    parameters:
      service: html5-apps-repo
      service-plan: app-host

  # XSUAA service instance
  - name: myApp-xsuaa
    type: org.cloudfoundry.managed-service
    parameters:
      path: ./xs-security.json
      service: xsuaa
      service-plan: application

  # Workflow reuse service instance
  - name: myApp-workflow-service
    type: org.cloudfoundry.managed-service
    parameters:
      service: workflow
      service-plan: lite

parameters:
  deploy_mode: html5-repo

Here are the needed Steps

1. Delete the Entire `myApp-destination-content` Module

With app-front, credentials for dependent services are stored directly with the application, so this destination is no longer needed.

Action: Remove the myApp-destination-content module completely.

2. Update the `myApp-app-content` Module

The app-content module now needs to:

Bind directly to the destination, XSUAA, and Workflow service instances (no longer via destinations)
Reference the app-front service instead of html-repo-host as the content target
Keep everything else unchanged (build parameters, artifact dependencies)

Current `myApp-app-content`:

requires:
  - name: myApp-html-repo-host
    parameters:
      content-target: true

Update to:

requires:
  - name: myApp-xsuaa
  - name: myApp-workflow
  - name: myApp-destination-service  
  - name: myApp-app-front
    parameters:
      content-target: true

3. Replace the `html5-repo-host` Resource

The HTML5 repository service (html5-apps-repo) is replaced with the Application Frontend service (app-front).

Current resource:

- name: myApp-html5-repo-host
  type: org.cloudfoundry.managed-service
  parameters:
    service: html5-apps-repo
    service-plan: app-host

Replace with:

- name: myApp-app-front
  type: org.cloudfoundry.managed-service
  parameters:
    service: app-front
    service-plan: developer

4. Remove `HTML5Runtime_enabled` from Destination Service

The destination service is still needed to point to the backend, but the HTML5Runtime_enabled: true flag is no longer required.

Changed destination config:

config:
#  HTML5Runtime_enabled: true   ** This line is not needed anymore **
  init_data:
    instance:
      destinations:
        - Authentication: NoAuthentication
          Name: backend-api
          ProxyType: Internet
          Type: HTTP
          URL: https://backend-api.example.com
        existing_destinations_policy: update
  version: 1.0.0

5. Update xs-app.json

The xs-app.json file inside your HTML5 application controls how routes are handled. Routes that serve static content reference the hosting service by name — this needs to change from html5-apps-repo-rt to app-front.

Before:

{
  "source": "^/index.html$",
  "target": "/index.html",
  "service": "html5-apps-repo-rt",
},
{
  "source": "^(.*)$",
  "target": "$1",
  "service": "html5-apps-repo-rt"
}

Update to:

{
  "source": "^/index.html$",
  "target": "/index.html",
  "service": "app-front",
},
{
  "source": "^(.*)$",
  "target": "$1",
  "service": "app-front"
}

Action: Replace every instance of “service”: “html5-apps-repo-rt” with “service”: “app-front”. Routes pointing to backend destinations are unaffected.

That it!! No other changes are needed.

What Stays the Same

The following require no changes:

The HTML5 application module itself (html5-app) build commands, paths, etc.
XSUAA service instance configuration
Workflow service instance configuration
Backend destinations that do not carry a sap.cloud.service attribute

To Sum Up

Moving an existing UI application from HTML5 Repo to AppFront is a simple, straightforward process that will not impact the business logic of your application.

Note that the URL of the application will change, so bookmarks will have to be updated. If your application is integrated into an SAP Build Work Zone site, these settings will have to be updated as well.

The New MTA Descriptor (app-front)

For reference, here is the full descriptor after applying all required changes.

_schema-version: "3.2"
ID: myApp-id
version: 0.0.1

modules:
  # Module that deploys HTML5 application content
  - name: myApp-app-content
    type: com.sap.application.content
    path: .
    requires:
      - name: myApp-xsuaa
      - name: myApp-workflow
      - name: myApp-app-front
        parameters:
          content-target: true
    build-parameters:
      build-result: resources
      requires:
        - artifacts:
            - html5-app.zip
          name: html5-app
          target-path: resources/

  # HTML5 application module
  - name: html5-app
    type: html5
    path: html5-app
    build-parameters:
      build-result: dist
      builder: custom
      commands:
        - npm install
        - npm run build:cf
      supported-platforms: []

resources:
  - name: myApp-backend-destination
    type: org.cloudfoundry.managed-service
    parameters:
      config:
        init_data:
          instance:
            destinations:
              # Backend destination without sap.cloud.service
              - Authentication: NoAuthentication
                Name: backend-api
                ProxyType: Internet
                Type: HTTP
                URL: https://backend-api.example.com
            existing_destinations_policy: update
        version: 1.0.0
      service: destination
      service-plan: lite

  # HTML5 app-front service instance
  - name: myApp-app-front
    type: org.cloudfoundry.managed-service
    parameters:
      service: app-front
      service-plan: developer

  # XSUAA service instance
  - name: myApp-xsuaa
    type: org.cloudfoundry.managed-service
    parameters:
      path: ./xs-security.json
      service: xsuaa
      service-plan: application

  # Workflow reuse service instance
  - name: myApp-workflow-service
    type: org.cloudfoundry.managed-service
    parameters:
      service: workflow
      service-plan: lite

Source link