GithubHelp home page GithubHelp logo

sickag / collage Goto Github PK

View Code? Open in Web Editor NEW
28.0 4.0 4.0 1.55 MB

Library to make creating and using of micro frontends convenient and easy

Home Page: https://sickag.github.io/collage/

License: MIT License

HTML 32.23% CSS 0.74% TypeScript 53.18% JavaScript 13.84%
microfrontends micro-frontends collage

collage's Introduction

Collage

Introduction

Collage is a library for creating and embedding micro frontends as fragments.

With Collage you can upgrade a web application of all sorts to either a micro frontend or an application capable of embedding micro frontends - basically both at the same time. Doing so, Collage works on the scope of HTML Documents by enhancing a Document with certain capabilities, allowing them to efficiently communicate with each other.

Official Documentation

For information about collage and its capabilities, please have a look at our Official Documentation.

Developer Documentation

For details about the architecture and structure of collage, please have a look at our Developer Documentation.

Preview

To create and embed micro frontends with collage you just need to add a few lines on top of your already existing Application:

<body>
  <div class="somewhere">
    <!-- include a micro frontend effortlessly -->
    <collage-fragment
      url="/url/to/micro-frontend"
      config-something="Configure this!"
      name="my-micro-frontend">
    </collage-fragment>
  </div>
</body>
const api = await expose({
  // expose the api of your micro frontend
  services: {
    myService(name = "") {
      return `Default Implementation for ${name}`;
    },
  },
});

Features

  • Upgrade any web application to a micro frontend by exposing its capabilities.
  • Embed micro frontends in your application.
  • Configure embedded micro frontends to fit them perfectly into your application.
  • Provide services to other micro frontends and the whole Arrangement and use services, other Contexts are exposing.
  • Publish messages or subscribe to topics which are available for all parts of your application.
  • Micro frontends built with different frameworks can be combined to one application without effort.
  • Scope Isolation Guarantees compatibility in every scenario.
  • Bundle micro frontends into your application at build time or include them from any other origin - they can even be added and removed dynamically at runtime.

Non-functional Features

  • Small - Minified and gzipped, its footprint is just about 15 KB.
  • Easy to use - Create a micro frontend with just a few lines of code.
  • Use a self explainatory api to describe your micro frontends and orchestrate them in complex arrangements effortlessly.
  • Built on web standards and only a few simple core concepts means that you never run into magic behaviour that ruins your day.
  • Easy to use - Simply wrap the expose() call to create custom functionality.

collage's People

Contributors

beneee avatar dependabot[bot] avatar kirchsusickag avatar phebing avatar razzeee avatar svelue avatar wanjatschuorsickag 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

Watchers

avatar avatar avatar avatar

Forkers

razzeee phebing svelue beneee

collage's Issues

[Suggestion] Add an onError handler to <collage-fragment>

The <collage-fragment> web component provides a few lifecycle methods, such as onLoaded. While this is fine, I was wondering if it would be possible to control the behavior in case loading the iframe fails, e.g. because of a network error, or if the targeted server returns a 404.

Would it be possible to add an onError handler, where one might control what should happen in these cases?

Make sure to provide side effects free bundle

It should be checked if it is possible to provide a side effects free package by adding hints for bundlers (e.g. webpack) that make it possible to better tree shake the package.

Proposed solution:

Further Information:

If this feature is considered, I would be happy to provide a pull request for this feature.

feature request: debug flag

The debug flag should be accessible by developers using collage to get more debug information (e.g. contents of penpal messages)

Error when removing a collage-fragment from DOM, which itself does not use collage to be a collage-fragment by itself

Following error occurs, when removing a collage-fragment from the DOM, whose underlying application does not use collage:

image

Steps to reproduce the error:

  1. create a parent app which includes a child app via collage-fragment
    Example code parent:
     <script type="module">
      import { expose } from "@collage/core";
      expose().then((context) => {
        document.querySelector("#btn").addEventListener("click", () => {
          document.querySelector("#iframe").remove();
        });
      });
    </script>
    <button id="btn">Remove fragment without collage</button>
    <collage-fragment id="iframe"  url="./child.html"></collage-fragment>
  1. create a child app which should not use collage itself (child.html)
    <div>It does not matter what happens here</div>
  1. the parent element removes the collage-fragment from the DOM --> document.querySelector('collage-fragment').remove();

