State transferring utility for Angular Universal
Adding
Add
Please support this project by simply putting a Github star. Share this library with friends on Twitter and everywhere else you can.
NOTICE
This 4.x.x branch is intented to work with @angular v4.x.x
. If you're developing on a later release of Angular
than v4.x.x
, then you should probably choose the appropriate version of this library by visiting the master branch.
Table of contents:
- Installation- [Examples](#examples)
- [Related packages](#related-packages)
- [Adding `@ngx-universal/state-transfer` to your project (SystemJS)](#adding-systemjs)
- app.server.module configuration
- app.browser.module configuration
- app.module configuration
Prerequisites
This library depends onAngular v4.0.0
. Older versions contain outdated dependencies, might produce errors.
Also, please ensure that you are using Typescript v2.3.4
or higher.
Getting started
Installation
You can install@ngx-universal/state-transfer
using npm
```
npm install @ngx-universal/state-transfer --save
```
Examples
- ng-seed/universal is an officially maintained seed project, showcasing common patterns and best practices for
@ngx-universal/state-transfer
.
Related packages
The following packages may be used in conjunction with@ngx-universal/state-transfer
:
Adding @ngx-universal/state-transfer
to your project (SystemJS)
Add map
for @ngx-universal/state-transfer
in your systemjs.config
```javascript
'@ngx-universal/state-transfer': 'nodemodules/@ngx-universal/state-transfer/bundles/state-transfer.umd.min.js'
```
app.server.module configuration
ImportServerStateTransferModule
using the mapping '@ngx-universal/state-transfer'
and append ServerStateTransferModule.forRoot({...})
within the imports property of app.server.module (considering the app.server.module is the server module in Angular
Universal application).
```TypeScript
...
import { ServerStateTransferModule, StateTransferService } from '@ngx-universal/state-transfer';
...
@NgModule({
imports:
BrowserModule.withServerTransition({
appId: 'my-app-id'
}),
ServerModule,
ServerStateTransferModule.forRoot(),
AppModule
,
...
bootstrap: AppComponent
})
export class AppServerModule {
constructor(private readonly stateTransfer: StateTransferService) {
}
ngOnBootstrap = () => {
this.stateTransfer.set('test_key', JSON.stringify({'value': 'test'}));
this.stateTransfer.inject();
}
}
```
app.browser.module configuration
ImportBrowserStateTransferModule
using the mapping '@ngx-universal/state-transfer'
and append BrowserStateTransferModule.forRoot({...})
within the imports property of app.browser.module (considering the app.browser.module is the browser module in Angular
Universal application).
```TypeScript
...
import { BrowserStateTransferModule } from '@ngx-universal/state-transfer';
...
@NgModule({
imports:
BrowserModule.withServerTransition({
appId: 'my-app-id'
}),
BrowserStateTransferModule.forRoot(),
AppModule
,
...
bootstrap: LayoutMainComponent
})
export class AppBrowserModule {
}
```
app.module configuration
ImportHttpTransferModule
using the mapping '@ngx-universal/state-transfer'
and append HttpTransferModule.forRoot({...})
within the imports property of app.module (considering the app.module is the core module in Angular application).
```TypeScript
...
import { HttpTransferModule } from '@ngx-universal/state-transfer';
...
@NgModule({
imports:
BrowserModule,
HttpTransferModule.forRoot(),
...
,
...
bootstrap: AppComponent
})
export class AppModule {
...
}
```
:+1: So good! @ngx-universal/state-transfer
will now transfer the state from the server platform to the browser
platform.
Usage
StateTransferService
has the following methods:
initialize(state: Map<string, any>)
: initializes theSTATE
using an existingMap<string, any>
get(key: string)
: gets some object fromSTATE
, by key
set(key: string, value: any)
: puts some object toSTATE
inject()
: injects theSTATE
inside a<script>
block (between the<head>...</head>
tags)
STATE
value transferred from the server platform to the browser platform,
using the configuration above.
app.browser.module
```TypeScript ... import { BrowserStateTransferModule, DEFAULTSTATEID } from '@ngx-universal/state-transfer'; ... @NgModule({ imports:BrowserModule.withServerTransition({
appId: 'my-app-id'
}),
BrowserStateTransferModule.forRoot(),
AppModule
,
...
bootstrap: LayoutMainComponent
})
export class AppBrowserModule {
constructor() {
// get `STATE` value (injected by the server platform)
let stateValue = undefined;
const win: any = window;
if (win && win[DEFAULT_STATE_ID])
stateValue = win[DEFAULT_STATE_ID];
// do something with the value acquired
// whatever you want ...
}
}
```