NgxsMessagePlugin
An Ngxs plugin that allows you to synchronize state across different browser contexts.
This allows you to use the same state in an iframe or popup window, and dispatch actions which will transparently run on the state host and update every app that subscribes to the state. For instance this makes it easier to manage state if you can detach elements from your app to a separate window.
Check out the sample app at https://andreas-hjortland.github.io/ngxs-message-plugin/ (or check out the source code in projects/testapp)
Installation and usage
First you need to install the npm module:
npm install ngxs-message-plugin --save
Then you need to include the module in your host and child apps.
Host
@NgModule({
imports: [
NgxsMessagePlugun.forRoot();
]
})
export class AppModule { }
Child (popup / iframe)
@NgModule({
imports: [
NgxsMessagePlugun.forChild();
]
})
export class AppModule { }
You can then do window.open('path/to/child/entrypoint')
and see that the state is the same in both the child and the
host state. You can also dispatch actions from the child state and they will be evaluated on the host store.
Configuration
If you need to customize the module, the forRoot
/ forChild
functions can take an optional configuration object. For
instance if you want to synchronize the state between all open windows on the origin, you can use the BroadcastChannel
message transport, or maybe you want to create your own message transport that uses web sockets to synchronize the state
with another browser alltogether. To configure the module, do like this
@NgModule({
imports: [
NgxsMessagePlugun.forRoot({
messageHandler: 'broadcast',
broadcastChannelName: 'myChannel', // this is what separates messages from different instances of the app
});
]
})
export class AppModule { }
You can check out all the configuration options in symbols.ts
, but
the most important options are messageHandler
which lets you configure how the messages are passed between instances.
The default is port
which will register any popup window or frame that is opened on the same domain with the opener
state. You can also roll your own by providing an implementation of MessageCommunicationService
.
Test app
The test app is a simple demo app which highlights how to use the library and demos that both the state and actions are
transparently handled. Here you can also see that we are using the KNOWN_ACTION
injection token to help the host
deserialize the actions since we are using instanceof
in the counter.state.ts
To start the test app, just check out the project, install dependencies using npm install
and start it using npm run
Known issues, limitations and potential improvements
- If you are auto generating the action type names, you have to ensure that the action type name is the same on both the
store owner and consumer.
- For the ngxs emitter plugin, you will have to supply the action type in the
@Receiver
decorator.
- For the ngxs emitter plugin, you will have to supply the action type in the
- If you are relying on the
instanceof
operator in your reducers, you will have to register the action class with theKNOWN_ACTION
injection token or through theknownActions
configuration parameter on the host. This lets the plugin map actions from the clients so that we can re-apply the prototype after deserializing the objects - We are serializing and copying the whole state for each state change and are doing the diff on the client. We probably could only send a diff from the host that we apply on the client. Feel free to create a pull request if you want to do this =)
- The state must be serializable and clonable using the structured clone algorithm. This is already best practice, but anything in the store not serializable will be ignored.
- On the children, you should not add any other plugins that modify the state because that might or might not be caught by the message plugin and therefore lost. That is not a problem on the host.
Contributions
All contributions are welcome (both issues and pull requests) as long as we keep a civil tone :)