Repluggable

https://github.com/wix-incubator/repluggable
Admin
Repluggable is a library for implementing inversion of control in front-end applications,...
Tokens:5,132
Snippets:30
Trust Score:9.7
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Create New Repluggable Project

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Sets up a new React+Redux project with Repluggable, installs dependencies, replaces default files with a 'helloWorld' example, and starts the development server.

```bash
npx create-react-app your-app-name --template typescript
cd your-app-name
yarn add react@16.14.0 react-dom@16.14.0 @types/react@16.14.0 @types/react-dom@16.9.0 repluggable
rm src/App* 
rm src/logo*
cp -R node_modules/repluggable/examples/helloWorld/src/ ./src
yarn start
```

--------------------------------

### Basic Replugabble Application Setup

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Demonstrates the basic setup of a Replugabble application using React. It initializes the app host with packages and renders the main application view. It also shows how to dynamically add shells later.

```TypeScript
import ReactDOM from 'react-dom'
import { createAppHost, AppMainView } from 'repluggable'

import packageOne from 'package-one'
const packageTwo = () => import('package-two').then(m => m.default)
const packageThree = require('package-three')

const host = createAppHost([
    packageOne,
    packageThree
])

ReactDOM.render(
    <AppMainView host={host} />,
    document.getElementById('root')
)

// Sometime later
void packageTwo().then(p => host.addShells([p]))
```

--------------------------------

### Install Repluggable

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Adds the Repluggable library to an existing React+Redux application using npm.

```bash
npm install repluggable
```

--------------------------------

### Implementing Package API with Store Access

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Provides an example implementation of the package API. It shows how to access the application store using `shell.getStore` and dispatch actions or retrieve state slices.

```TypeScript
const createFooAPI = (shell: Shell): FooAPI => {
    const entryPointStore = shell.getStore<FooState>()
    const getState = () => entryPointStore.getState()

    return {
        // ... other API implementations
        getBazXyzzy(): number {
            const state: FooState = getState()
            return state.baz.xyzzy
        },
        setBazXyzzy(value: number): void {
            entryPointStore.dispatch(BazActionCreators.setXyzzy(value))
        }
        // ... other API implementations
    }
}
```

--------------------------------

### EntryPoint Interface Definition and Usage

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Defines the `EntryPoint` interface for Replugabble packages and provides an example of its implementation. This includes methods for specifying dependencies, declaring APIs, and handling lifecycle hooks like `attach`, `extend`, and `detach`.

```TypeScript
import { EntryPoint, Shell } from 'repluggable'

// Assuming BarAPI, FooAPI, FooItem, createFooAPI are defined elsewhere
// import { BarAPI } from './barApi'
// import { FooAPI, createFooAPI } from './fooApi'
// import FooItem from './FooItem'

const FooEntryPoint: EntryPoint = {

    // required: specify unique name of the entry point
    name: 'FOO',

    // optional
    getDependencyAPIs() {
        return [
            // DO list required API keys
            // BarAPI
        ]
    },

    // optional
    declareAPIs() {
        // DO list API keys that will be contributed 
        return [
            // FooAPI
        ]
    },

    // optional
    attach(shell: Shell) {
        // DO contribute APIs
        // DO contribute reducers
        // DO NOT consume APIs
        // DO NOT access store
        // shell.contributeAPI(FooAPI, () => createFooAPI(shell))
    },

    // optional
    extend(shell: Shell) {
        // DO access store if necessary
        // shell.getStore().dispatch(....)
        // DO consume APIs and contribute to other packages
        // shell.getAPI(BarAPI).contributeBarItem(() => <FooItem />)
    },

    // optional
    detach(shell: Shell) {
        // DO perform any necessary cleanup
    }
}
```

--------------------------------

### Define a Pluggable Entry Point

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Defines a simple pluggable entry point for a Repluggable package. The 'attach' function is called when the package is loaded, and it logs a message to the console. This serves as a basic example of how packages contribute functionality.

```TypeScript
import { EntryPoint } from 'repluggable'

export const Foo : EntryPoint = {
    name: 'FOO',

    attach() {
        console.log('FOO is here!')
    }
}
```

