Application shell

Harmony allows to compose business capabilities called Aspects into shell applications via a declarative manifest, reducing integration risks and improving flexibility, reusability, and maintainability.

To create shell application, run:

bit create harmony-platform pied-piper
Copied

Run the platform:

bit run pied-piper --watch
Copied

Compose Harmony Platforms using different domain components

Features are easily toggled on or off within the platform manifest file:

// pied-piper.bit-app.ts
import { HarmonyPlatform } from '@bitdev/harmony.harmony-platform';
import { NodeJSRuntime } from '@bitdev/harmony.runtimes.nodejs-runtime';
import { BrowserRuntime } from '@bitdev/harmony.runtimes.browser-runtime';
import { SymphonyPlatformAspect } from '@bitdev/symphony.symphony-platform';
import { HeaderAspect } from '@bitdev/symphony.aspects.header'; 
import { PeopleAspect } from '@bitdev/symphony.examples.people'; // import the people aspect

/**
 * compose the Pied Piper platform.
 */    
export const PiedPiper = HarmonyPlatform.from({
  name: 'pied-piper',

  /**
   * platform aspect to compose.
   */
  platform: [SymphonyPlatformAspect, {
    name: 'Pied Piper',
    logo: 'https://static.bit.dev/extensions-icons/pied-piper.svg',
  }],

  /**
   * runtimes to support.
   * defaults to browser and nodejs
  */
  runtimes: [
    new BrowserRuntime(),
    new NodeJSRuntime()
  ],

  /**
   * business capabilities to include 
   * in the platform composition
  */
  aspects: [
    HeaderAspect,
    PeopleAspect, // compose the people aspect to the pied piper platform
  ],
});

export default PiedPiper;
Copied

This manifest demonstrates the addition of new functionalities to the platform without applying changing to the core application logic, mitigating risks and enabling control and reuse of capabilities.

The platform aspect is the gateway to your platform, each shell application is required to use a single platform aspect, which acts as the entry for the platform for all runtimes.

The platform property, as demonstrated above, is used as the entry aspect for your platform, using the base SymphonyPlatformAspect.

Create your own platform aspect, basing on Symphony to customize the theme:

bit create platform-aspect pied-platform
Copied

Now edit the platform aspect to control your platform theme and layout:

// 
import { SymphonyPlatformAspect, type SymphonyPlatformBrowser } from '@bitdev/symphony.symphony-platform';
import { PiedTheme } from '@pied/design.pied-theme'; // import your theme as a component
import type { PiedPlatformConfig } from './pied-platform-config.js';

export class PiedPlatformBrowser {
  constructor(
    private config: PiedPlatformConfig,
  ) {}
  
  /**
   * declare the Symphony platform as your dependency
  **/
  static dependencies = [SymphonyPlatformAspect];

  static async provider(
    [symphonyPlatform]: [SymphonyPlatformBrowser],
    config: PiedPlatformConfig,
  ) {
    const piedPlatform = new PiedPlatformBrowser(config, panelSlot);

    // register your custom theme to the Symphony platform.
    symphonyPlatform.registerTheme((props) => {
      return <PiedTheme {...props} />;
    });

    symphonyPlatform.registerLayoutEntry({
      position: 'top',
      component: () => {
        return <Header />;
      } 
    });

    return piedPlatform;
  }
}

export default PiedPlatformBrowser;
Copied

Platform aspect serve as the bedrock for composing unified application shells. To learn more on creating and maintaining platform aspects, head to the create platform documentation.

Aspects are used to stitch a composable architecture into a unified app. They encapsulate the logic required to plugin a certain functionality to a platform including its backend, frontend and other required runtimes.

Create a new aspect:

bit create aspect billing
Copied

Once you've created your Aspect, add it to your application shell manifest to start integrating it with your Harmony platform. For a deeper dive into Aspect creation, check out the Harmony aspects documentation.

The Harmony platform includes the Browser and NodeJS runtimes. By default, when running an Harmony platform it runs all runtimes defined the in the platform using the runtimes property as demonstrated in the above snipped.

You can run specific runtimes of your harmony platform using the following command:

bit run pied-piper -- browser,node
Copied

Both runtimes are optimized for development and production purposes and configurable as needed. By default, they support SSR, HMR (for backend and frontend) and compile to unified binary outputs.

To learn more learn about configuring the NodeJS runtime and the Browser runtime.

When using the official runtimes, upon every snap or tag of your components, a new build would trigger and Ripple CI would build your platform, producing a single unified artifact for each runtime.

You can customize the build or add your own steps as needed by using the build property key in your Harmony platform, referencing it to a build function:

import { HarmonyBuildContext } from '@bitdev/harmony.harmony-platform';

export async function platformBuildFunction(context: HarmonyBuildContext) {
  console.log(context.capsule.path, context.aspects); // echos the platform path and a map aspects composed into the platform.

  return {
    artifacts: []
  }
}
Copied

Find more information on the API available on the build context provided by Harmony. To learn further into the Application context head to the Building apps section.

You can use the following command to test your build:

bit build pied-piper
Copied

Head to the your component directory in the output build root to see your artifacts.

Our official runtimes produce a artifacts for NodeJS, and the Browser runtimes using ESBuild for performance and Webpack for compatibility.

Using Harmony and Ripple CI your platform produces unified build artifact for each of your runtimes, which results in faster performance but also ease deployment and portability of your platform. Using Ripple CI builds are always preserved fast, and teams can independently preview and release their changes to production.

bit tag --message 'releasing my feature' --major
Copied

Using Ripple CI builds are always preserved fast, and teams can independently preview and release their changes to production. Learn more about Harmony deployment.

• Harmony platform example
• Creating Aspects
• Using Runtimes