Note

If a collage fragment is created with an application that does not use collage itself, this will result in collage not being able to complete the handshake and therefore some collage features cannot be used.

Type import issues with node bundler setup

When importing collage in a typescript node bundler setup the index.d.ts could not be found due to an error in the package.json.

Could not find a declaration file for module '@collage/core'. 'c:/.../node_modules/@collage/core/dist/collage.es.js' implicitly has an 'any' type.

To make it work again, we need to revert the removal of the "types" keyword in the package.json.

Typings could not be found

When importing collage with typescript the index.d.ts could not be found due to an error in the package.json.

Could not find a declaration file for module '@collage/core'. 'c:/.../node_modules/@collage/core/dist/collage.es.js' implicitly has an 'any' type.
There are types at 'c:/.../node_modules/@collage/core/dist/index.d.ts', but this result could not be resolved when respecting package.json "exports". The '@collage/core' library may need to update its package.json or typings.

Handling of not implemented services in when called within fragment

I have an arrangement which makes services available via expose().

code3

To access this service from the arrangement within my fragments, I have to implement this function in expose() again.
code4

I struggled with getting this communication to work in the beginning, as it was unclear to me why and how I have to (re-)implement functions within a fragment to call them from the "external" arrangement.
I have two recommendations for clarifying this design choice and making it more beginner friendly:

No. 1: Clearly stating the options and reasons to choose them could make it easier to understand conceptually

The re-implementation of external functionalities within the fragments expose() was decided upon to create a clear fallback strategy, when the external service is not available.
This re-implementation can

  • be empty, if the fragment does not have to be usable outside the context enabling the external functionality
  • resemble the full external functionality, to make the fragment independent and fully featured without any context
  • contain any other fallback functionality to be called of external service not available

No. 2: I think it would be very helpful for situations like this to get meaningful errors from collage as to why I can't access a function.
Errors like the following could lower the barrier to entry:

  • "Uncaught (in promise) collageError: api.services.ArrangementName.getHelloWorld is not a defined in the Collage API expose() initialization, see here: LINK TO DOKU"

Thanks :)

Handling of not implemented services in when called within fragment

I have an arrangement which makes services available via expose().

code3

To access this service from the arrangement within my fragments, I have to implement this function in expose() again.
code4

I struggled with getting this communication to work in the beginning, as it was unclear to me why and how I have to (re-)implement functions within a fragment to call them from the "external" arrangement.
I have two recommendations for clarifying this design choice and making it more beginner friendly:

No. 1: Clearly stating the options and reasons to choose them could make it easier to understand conceptually

The re-implementation of external functionalities within the fragments expose() was decided upon to create a clear fallback strategy, when the external service is not available.
This re-implementation can

  • be empty, if the fragment does not have to be usable outside the context enabling the external functionality
  • resemble the full external functionality, to make the fragment independent and fully featured without any context
  • contain any other fallback functionality to be called of external service not available

No. 2: I think it would be very helpful for situations like this to get meaningful errors from collage as to why I can't access a function.
Errors like the following could lower the barrier to entry:

  • "Uncaught (in promise) collageError: api.services.ArrangementName.getHelloWorld is not a defined in the Collage API expose() initialization, see here: LINK TO DOKU"

Thanks :)

The documentation of onConfigUpdated has an incorrect reference to the underlying event

collage/docs/docs/core-api.md

Line 543 in a217790

The onUpdated hook is based on the `collage-context-updated` event, which is dispatched, everytime something on the own context changed. The event emits the updated context.

Docu text is:

The onUpdated hook is based on the collage-context-updated event, which is dispatched, everytime something on the own context changed. The event emits the updated context. You can use the event if necessary, but you should prefere the hook.

but should be

The onConfigUpdated hook is also based on the collage-context-updated event, which is dispatched, everytime something on the own contexts changed. The event emits the updated context. You can use the event if necessary, but you should prefer the hook.

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.