Skip to content

WebDocker is a declarative configuration management system used to dynamically inject assets (JS and CSS) to website and render them afterward. It is mostly used for delivery of Micro Frontends, providing multiple ways to trigger the assets injection.

License

Notifications You must be signed in to change notification settings

OpenReplyDE/web-docker

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

36 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

README

The Webdocker is a central registry or Subject to which fragments(web components) can subscribe. Subscribed fragments declare their resources (js or CSS scripts) to the registry. The registry is responsible for loading the resources.

It is mostly used for delivery of microfrontends to the overall project, providing multiple ways to trigger the assets injection.

Summary of setup

  1. fragment: Next to Web Docker, this repo contains a fragment folder, which mocks the behavior of a fragment
  2. test-Host: A vue application that registers the web docker and loads the fragment
  3. web docker: contains the docker code responsible for registry and event handling. This is the actual asset that is uploaded as a build artifact.
  4. tests: A folder containing end-to-end tests for fragment, test-host and web docker (using playwright)

Observed Modules

Assets for observed modules are initially not injected in page. An observation mechanism examines the page for frequent updates and injects the assets only if the custom elements associated with the module are present on the page

Page Modules

These are modules which are injected into the page as soon as the first render is finished.

Global Modules

These are particular types of page modules which can be used by other modules as shared dependency.

Local development

  1. run following build commands to create the test fragments
       nvm use
       npm run build:page-module
       npm run build:observed-module
  2. Serve the fragments
       nvm use
       npm run serve:fragments
  3. Serve the test host
       nvm use
       npm run dev:test-host
  4. on the browser, navigate to http://localhost:5173/test-host.html to see the test host and the loaded page fragment NOTE: navigating to http://localhost:5173 will not show the fragment as the test host is not loaded on the root path

Environment variables

logging is disabled by default. To enable logging, set the following environment variable

 VITE_APP_LOG_EVENTS=true

Running the Web Docker as NPM package

  1. Install the package
       npm install @web-docker/web-docker
  2. Import the package in your project
       import { WebDocker } from '@openreplyde/web-docker'
  3. Initialize the Web Docker- the default construction does not require any parameters and fetches remote configs per default
       const webDocker = new WebDocker()

Extending the Web Docker with custom Services

Webdocker is designed to be extensible. You can extend the Web Docker with custom services by implementing the ModuleService interface. The custom service can be added to the Web Docker by calling the addService method.

import { WebDocker, ModuleService } from '@openreplyde/web-docker'

declare module '@openreplyde/web-docker' {
  interface IncludeTypeMap {
    customType: string;
  }
}

class CustomService implements ModuleService {
    constructor(
      private readonly config: { events: {} },
      private readonly assetFactory = new AssetFactory(),
      private readonly logEvents: boolean = false) {
        // initialize the service
    }

    async load(): Promise<void> {
        // load the module
    }
    
   get assetSources(): string[] {
        // return the asset sources
   }
   
   get module(): string {
        // return the module name
   }
   
   remove(): void {
        // remove the module
   }
}

const registry = new ModuleRegistry(true);
registry.addModuleServiceFactory({ type: 'customType', constructor: ServiceExtension });

const options = {
   configFilePath: "https://your-config-url.com",
   logEvents: false,
   scope: "webdocker"
}

const moduleConfigService = new ModuleConfigService();
const remoteConfigService = new RemoteConfigService(options);

const webDocker = new Webdocker(options, registry, moduleConfigService, remoteConfigService);

moduleConfigService and remoteConfigService are optional parameters. If not provided, the default services are used.

About

WebDocker is a declarative configuration management system used to dynamically inject assets (JS and CSS) to website and render them afterward. It is mostly used for delivery of Micro Frontends, providing multiple ways to trigger the assets injection.

Resources

License

Stars

Watchers

Forks

Packages