--------------------------------

### Stateless Function Component Example

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

An example of a stateless functional component (SFC) in React, demonstrating how to define its props type using a combination of state and dispatch props.

```jsx
(props) => (
    <div className="foo">
        <div>
            <label>XYZZY</label>
            <input
                type="text"
                defaultValue={props.xyzzy}
                onChange={e => props.setXyzzy(e.target.value)} />
        </div>
        <div>
            Current BAR = {props.bar}
            <button onClick={() => props.createNewBar()}>
                Create new BAR
            </button>
        </div>
    </div>
)
```

--------------------------------

### Connecting React Component with connectWithShell

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Example of using `connectWithShell` to create a connected container for a React component. This function allows the component to access APIs from the shell. It demonstrates how `mapStateToProps` and `mapDispatchToProps` receive the `shell` object as the first argument.

```TypeScript
export const createFoo = (boundShell: Shell) => connectWithShell(
    // mapStateToProps
    // - shell: represents the associated entry point
    // - the rest are regular parameters of mapStateToProps
    (shell, state) => {
        return {
            // some properties can map from your own state
            xyzzy: state.baz.xyzzy,
            // some properties may come from other packages' APIs
            bar: shell.getAPI(BarAPI).getCurrentBar()
        }
    },
    // mapDispatchToProps
    // - shell: represents the associated entry point
    // - the rest are regular parameters of mapDispatchToProps
    (shell, dispatch) => {
        return {
            // some actions may alter your own state
            setXyzzy(newValue: string): void {
                dispatch(FooActionCreators.setXyzzy(newValue))
            },
            // others may request actions from other packages' APIs
            createNewBar() {
                shell.getAPI(BarAPI).createNewBar()
            }
        }
    },
    boundShell
)(FooSfc)
```

--------------------------------

### AppHost Initialization and Rendering

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Demonstrates the minimal responsibilities of the main application: initializing an AppHost with pluggable packages and rendering the AppMainView component.

```javascript
import React from 'react';
import AppHost from './AppHost'; // Assuming AppHost is defined elsewhere
import AppMainView from './AppMainView'; // Assuming AppMainView is defined elsewhere

const pluggablePackages = [
  // List of pluggable packages
];

function App() {
  const appHost = new AppHost(pluggablePackages);

  return (
    <AppMainView appHost={appHost} />
  );
}
```

--------------------------------

### Bootstrap Main Application with Entry Points

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Initializes the Repluggable application host with an array of entry points (packages). The `createAppHost` function takes the list of packages, and `AppMainView` is used to render the application's main view, passing the host to it.

```TypeScript
import { createAppHost, AppMainView } from 'repluggable'
import { Foo } from './foo'
import { Bar } from './bar'

const host = createAppHost([
    // the list of initially loaded packages
    Foo,
    Bar
])

ReactDOM.render(
    <AppMainView host={host} />,
    document.getElementById('root')
)
```

--------------------------------

### Initialize AppHost and Add Shells

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Initializes the `AppHost` with statically loaded packages and later adds dynamically loaded packages (shells) to the host. This showcases how to manage package loading over time.

```TypeScript
const host = createAppHost([
    foo,
    baz
])

// Later
void bar().then(p => host.addShells([p]))
```

--------------------------------

### Load Pluggable Packages

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Demonstrates different methods for loading pluggable packages: statically bundled, via WebPack code splitting (dynamic import), and from an AMD module using RequireJS.

```TypeScript
import foo from 'package-foo'
const bar = () => import('package-bar').then(m => m.default)
const baz = require('package-baz')
```

--------------------------------

### Import Repluggable Functions

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Imports necessary functions from the 'repluggable' package for creating an application host and rendering the main application view.

```TypeScript
import { createAppHost, AppMainView } from 'repluggable'
```

--------------------------------

### Render AppMainView

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Renders the main application view using `ReactDOM.render`, passing the initialized `AppHost` to the `AppMainView` component. This is the final step in bootstrapping the Repluggable application.

```TypeScript
ReactDOM.render(
    <AppMainView host={host} />,
    document.getElementById('root')
)
```

--------------------------------

