GitBook: [master] 11 pages modified

Author: christianalfoni

SUMMARY.md

@@ -16,6 +16,7 @@
 * [Effects](core/running-side-effects.md)
 * [Operators](core/going-functional.md)
 * [Statecharts](core/statecharts.md)
+* [Server Side Rendering](core/server-side-rendering.md)
 * [Typescript](core/typescript.md)
 
 ## views
@@ -34,9 +35,8 @@
 * [Connecting to React Native](https://dev.to/brasilikum/how-to-setup-overmind-with-react-native-expo-optional-4mk5)
 * [Managing lists](guides-1/managing-lists.md)
 * [State first routing](guides-1/state-first-routing.md)
-* [Server Side Rendering](guides-1/server-side-rendering.md)
 * [Move to Typescript](guides-1/move-to-typescript.md)
-* [Testing](features/testing.md)
+* [Testing](guides-1/testing.md)
 
 ## API <a id="api-1"></a>
 

core/running-side-effects.md

@@ -91,6 +91,7 @@ It can be a good idea to not allow your side effects to initialize when they are
 ```typescript
 import * as firebase from 'firebase'
 
+// We use IIFE to hide the private "app" variable
 export const api = (() => {
   let app
 
@@ -132,6 +133,35 @@ export const onInitialize = async ({ effects }) => {
 Typically you explicitly communicate with effects from actions, by calling methods. But sometimes you need effects to know about the state of the application, or maybe some internal state in the effect should be exposed on your application state. Again we can take advantage of an **initialize** method on the effect:
 
 {% tabs %}
+{% tab title="overmind/effects.js" %}
+```javascript
+// We use an IIFE to isolate some variables
+export const socket = (() => {
+  _options
+  _ws
+  return {
+    initialize(options) {
+      _options = options
+      _ws = new WebSocket('ws://...')
+      _ws.onclose = () => options.onStatusChange('close')
+      _ws.onopen = () => options.onStatusChange('open')
+      _ws.addEventListener(
+        'message',
+        (event) => options.onMessage(event.data)
+      )
+    },
+    send(type, data) {
+      _ws.postMessage({
+        type,
+        data,
+        token: _options.getToken()
+      })
+    }
+  }
+})()
+```
+{% endtab %}
+
 {% tab title="overmind/onInitialize.js" %}
 ```typescript
 export const onInitialize = async ({ state, effects, actions }) => {

guides-1/server-side-rendering.md core/server-side-rendering.mdguides-1/server-side-rendering.md renamed to core/server-side-rendering.md

@@ -36,7 +36,7 @@ Here we only export the configuration from the main Overmind file. The instantia
 
 ## Preparing effects
 
-The effects will also be shared with the server. Typically this is not an issue, but you should be careful about creating effects that run logic when they are defined. You might also consider lazy-loading effects so that you avoid loading them on the server at all. You can read more about them in [EFFECTS](../core/running-side-effects.md).
+The effects will also be shared with the server. Typically this is not an issue, but you should be careful about creating effects that run logic when they are defined. You might also consider lazy-loading effects so that you avoid loading them on the server at all. You can read more about them in [EFFECTS](running-side-effects.md).
 
 ## Rendering on the server
 
@@ -103,3 +103,55 @@ export const onInitialize: OnInitialize = ({ state }) => {
 If you are using state first routing, make sure you prevent the router from firing off the initial route, as this is not needed.
 {% endhint %}
 
+## OnInitialize
+
+The `onInitialized` action does not run on the server. The reason is that it is considered a side effect you might not want to run, so we do not force it. If you do want to run an action as Overmind fires up both on the client and the server you can rather create a custom action for it.
+
+{% tabs %}
+{% tab title="overmind/actions.js" %}
+```javascript
+export const initialize = () => {
+  // Whatever...
+}
+```
+{% endtab %}
+
+{% tab title="client/index.js" %}
+```typescript
+import { createOvermind } from 'overmind'
+import { config } from './overmind'
+
+const overmind = createOvermind(config)
+overmind.actions.initialize()
+```
+{% endtab %}
+
+{% tab title="server/index.js" %}
+```javascript
+import { createOvermindSSR } from 'overmind'
+import { config } from '../client/overmind'
+
+export default async (req, res) => {
+  const overmind = createOvermindSSR(config)
+  await overmind.actions.initialize()
+
+  const html = renderToString(
+    // Whatever implementation your view layer provides
+  )
+
+  res.send(`
+<html>
+  <body>
+    <div id="app">${html}</div>
+    <script>
+      window.__OVERMIND_MUTATIONS = ${JSON.stringify(overmind.hydrate())}
+    </script>
+    <script src="/scripts/app.js"></script>
+  </body>
+</html>
+`)
+}
+```
+{% endtab %}
+{% endtabs %}
+

core/typescript.md

@@ -387,7 +387,41 @@ export const filterAwesome: <T extends { isAwesome: boolean }>() => Operator<T>
 
 That means this operator can handle any type that matches an **isAwesome** property, though will pass the original type through.
 
-## Statecharts
+## Statemachine
+
+Statemachines exposes a type called **Statemachine** which you will give a single type argument of what states it should manage:
+
+{% tabs %}
+{% tab title="overmind/state.ts" %}
+```typescript
+import { Statemachine, statemachine } from 'overmind'
+
+type Mode =
+  | 'unauthenticated'
+  | 'authenticating'
+  | 'authenticated'
+  | 'unauthenticating'
+
+type State = {
+  mode: Statemachine<Mode>
+}
+
+export const state: State = {
+  mode: statemachine<Mode>({
+    initial: 'unauthenticated',
+    states: {
+      unauthenticated: ['authenticating'],
+      authenticating: ['unauthenticated', 'authenticated'],
+      authenticated: ['unauthenticating'],
+      unauthenticating: ['unauthenticated', 'authenticated']
+    }
+  })
+}
+```
+{% endtab %}
+{% endtabs %}
+
+## Statechart
 
 To type a statechart you use the **Statechart** type:
 

faq.md

@@ -8,5 +8,9 @@ First… try to refresh your app to reconnect. If this does not work make sure t
 
 Restart VS Code
 
+## My operator actions are not running?
+
+Operators are identified with a Symbol. If you happen to use Overmind across packages you might be running two versions of Overmind. The same goes for core package and view package installed out of version sync. Make sure you are only running on package of Overmind by looking into your **node\_modules** folder.
+
 
 

features/testing.md guides-1/testing.mdfeatures/testing.md renamed to guides-1/testing.md

@@ -11,22 +11,18 @@ You can also do **unit testing** of actions and effects. This will cover expecte
 When you write tests you will create many instances of a mocked version of Overmind with the configuration you have created. To ensure that this configuration can be used many times we have to separate our configuration from the instantiation of the actual app.
 
 {% tabs %}
-{% tab title="overmind/index.ts" %}
+{% tab title="overmind/index.js" %}
 ```typescript
 import { IConfig } from 'overmind'
 import { state } from './state'
 
 export const config = {
   state
 }
-
-declare module 'overmind' {
-  interface Config extends IConfig<typeof config> {}
-}
 ```
 {% endtab %}
 
-{% tab title="index.ts" %}
+{% tab title="index.js" %}
 ```typescript
 import { createOvermind } from 'overmind'
 import { config } from './overmind'
@@ -43,11 +39,9 @@ Now we are free to import our configuration without touching the application ins
 When testing an action you’ll want to verify that changes to state are performed as expected. To give you the best possible testing experience Overmind comes with a mocking tool called **createOvermindMock**. It takes your application configuration and allows you to run actions as if they were run from components.
 
 {% tabs %}
-{% tab title="overmind/actions.ts" %}
+{% tab title="overmind/actions.js" %}
 ```typescript
-import { AsyncAction } from 'overmind'
-
-export const getPost: AsyncAction<string> = async ({ state, api }, id) {
+export const getPost = async ({ state, api }, id) {
   state.isLoadingPost = true
   try {
     state.currentPost = await api.getPost(id)
@@ -63,7 +57,7 @@ export const getPost: AsyncAction<string> = async ({ state, api }, id) {
 You might want to test if a thrown error is handled correctly here. This is an example of how you could do that:
 
 {% tabs %}
-{% tab title="overmind/actions.test.ts" %}
+{% tab title="overmind/actions.test.js" %}
 ```typescript
 import { createOvermindMock } from 'overmind'
 import { config } from './'
@@ -114,7 +108,7 @@ If your actions can result in multiple scenarios a unit test is beneficial. But
 You do not have to explicitly write the expected state. You can also use for example [JEST](https://www.overmindjs.org/guides/intermediate/05_writingtests?view=react&typescript=true) for snapshot testing. The mock instance has a list of mutations performed. This is perfect for snapshot testing.
 
 {% tabs %}
-{% tab title="overmind/actions.test.ts" %}
+{% tab title="overmind/actions.test.js" %}
 ```typescript
 import { createOvermindMock } from 'overmind'
 import { config } from './'
@@ -162,7 +156,7 @@ In this scenario we would also ensure that the **isLoadingPost** state indeed fl
 The **onInitialize** hook will not trigger during testing. To test this action you have to trigger it yourself.
 
 {% tabs %}
-{% tab title="overmind/onInitialize.test.ts" %}
+{% tab title="overmind/onInitialize.test.js" %}
 ```typescript
 import { createOvermindMock } from 'overmind'
 import { config } from './'
@@ -197,29 +191,17 @@ A simple example of this is doing requests. Maybe you want to use e.g. [AXIOS](h
 This is just an example showing you how you can structure your code for optimal testability. You might prefer a different approach or maybe rely on integration tests for this. No worries, you do what makes most sense for your application:
 
 {% tabs %}
-{% tab title="overmind/effects.ts" %}
+{% tab title="overmind/effects.js" %}
 ```typescript
 import * as axios from 'axios'
-import { Post } from './state'
-
-interface IRequest {
-  get<T>(url: string): Promise<T>
-}
-
-interface IOptions {
-  authToken: string
-  baseUrl: string
-}
 
 // This is the class we can create new instances of when testing
 export class Api {
-  request: IRequest
-  options: IOptions
-  constructor(request: IRequest, options: IOptions) {
+  constructor(request, options) {
     this.request = request
     this.options = options
   }
-  async getPost(id: string): Promise<Post> {
+  async getPost(id: string) {
     try {
       const response = await this.request.get(this.options.baseUrl + '/posts/' + id, {
         headers: {
@@ -247,7 +229,7 @@ export const api = new Api(axios, {
 Let’s see how you could write a test for it:
 
 {% tabs %}
-{% tab title="overmind/effects.test.ts" %}
+{% tab title="overmind/effects.test.js" %}
 ```typescript
 import { Api } from './effects'
 

introduction.md

@@ -8,7 +8,11 @@ If you rather want to go right ahead and set up a local project, please have a l
 
 Before we move on, have a quick look at this sandbox. It is a simple counter application and it gives you some foundation before talking more about Overmind and building applications.
 
-{% embed url="https://codesandbox.io/s/overmind-counter-c4tuh?from-embed" %}
+{% embed url="https://codesandbox.io/embed/overmind-counter-c4tuh?fontsize=14&hidenavigation=1&theme=dark&view=editor" %}
+
+
+
+
 
 ## Application state VS Component state
 
@@ -93,7 +97,7 @@ And as we will see later you will also be using **effects** from the context.
 
 Now we will move to a more complex example. Please have a look:
 
-{% embed url="https://codesandbox.io/s/overmind-todomvc-simple-097zs?from-embed" %}
+{% embed url="https://codesandbox.io/embed/overmind-todomvc-simple-097zs?fontsize=14&hidenavigation=1&module=%2Fsrc%2Fapp.js&theme=dark&view=editor" %}
 
 We have now separated out the Overmind related logic into its own file, **app.js**. This file creates the Overmind instance and also exports how the components will interact with the state and the actions, the hook called **useApp**. Vue and Angular has other mechanisms conventional to those frameworks where application state and actions can be accessed.
 
@@ -183,7 +187,7 @@ Any function you insert into the state tree is treated as derived state. That me
 
 Now let us move into an even more complex application. Here we have added **effects**. Specifically effects to handle routing, storing todos to local storage and producing unique ids for the todos. We have added an **onInitialize** hook which is a special function Overmind runs when the application starts.
 
-{% embed url="https://codesandbox.io/s/overmind-todomvc-2im6p?from-embed" %}
+{% embed url="https://codesandbox.io/embed/overmind-todomvc-2im6p?fontsize=14&hidenavigation=1&module=%2Fsrc%2Fapp.js&theme=dark&view=editor" %}
 
 You can think of effects as a contract between your application and the outside world. You write an effect API of **what** your application needs and some 3rd party tool or native JavaScript API will implement **how** to provide it. Let us look at the router:
 
@@ -223,7 +227,7 @@ This argument passed is transformed into something Page can understand. What thi
 
 Defining all the state, actions and effects on one object would not work very well for a large application. A convention in Overmind is to split these concepts into different files behind folders representing a domain of the application. In this next sandbox you can see how we split up state, actions and effects into different files. They are all exposed through a main file representing that domain, in this case “the root domain”:
 
-{% embed url="https://codesandbox.io/s/overmind-todomvc-split-xdh41?from-embed" %}
+{% embed url="https://codesandbox.io/embed/overmind-todomvc-split-xdh41?fontsize=14&hidenavigation=1&module=%2Fsrc%2Fapp%2Findex.js&theme=dark&view=editor" %}
 
 Also notice that we have split up the instantiation of Overmind from the definition of the application. What this allows us to do is reuse the same application configuration for testing purposes and/or server side rendering. We separate the definition from the instantiation.
 
@@ -239,7 +243,7 @@ Have a look at this new project where we have typed the application:
 You have to **OPEN IN EDITOR** to get the full Typescript experience.
 {% endhint %}
 
-{% embed url="https://codesandbox.io/s/overmind-todomvc-typescript-39h7y?from-embed" %}
+{% embed url="https://codesandbox.io/embed/overmind-todomvc-typescript-39h7y?fontsize=14&hidenavigation=1&module=%2Fsrc%2Fapp%2Findex.ts&theme=dark&view=editor" %}
 
 As you can see we only have to add an **Action** type to our functions and optionally give it an input type. This is enough for the action to give you all information about the application. Try changing some code and even add some code to see how Typescript helps you to explore the application and ensure that you implement new functionality correctly.
 

quickstart.md

@@ -35,7 +35,7 @@ export const state = {
 ```
 {% endtab %}
 
-{% tab title="overmind/index.ts" %}
+{% tab title="overmind/index.js" %}
 ```typescript
 import { state } from './state'
 
@@ -44,41 +44,20 @@ export const config = {
 }
 ```
 {% endtab %}
-{% endtabs %}
-
-And fire up your application in the browser or whatever environment your user interface is to be consumed in by the users.
-
-### VS Code
-
-For the best experience you should install the [OVERMIND DEVTOOLS](https://marketplace.visualstudio.com/items?itemName=christianalfoni.overmind-devtools-vscode) extension. This will allow you to work on your application without leaving the IDE at all.
-
-![](.gitbook/assets/amazing_devtools.png)
-
-{% hint style="info" %}
-If you are using the **Insiders** version of VSCode the extension will not work. It seems to be some extra security setting.
-{% endhint %}
-
-### Devtool app
 
-Alternatively you can install the standalone application of the devtools. It is highly recommended to install the package [CONCURRENTLY](https://www.npmjs.com/package/concurrently). It allows you to start the devtools as you start your build process:
+{% tab title="index.js" %}
+```typescript
+import { createOvermind } from 'overmind'
+import { config } from './overmind'
 
-```text
-npm install overmind-devtools concurrently
+const overmind = createOvermind(config)
 ```
+{% endtab %}
+{% endtabs %}
 
-{% code title="package.json" %}
-```javascript
-{
-  ...
-  "scripts": {
-    "start": "concurrently \"overmind-devtools\" \"someBuildTool\""
-  },
-  ...
-}
-```
-{% endcode %}
+And fire up your application in the browser or whatever environment your user interface is to be consumed in by the users.
 
-### Hot Module Replacement <a id="quickstart-hot-module-replacement"></a>
+Move on with the specific view layer of choice to connect your app:
 
-A popular concept introduced by Webpack is [HMR](https://webpack.js.org/concepts/hot-module-replacement/). It allows you to make changes to your code without having to refresh. Overmind automatically supports HMR. That means when **HMR** is activated Overmind will make sure it updates and manages its state, actions and effects. Even the devtools will be updated as you make changes.
+\*\*\*\*[**REACT** ](views/react.md)**-** [**ANGULAR**](views/angular.md) **-** [**VUE**](views/vue.md)\*\*\*\*