Create Platform Aspect

The platform aspect provides the API for other aspects to integrate with the main platform and extend it with customizations, features and business capabilities.

Platform Aspect is providing the API to feature teams

Kickstart with Symphony

Symphony provides a ready-to-use platform foundation built with React, GraphQL, and Express.

Leverage Symphony to kickstart your platform development and extend its existing APIs to meet your unique needs. To quickly create a new platform aspect using Symphony as a foundation, utilize the convenient Symphony templates:

// workspace.jsonc
{
    "teambit.generator/generator": {
    "envs": [
      "bitdev.node/node-env",
      "bitdev.react/react-env",
      "bitdev.symphony/symphony-env"
    ]
  },
}
Copied

Create the aspect:

bit create aspect pied-platform
Copied

You can now use the Symphony platform APIs and customize them to your own platform needs. The examples below is demonstrating using the Symphony platform API to customize the platform theme:

import { SymphonyPlatformAspect, type SymphonyPlatformBrowser } from '@bitdev/symphony.symphony-platform';
import { PiedTheme } from '@pied/design.pied-theme';
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} />;
    });

    return piedPlatform;
  }
}

export default PiedPlatformBrowser;
Copied

The example above replaces the default Sparks Theme provided by Symphony with a custom theme. You can checkout the full component examples in the Pied Piper demo.

Create custom platform aspect

If you are looking for a custom stack, or greater level of control over the platform aspect create your own by running the following commands:

bit create platform-aspect wayne-platform
Copied

Use the platform aspect in Harmony platforms as the entry Aspect for the platform.

import { WaynePlatformAspect } from '@wayne/wayne.wayne-platform';
import { PeopleAspect } from '@wayne/people.people';

export const WaynePlatform = HarmonyPlatform.from({
  name: 'wayne-platform',

  platform: WaynePlatformAspect,

  aspects: [
    PeopleAspect
  ]
});

export default WaynePlatform;
Copied

Run the server API

Use the NodeJS runtime to run your servers and return the port and URL to be wired to your other runtimes.

export class WaynePlatformNode {
  run() {
    console.log('hello my platform!');

    // return the server information to be wired to other runtimes.
    return {
      appName: 'wayne-server',
      port: 5001,
      url: 'http://localhost:5001'
    };
  }

  static async provider() {
    return new WaynePlatformNode();
  }
}
Copied

It is recommended to expose a slot API for registering backend services and orchestrating a micro service architecture. See Wayne Platform example to learn how to use a micro service architecture in Harmony.

Render the UI

Use the Browser runtime to render UI for the web in SSR and CSR:

import { hydrateRoot } from 'react-dom/client';

export class WaynePlatformBrowser {

  get apiGatewayUrl() {
    // Backend API endpoint is wired as an env variable. 
    return process.env.API_GATEWAY;
  }

  // render the UI in the browser.
  render() {
    // CSR rendering logic. 
  }

  renderSsr() {
    // SSR rendering logic.    
  }

  static async provider() {
    return new WaynePlatformBrowser();
  }
}
Copied

You can create new runtimes for Harmony by implementing a Runtime. Learn more on implementing Harmony runtimes.

Routing

The default Platform aspect template includes Routing using React Router and allowes for other Aspects to plugin a route using the registerRoute method.

Backend services

This is often useful to expose a slot API for Aspects to plugin new backend servers and route them using an API gateway. The default Platform Aspect is using Apollo GraphQL to allow for other aspect to plugin a GraphQL API server using the registerBackendServer API method.

Testing Platform Aspects

Platform Aspects are tested just like every other Aspect. Learn more on testing Aspects.

Fork Symphony

You can fork Symphony as a jump start to building your own platform. Run the following command to fork your own platform:

bit fork bitdev.symphony/symphony-platform acme-platform
Copied