### Exporting Entry Points from a Package

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Illustrates how to export multiple entry points from a package's main index file. The default export should be an array containing all the package's entry point objects.

```TypeScript
import { FooEntryPoint } from './fooEntryPoint'
import { BarEntryPoint } from './barEntryPoint'

export default [
    FooEntryPoint,
    BarEntryPoint
]
```

--------------------------------

### Creating Reducers

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Illustrates the creation of reducer functions that manage specific parts of the application state. Each reducer takes the current state and an action, returning the new state.

```TypeScript
function bazReducer(
    state: BazState = { /* initial values */ },
    action: Action) 
{
     // ... reducer logic
}

function quxReducer(
    state: QuxState = { /* initial values */ },
    action: Action)
{
     // ... reducer logic
}
```

--------------------------------

### AppHost Package Addition

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Illustrates how a package, represented by a Promise resolving to its default export, is added to the AppHost. This supports various module systems and loading strategies.

```typescript
const packagePromise: Promise<MyPackage> = import('./myPackage');
appHost.add(packagePromise);
```

--------------------------------

### Entry Point Dependency Declaration

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Shows how an entry point declares its API dependencies. If required APIs are unavailable, the entry point is put on hold until they are provided.

```typescript
const entryPoint = {
  id: 'myEntryPoint',
  dependencies: ['apiA', 'apiB'],
  // ... other entry point configurations
};
```

--------------------------------

### EntryPoint Interface

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Defines the structure of an EntryPoint in Replugabble. It includes required properties like `name` and optional methods for managing dependencies, declaring APIs, and handling the lifecycle of a pluggable component.

```APIDOC
EntryPoint:
  name: string (required) - Unique identifier for the entry point.
  getDependencyAPIs(): SlotKey<any>[] (optional) - Returns an array of API keys that this entry point depends on.
  declareAPIs(): SlotKey<any>[] (optional) - Returns an array of API keys that this entry point contributes.
  attach(shell: Shell): void (optional) - Lifecycle hook called when the entry point is attached. Used for contributing APIs and reducers.
  extend(shell: Shell): void (optional) - Lifecycle hook called after attach. Used for consuming APIs and interacting with the store.
  detach(shell: Shell): void (optional) - Lifecycle hook called when the entry point is detached. Used for cleanup.
```

--------------------------------

### API Consumption with getAPI

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Illustrates how a consumer package retrieves an API object by calling `getAPI` with the API key provided by a provider package.

```javascript
import { getAPI } from 'repluggable'; // Assuming getAPI is exported from repluggable
import { MyApiProviderKey, MyApiInterface } from './MyApiProvider'; // Assuming API key and interface are exported

// Inside a component or service that needs to consume the API:
const myApi = getAPI(MyApiProviderKey);

// Now you can use methods from myApi, e.g.:
// myApi.someMethod();

// Type assertion for better intellisense (TypeScript):
// const myApiTyped: MyApiInterface = getAPI(MyApiProviderKey);
```

--------------------------------

### API Declaration and Contribution

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Details the process of creating and contributing a Replugabble API. This involves declaring an interface, defining a `SlotKey`, implementing the API logic, and contributing it via the `attach` function in an entry point.

```TypeScript
// 1. Declare an API interface
export interface FooAPI {
    doSomething(): void
    doSomethingElse(what: string): Promise<number>
}

// 2. Declare an API key
import { SlotKey } from 'repluggable'

export const FooAPI: SlotKey<FooAPI> = {
    name: 'Foo API',
    public: true
}

// 3. Implement your API
// import { Shell } from 'repluggable'
// export function createFooAPI(shell: Shell): FooAPI {
//     return {
//         doSomething(): void {
//             // ...
//         },
//         doSomethingElse(what: string): Promise<number> {
//             // ...
//         }
//     }
// }

// 4. Contribute your API from an entry point attach function
// import { EntryPoint } from 'repluggable'
// import { FooAPI, createFooAPI } from './fooApi'

// const FooEntryPoint: EntryPoint = {
// 
//     ...
// 
//     attach(shell: Shell) {
//         shell.contributeAPI(FooAPI, () => createFooAPI(shell))
//     }
// 
//     ...
// 
// }

// 5. Export your API from the package
// export { FooAPI } from './fooApi'
```

