Skip to Content

Deploy your first application to Application Frontend using CLI

Beginner
20 min.
HTML5, Beginner, User Interface, Tutorial
Learn how to create and deploy your first "Hello World" application using Application Frontend Service and the afctl CLI, including version management basics.
You will learn
  • How to log in to Application Frontend Service using the CLI.
  • How to create, deploy, and manage a simple “Hello World” application.
  • Understand how application versions work in Application Frontend.
  • Activate and manage different application versions using afctl.
tahelMilsteinTahel MilsteinOctober 23, 2025
Created by
rbrainey
October 23, 2025
Contributors
rbrainey

Prerequisites

  • Step 1

    Before you start, make sure you have the required tools installed locally.

    1. Verify that Node.js (version ≥ 22.6.0) is installed:
    shell
    Copy
    node --version

    Note: If you don’t have Node.js installed, download it from nodejs.org.

    1. Install the Application Frontend CLI (afctl) globally using npm:
    shell
    Copy
    npm install -g @sap/appfront-cli
    1. Verify the installation:
    shell
    Copy
    afctl

    You should see the current CLI version printed in your terminal.

  • Step 2
    1. Navigate to your BTP Cockpit subaccount with Application Frontend Service subscription.
    2. Go to Services > Instances and Subscriptions.
    3. In the Subscriptions table, click on Application Frontend Service.
    4. Copy the URI from the Application Frontend CLI section.
    5. Open your terminal (command line) on your local machine.
    6. Run the following command to log in to Application Frontend Service using the CLI. Replace <URI> with your copied one.
    shell
    Copy
    afctl login --sso --api '<URI>'

    Tip: You can see all supported login options using afctl login --help

    1. A new browser tab will open. Complete the login form with your user credentials if prompted.
    2. (Optional) Validate that you are logged in and your session is active:
    shell
    Copy
    afctl config
    Application Frontend Service Welcome Page
  • Step 3
    1. Create a directory named hello-world.
      This will be your application root directory.
    2. Change your working directory to it:
    shell
    Copy
    cd <path_to_hello_world>
    1. Initialize your application with minimal configuration:
    shell
    Copy
    afctl init


    Tip: Use the -f flag to skip prompts and initialize with default name and version.


    Example: afctl init -f


    This creates:



    • manifest.json — contains application name and version

    • xs-app.json — routing configuration


    1. Create an index.html file with the following content:
    html
    Copy
    <html>
<head>
   <style>
      body {
         display: grid;
         place-content: center;
         position: absolute;
         inset: 0;
      }
   </style>
</head>
<body>
   <h1>Hello World!</h1>
</body>
</html>
    1. Update xs-app.json to set the welcome file to /index.html:
    json
    Copy
    {
   "welcomeFile": "/index.html",
   "routes": [{
      "source": ".*",
      "service": "app-front"
   }]
}
    1. Push your application to Application Frontend Service:
    shell
    Copy
    afctl push
    afctl push example
    1. List deployed applications and their URLs:
    shell
    Copy
    afctl list
    afctl list example
    1. Copy the URL of the hello-world app from the terminal output and open it in your browser. You should see Hello World! displayed in the middle of the page.
  • Step 4

    Application Frontend Service supports multiple versions of the same app to be deployed and accessed simultaneously. This allows previewing new versions before activation and publication under the main URL.

    Let’s update and redeploy your app to see this in action.

    1. Update xs-app.json to add a new route that returns JSON with logged-in user details:
    json
    Copy
    {
   "welcomeFile": "/index.html",
   "routes": [{
      "source": "^/user-api/currentUser$",
      "service": "sap-approuter-userapi"
   }, {
      "source": ".*",
      "service": "app-front"
   }]
}

    Route order matters — Application Frontend processes routes sequentially and uses the first match.

    1. Update index.html to fetch and display the current user's first name:
    html
    Copy
    <html>
<head>
   <style>
      body {
         display: grid;
         place-content: center;
         position: absolute;
         inset: 0;
      }
   </style>
</head>
<body>
   <h1>Loading...</h1>
   <script>
      fetch('./user-api/currentUser', { credentials: 'include' })
         .then(res => res.json())
         .then(user => {
               const h1 = document.querySelector('h1');
               h1.textContent = `Hello, ${user.firstname}!`;
         });
   </script>
</body>
</html>
    1. Update manifest.json to bump the version:
    json
    Copy
    {
   "sap.app": {
      "id": "hello-world",
      "applicationVersion": {
         "version": "2.0.0"
      }
   }
}
    1. Deploy the new version without activating it:
    shell
    Copy
    afctl push -n
    1. List the application versions:
    shell
    Copy
    afctl list hello-world

    You’ll see:

    • One main application URL (stable, never changes)
    • Multiple version-specific URLs for each version
    afctl list hello-world versions
    1. Refresh your browser tab with the main application URL — it still shows version 1.0.0.
    2. Open a new browser tab with the version 2.0.0 URL — you'll see your new greeting version ("Hello, {your name}!").
    3. Activate version 2.0.0:
    shell
    Copy
    afctl activate hello-world 2.0.0
    1. Refresh the main application URL again — it now serves the new version.

    Congratulations! You successfully finished the Hello World Application Frontend exercise.

Back to Top
Back to top