Code Monkey home page Code Monkey logo

frontend-discovery's Introduction

Frontend Discovery

This repository contains schema, documentation and RFCs for the Frontend Discovery project.

Summary

The aim of this project is to define and drive adoption of a frontend discovery pattern, with a primary focus on client-side rendered (CSR), server-side rendered (SSR) and edge-side rendered (ESR) micro-frontends. The frontend discovery pattern improves the development experience when developing, testing, and delivering micro-frontends by making use of a shareable configuration describing the entry point of micro-frontends, as well as additional metadata that can be used to deploy in every environment safely.

Motivation

There are many client-side rendering frameworks and libraries for building micro-frontends such as Single SPA, Module Federation, Luigi Framework and more. They are all doing a great job composing micro-frontends in a single view (horizontal split) or as standalone artifact loaded by an application shell (vertical split), facilitating the development experience and provide utilities for overcoming common challenges during the development of a micro-frontends application. However, currently none of these frameworks address micro-frontends discoverability. In distributed architectures like micro-services, there are mechanisms to consume a specific service without knowing its endpoint URL. The service discovery pattern allows to associate a unique identifier to a URL that is managed by the service team who manage the service. In this way, the team can change the underline infrastructure and even the service URL, without the need to coordinate with all the consumer of their API. The service team is decoupled from the rest of the consumers and it has the capability to work autonomously reducing the time to market of their implementations.

This is a common challenge for distributed systems on the backend, but so far there isn't an alternative for distributed systems on the frontend. That's the reason why we want to introduce a micro-frontends discovery pattern.

This gap in client-side rendering implementations is a common challenge for every micro-frontends application and every company is solving in different ways: injecting the URL during the CI pipeline, creating browsers extensions for allowing developers to quickly test their micro-frontends autonomously and so on. However, we didn't find a consistent way to look at the problem that is not only enabling to retrieve the entry point of a micro-frontend but also improving the deployment process with mechanisms such as canary release, blue-green deployment or role-based deployment.

The goal of this project is defining a the discoverability schema, and provide examples and foundational libraries in Vanilla JavaScript that can abstract the complexity and be easily integrated with all the most popular micro-frontend frameworks.

Discoverability Schema

The schema covers the following use cases:

  • provide a list of micro-frontends entrypoints in form of URLs
  • introduce deployment mechanisms such as canary releases and blue-green deployment for applications
  • allow extensibility for different use cases specific to company (e.g.: country-based deployment) and framework specific implementations

This is an example of the latest schema implementation:

{
  "schema": "https://mfewg.org/schema/v1-pre.json",
  "microFrontends": {
    "@my-project/catalog": [
      {
        "url": "https://static.website.com/my-catalog-1.3.5.js",
        "fallbackUrl": "https://alt-cdn.com/my-catalog-1.3.5.js",
        "metadata": {
          "integrity": "e0d123e5f316bef78bfdf5a008837577",
          "version": "1.3.5"
        },
        "extras": {
          "modulefederation": {
            "prefetch": ["@my-project/myaccount"]
          }
        }
      }
    ],
    "@my-project/myaccount": [
      {
        "url": "https://static.website.com/my-account-1.2.2.js",
        "fallbackUrl": "https://alt-cdn.com/my-account-1.2.2.js",
        "metadata": {
          "integrity": "e0d123e5f316bef78bfdf5a008837577",
          "version": "1.2.2"
        },
        "deployment": {
          "traffic": 30,
          "default": false
        }
      },
      {
        "url": "https://static.website.com/my-account-2.0.0.js",
        "fallbackUrl": "https://alt-cdn.com/my-account-2.0.0.js",
        "metadata": {
          "integrity": "e0d123e5f316bef78bfdf5a008837577",
          "version": "2.0.0"
        },
        "deployment": {
          "traffic": 70,
          "default": true
        }
      }
    ]
  }
}

Roadmap

  • March 2022 to April 2022: Formed a group of core contributors consisting of Joel Denning, Luca Mezzalira, Matteo Figus and Zack Jackson and defined motivation and project goals
  • April 2022 to June 2022: Worked on the first candidate for the discovery Schema
  • August 2022: Open Github Repository for public consumption, discussion and allow creation of RFCs
  • Q4 2022 until Q1 2023: Creation of JavaScript Vanilla Library and Framework specific POCs to validate schema v1 candidate, add documentation, add code examples and iterate on schema after gathering feedback from community

Contributing with RFCs

What is an RFC?

An RFC is a document that proposes a change to the project. Request for Comments means a request for discussion and oversight about the future of the project from maintainers, contributors and users.

RFC Process

This team is still defining the best process to work on RFCs. For the time being, everyone can create an RFC proposal about the project, the JSON schema and the roadmap by opening an Issue in Github.

Security issue notifications

If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public github issue.

Licensing

See the LICENSE file for our project's licensing. We will ask you to confirm the licensing of your contribution.

We may ask you to sign a Contributor License Agreement (CLA) for larger changes.

frontend-discovery's People

Contributors

amazon-auto avatar lucamezzalira avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

frontend-discovery's Issues

[RFC][Proposal] Add an optional field for type definitions

Summary

This proposals intent is to provide a field called types to hold the URL to the Typescript type definitions of the micro-frontend modules/applications to enable further integrations with various tools to offer type safety at different stages of the software development.

Motivation

A micro-frontend(MF) module/application could expose interface for 3rd parties to consume, such as component interface, module exports, etc. Introducing breaking changes to the interfaces could be a big challenge if the MF modules/applications are shared by different teams/organizations. It requires extra communication and testing efforts.