--------------------------------

### Extension Slot Initialization and Contribution

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Demonstrates the internal initialization of an extension slot and how a package contributes an API to push contributions into it. Extension slots are typed generic objects that manage contributions from different packages.

```typescript
class MyPackage {
  private readonly extensionSlot = new ExtensionSlot<MyContributionType>();

  constructor(private readonly appHost: AppHost) {
    this.appHost.register(this.extensionSlot);
  }

  public contribute(contribution: MyContributionType) {
    this.extensionSlot.contribute(contribution);
  }
}
```

--------------------------------

### Shell Object

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Describes the `Shell` object provided to EntryPoint lifecycle hooks. The `Shell` object acts as an interface to the `AppHost`, allowing interaction with the application's state and API registry.

```APIDOC
Shell:
  contributeAPI<T>(api: SlotKey<T>, factory: () => T): void - Contributes an API implementation to the host.
  getStore(): Store - Returns the application's Redux store.
  getAPI<T>(api: SlotKey<T>): T - Retrieves an API implementation from the host.
  contributeReducer(reducer: Reducer): void - Contributes a Redux reducer.
  contributeActions(actions: Action[]): void - Contributes Redux actions.
```

--------------------------------

### API Key Declaration

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Explains how to declare an API key using `SlotKey`. This key is used to uniquely identify and register APIs within the Replugabble framework. `public: true` is necessary for exporting APIs externally.

```APIDOC
SlotKey<T>:
  name: string - A human-readable name for the API.
  public: boolean (required for external export) - Indicates if the API is publicly accessible outside its package.
```

--------------------------------

### Enabling Hot Module Replacement (HMR)

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Demonstrates how to enable Hot Module Replacement (HMR) for repluggable packages using the `hot` utility. This allows for immediate code updates during local development without full page reloads.

```ts
import { hot } from 'repluggable'
import { FooEntryPoint } from './fooEntryPoint'
import { BarEntryPoint } from './barEntryPoint'

export default hot(module, [
    FooEntryPoint,
    BarEntryPoint
])
```

--------------------------------

### Contributing State to the Shell

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Demonstrates how to contribute reducers to the Replugged shell. The `contributeState` method takes a reducer map object whose keys match the root state type.

```TypeScript
attach(shell: Shell) {
    shell.contributeState<FooState>(() => ({
        baz: bazReducer,
        qux: quxReducer
    }))
}
```

--------------------------------

### Defining Package API for State Management

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Defines the interface for the package's API, including methods for accessing and modifying state. These methods abstract away direct state manipulation.

```TypeScript
export interface FooAPI {
    // ... other API methods
    getBazXyzzy(): number
    setBazXyzzy(value: number): void
    // ... other API methods
}
```

--------------------------------

### Defining State Interfaces

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

Declares the TypeScript interfaces for the state managed by individual reducers and the root state type for the entry point.

```TypeScript
export interface BazState {
    ... // other properties
    xyzzy: number // for example
}

export interface QuxState {
    ... // other properties
}

// the root type on entry point level
export interface FooState {
    baz: BazState
    qux: QuxState
}
```

--------------------------------

### Defining React Component Props with Repluggable

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

TypeScript definitions for state props and dispatch props used in a React component integrated with repluggable. `FooStateProps` defines properties derived from the package's state and other package APIs, while `FooDispatchProps` defines actions to be dispatched.

```TypeScript
type FooStateProps = {
    // retrieved from own package state
    xyzzy: string
    // retrieved from another package API
    bar: number
}

type FooDispatchProps = {
    setXyzzy(newValue: string): void
    createNewBar(): void
}
```

--------------------------------

### Stateless Function Component Implementation

Source: https://github.com/wix-incubator/repluggable/blob/master/README.md

The implementation of a stateless functional component (`FooSfc`) in React, with its props type explicitly defined as the intersection of `FooStateProps` and `FooDispatchProps`.

```TypeScript
const FooSfc: React.SFC<FooStateProps & FooDispatchProps> =
    (props) => (
        <div className="foo">
            ...
        </div>        
    )
```
Tokens:
Raw