Design

An optional field types will be added to the current schema which is the URL to the generated type definitions of the MF modules/applications.

Example:

{
  "schema": "https://mfewg.org/schema/v1-pre.json",
  "microFrontends": {
    "@my-project/myaccount": [
      {
        "url": "https://static.website.com/my-account-1.2.2.js",
        "fallbackUrl": "https://alt-cdn.com/my-account-1.2.2.js",
+       "types": "https://static.website.com/my-account-types.1.2.2.tgz",
        "metadata": {
          "integrity": "e0d123e5f316bef78bfdf5a008837577",
          "version": "1.2.2"
        },
        "deployment": {
          "traffic": 30,
          "default": false
        }
      },
      {
        "url": "https://static.website.com/my-account-2.0.0.js",
        "fallbackUrl": "https://alt-cdn.com/my-account-2.0.0.js",
+       "types": "https://static.website.com/my-account-types.2.0.0.tgz",
        "metadata": {
          "integrity": "e0d123e5f316bef78bfdf5a008837577",
          "version": "2.0.0"
        },
        "deployment": {
          "traffic": 70,
          "default": true
        }
      }
    ]
  }
}

Use cases

Used by code editor plugins

With such plugin, code editor will download the type definition automatically. This offers a better developer experience on MF modules/applications, such as code completion, type checking at development time.

Used by build tools

Build tools such as webpack, esbuild can download the type definition with plugins and type-checking it before bundling and publishing the application. This makes it easy to reveal problems at build time instead of runtime.

How to register the very first version of a MFE via the Admin API

Hey @lucamezzalira , guys,

I am playing with the solutions and I managed to successfully deploy it, however I struggle to register my very first version of a MFE via the Admin API.

I am following the API documentation and here are the steps I performed:

  • Cognito Login - Success
  • Create project using POST API - Success
  • Create MFE using the POST API - Success
  • PATCH MFE - Fail
curl https://api.amazonaws.com/prod/projects/d7859c4c-77a2-4b49-a54d-0b407492a31e/microFrontends/5a23e420-1a6c-4ae2-ab94-eebdb3eafea9 -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" --request PATCH --data '{"name": "mfe-2","activeVersions":[{"version": "1.0.0","traffic": 100}],"default": "1.0.0"}' -H "Content-Type: application/json"

I am getting response

The specified version could not be found.

  • I then tested to create a new MFE version using the POST version API with the version payload included
curl https://api.amazonaws.com/prod/projects/d7859c4c-77a2-4b49-a54d-0b407492a31e/microFrontends/17d12cd5-d7fa-4f80-a378-0e3ed20ef8f9/versions -H "Authorization: Bearer <TOKEN>" --request POST --data '{ "version": { "url": "https://static.example.com/my-account-1.0.0.js", "metadata": { "version": "1.0.0", "integrity": "e0d123e5f317bef78bfdf5a008837200" }, "fallbackUrl": "https://alt-cdn.com/my-account-1.0.0.js" }, "deploymentStrategy": "AllAtOnce" }' -H "Content-Type: application/json" 

but got the following error:

Unable to create deployment when no existing version is currently receiving 100% traffic.

  • I tested an extra step and tried to specify version on new MFE creation (POST)
curl https://api.amazonaws.com/prod/projects/d7859c4c-77a2-4b49-a54d-0b407492a31e/microFrontends -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" --request POST --data '{"name": "mfe-2","activeVersions":[{"version": "1.0.0","traffic": 100}]}'

However the MFE entry gets created in the table dropping the activeVersions property.

What am I doing wrong?

Thanks!

Metadata open for extension

Hi Luca and friends of MFEs. I'll jump right in.

Question
Would you consider enabling the metadata object in the schema so it's open for extension. i.e. by removing or setting to true?

"additionalProperties": false

Rational
In the organisation that I work for, a MFE is identified using a convention; this looks something like {org}:{bc}:{mfename} ; reading from right to left mfename is the MFE name {bc} is the owning bounded context and {org} is the serving organisation.

Ideally it would be logical to place this meta information in the metadata section to make it easy to read from a human and machine perspective; adding this to another meta object in the extras section simply looks odd and kind of wrong.

If you look at another json schema CloudEvents (https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md), it is designed open to extension; meaning additional attributes can be added at the top level without impact to the convention; this enables an architecture to build upon a great standard but yet add additional characteristics as fits need.

Thank you kindly for considering.
Gareth.

Suggestions to schema improvements

Thanks for the great work. Looks like a huge, important step in the right direction.

Regarding the schema, I'm curious why you decided to inline default: true/false in each deployment configuratiun.
What if there are multiple default: true? Which one is the “real” default?

I think each configuration object should have a name, which can be used to assign version names such as “beta”, “canary”, "rc-0" or even relative version numbers etc.

Then you can reference each configuration entry by name instead of by index:

This could in turn be leveraged to allow for the deployments to be configured externally, instead of inlined as follows.
This would make it much easier to administer IMO.

{
  "deployments": {
    "default": "beta",
    "load": {
      "beta": {
        "percent": 70
      },
      "canary": {
        "percent": 30
      }
    }
  }
}

Could it be made more flexible to work with Feature/Deployment Flag tools such as Launch Darkly?
This would then require custom logic which accesses this config via an API and compares it with the user session role or group to decide which version is dynamically loaded for a given user.

{
  "deployments": {
    "default": "prod",
    "load": {
      "beta": {
        "users": ["beta-testers"]
      },
      "canary": {
        "users": ["canary-testers"]
      }
    }
  }
}

Just some thoughts. Cheers.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.