DEV Community: Konrad Abe

Tech Explained - a low-level primer on frontend technology

Konrad Abe — Thu, 09 Jun 2022 20:06:17 +0000

No matter whether you are a decision-maker, a junior dev, a recruiter or a project manager, our industry has created a plethora of buzzwords and deemed them industry standards on different levels.

This article will tackle some of the more prominent Marketing/CV Buzzwords in an attempt to explain them just deep enough to grasp the core idea for more educated decisions in the future.

At the end of the article, I will also include a link list for the different topics of this article.

JavaScript Versions

ECMAScript, JavaScript, ES5, ES6, ES2015, ES.Next…

Sounds weird, right?

The naming convention for JavaScript versions leaves room for improvement, I grant you that. JavaScript was released in 1995 as part of Netscape Navigator, labelled as LiveScript. A year later, it was renamed JavaScript in a (not so) clever marketing attempt, despite having nothing to do with Java in any way. Later that year, JavaScript was submitted to ECMA International and re-labelled again.

Today, JavaScript is the accepted name of the programming language while ECMA versions are mostly used to differentiate between versions. Well, after being nearly stagnant for 15 years…

JavaScript runs in (almost) every browser which means that browser vendors need to update their own implementation to match new ECMA versions, leading devs to track support for new features and to wait for browser vendors to follow new developments.

Tools like the pre-compiler Babel allows developers to use newer features by transpiling new code features into older and cross-browser compatible alternatives.

Here's a quick rundown of the most important versions:

ECMAScript 3 (ES3) | This version is what most people had accepted as plain or vanilla JavaScript for many years and was released in 1999.
ECMAScript 5 (ES5) | The 5th edition of ECMAScript, standardised in 2009, was the first big step for developers and the beginning of the separation of JavaScript developers into those that know the new features and those who don't. This was a top interview question for a long time.
ECMAScript 6 (ES6)/ ECMAScript 2015 (ES2015)
ECMAScript 7 (ES7)/ ECMAScript 2016 (ES2016)
ECMAScript 8 (ES8)/ ECMAScript 2017 (ES2017)
ECMAScript 9 (ES9)/ ECMAScript 2018 (ES2018)
…

As you can see, starting with 2015 a more regular and streamlined pace was established. By far the biggest and most popular step was going to ES5 and while more recent versions also come with increasingly modern and amazing features, they pale in terms of popularity impact compared to ES5.

The whole process is rounded up by a proposal stage for new features not yet standardised and officially released. This is nice for playing around and all that but it is not.

Where is this relevant?

Basically everywhere: frontend, backend, web, mobile, maybe even your next office coffee maker… To say it with the famous words of Jeff Atwood:

"Any app that can be written in JavaScript, will eventually be written in JavaScript."

Typescript (TS)

Javascript has long been criticised by many for its many quirks, lazy (loose) typing and other shortcomings. There have been famous (and funny) talks and presentations about this (search for Gary Bernhardt's "Wat" talk, if you want to get an idea). Long story short, JavaScript runs almost everywhere and by now you can build almost anything in JavaScript. Wouldn't it be great to fix that?

Well, as JavaScript already runs everywhere, you can not simply update it to remove these quirks and issues. So this is where Typescript comes in.

Typescript is basically an abstraction layer, a superset of JavaScript, that comes with its own pre-compiler and allows the programmer to write cleaner and strongly typed typescript code that will be compiled into regular but better JavaScript code.

And to make things easier to migrate old code, all JavaScript is basically valid typescript, just without the new tools and advantages so transitioning old applications into a new typescript form can happen line by line or file by file.

So what are the advantages of Typescript?

We can define types and interfaces for our variables, objects and functions.
We gain inheritance and composition for types and interfaces.
We receive instant feedback (in supporting IDEs) about type conflicts when calling a function, using a variable or receiving an output.
Typescript helps your IDE to give you more information and assistance with your code.
We get some basic assistance during refactoring, as types and interfaces give us more confidence in our code.
Typed code (with readable variable names) already offers a basic form of in-code documentation without a single line of comments.
A certain amount of bugs can be caught earlier.

What will Typescript not solve/offer?

Typescript will not catch all bugs in your code, especially when working with 3rd party APIs.
I often hear that Typescript will reduce bugs by 60% but to get this high of an improvement, the code must have been pretty bad even for regular JavaScript levels.
Typescript is an extra abstraction for your code. While some programmers swear by it, a new hire might not be able to work on your codebase if they lack Typescript Know-How.
Depending on your code-base, some edge cases might be hard to map with correct types/interfaces, leading to longer development time.

Before we move on, I'd like to quickly point out that from my experience, the last point on that "CON" list is often (not always) a sign of code smell, something that hints at "magic code" or stuff that is written either too complex or too clever to be good, stable and maintainable code.

This also brings us to one of my personal favourites about Typescript: it nudges us towards thinking more about the code we write, before we write it, not unlike TDD. When working with separate teams for Backend/API and Frontend code, predefining API contracts with Typescript allows us to mock data and work independently based on the formed API contract between both teams.

Where is this relevant?

Anywhere where JavaScript runs: In a browser, on Node.js or Deno and in your apps. Especially for DevOps and Backend developers writing Node.js code and coming from more object-oriented languages, Typescript can be an extra layer of comfort when writing JavaScript code.

Functional Programming (FP)

Keeping it very basic, Functional Programming is a programming paradigm that does not allow any mutations of data or uses any shared state. The main premise is that a function, run with identical input, will always return the same output and will not change any of the input values. It is declarative rather than procedural or imperative.

This paradigm makes functional code easily testable and predictable and often results in cleaner code, shorter functions and overall code that's easier to read and argue about on a human level.

Very similar to Typescript, Functional Programming does not have to be an all-in way to do things. Lending concepts from the functional paradigm can greatly increase the quality and even reusability of your code without forcing you to completely rewrite your existing codebase and even ties in greatly with stronger typing. JavaScript is a multi-paradigm programming language and allows us to take the best from multiple words to use where we gain the most of it.

Where is this relevant?

There are fully functional programming languages with a different level of support for this paradigm but basically, the concept of Functional Programming can be used anywhere you run your JavaScript code, so again, this is relevant for both Frontend and Backend (node) as well as native apps.

Test Driven Design (TDD)

Test-driven development is the software development practice of writing tests that match your expectations or requirements before you write the code to fulfil these.

RED -> GREEN -> BLUE (test, code, refactor).

TDD can fit in well with your existing agile workflow and has its roots in the Agile Manifesto.

RED | Test

A new feature should have a full description of the expected outcome. The team or developer can now transform these specifications into one or multiple simple (unit) tests based on their initial understanding and either check them manually or preferably integrate them with your automated testing. This will bring us to our first state: "RED" because these tests will now fail.

GREEN | Code

The second step is to write the most simple version of code to pass these tests. The idea is to make the most minimal change needed to pass these tests and reach the second state: "GREEN"

BLUE | Refactor

The third step is basically checking the existing code and tests for edge cases, performance issues and possible code optimisations and whether or not the initial feature requirements are fulfilled.

If you learned about unexpected issues during development, requirements changed or your new understanding of the task tells you that your tests need to be adjusted, you go back to the first step and adjust or add to your tests so that you will again get red test failures, iterating over these 3 steps until the task is feature-complete.

Existing tests from previous tasks will help you confirm that other code should not be affected by your changes.

Where is this relevant?

Again, basically, anywhere you write code. There is a small reality check in this case though. The practice of TDD will create a larger up-front workload before you can finish a task and many programmers muse that TDD is something they would like to do but their day-to-day business does not allow them to follow these principles.

Depending on how much code coverage with unit tests your team is trying to reach and how much time you have available, TDD might be a lot of overhead at first and there is a strong bias against it. From my experience though, teams that adapted this practice, apply a good measure of common sense and strike a good balance between code coverage and team performance (GTD or getting things done), during the later development phases of such projects, the existing tests help greatly track new bugs early and before deploying to a client's server.

React, Angular & Vue

React, Angular and Vue are three common tools to use when building websites. Angular and Vue are considered Javascript Frameworks that come with a bigger package of paradigms and restrictions while at the same time also bringing more functionality to the table. React, on the other hand, can be seen more as a library than a framework. It gives the developer more freedom in how to set up the website, at the same time resulting in more responsibility for the developer as well as a larger footprint.

At the end of the day, this article will not try to pick the best of the 3 solutions but I will try to give my personal experience without going too much into detail.

Both my current and my previous team decided to use React, not because it was better but because it felt more natural for us and had a good learning curve to get started. Angular is a fully-fledged framework with all the bells and whistles, but it can also be a bit overwhelming for new developers. Vue on the other hand never felt "right" for us. It is not good or bad, just different and between these three, working with React seemed to most closely resemble working with regular JavaScript. Additionally, switching over to React + Typescript is really simple and by now we migrated all major projects to Typescript.

Where is this relevant?

All three are primarily solutions to build web frontends and interfaces but can be combined with many different CMS backends when needed.

Redux

Redux is a predictable state container for JavaScript apps.

Redux is an open-source JavaScript library for managing and centralising the application state. The Redux store serves as a single point of truth and the simple one-directional messaging system at the core of Redux can help developers to build a scalable and robust client-side application data solution.

While often used in concert with Angular or React, Redux can be used in other constellations too and resembles Facebook's Flux Architecture in many ways.

With only 2kb for the basic install, Redux is tiny but it can easily be extended with custom middleware and there are existing solutions for integrations of data fetching, and other asynchronous tasks. With the Redux Toolkit (RTK), developers are also freed from the burden of writing boilerplate code.

Where is this relevant?

Again, this is a frontend library so no server-side to this either.

Wrapping Up

I hope this article helped you get some basic knowledge about some of the bigger buzzwords thrown around by recruiters, managers and some techies. I will follow up with two in-depth articles about typescript and functional programming, their PROs and CONs as well as some integration examples with other things from today's list such as React and Redux.

Link List

About Das Büro am Draht

Das Büro am Draht is a Berlin-based consultancy helping our clients to build resilient and adaptable digital platforms to support today's business requirements and even launch tomorrow's business models we might not yet foresee. Hence, we work closely together at every stage of the digital transformation process - from digital strategy to solution design & development to operational support. Our agile approach to developing versatile and scalable solutions ensures that our clients consistently deliver engaging and personalized customer experiences. To learn more about how we help companies across industries, follow us on LinkedIn.

Illustrations: kai_sinzinger

SERIES: React Native (Step by Step) - Nested Navigation, Persistent Redux Store and Returning Users

Konrad Abe — Sun, 02 May 2021 20:01:30 +0000

Last time we had a look at a more complex navigation flow using the AuthFlow Pattern. This time we will look into different types of nested navigations and adjust our main navigation flow a bit more to take care of persisted user data/login state and such.

Nested Navigation inside a screen

Here is a quick preview of what we will start with today.

For our first trick, we need a new type of navigation so we will grab it from npm real quick. I'll show you how to set up a nice and pre-styled material design tab navigation for our settings page.

@react-navigation/material-top-tabs
react-native-pager-view
react-native-tab-view

expo install @react-navigation/material-top-tabs react-native-pager-view react-native-tab-view

On our SettingsScreen.tsx we will use a new component with some simple mocked pages, including one really long scrollable list. We also import our createMaterialTopTabNavigator element from the material-top-tabs package to define the navigator we will implement within our page.

// File: src/components/demo/Settings.tsx
import React from 'react'
import { StyleSheet, View, Text, ScrollView } from 'react-native'
import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs'

const Tab = createMaterialTopTabNavigator()

const TabOne = () => (
    <View>
        <Text>Tab One</Text>
    </View>
)
const TabTwo = () => (
    <ScrollView>
        <Text />
        {Array(42)
            .fill('Tab Two')
            .map((text: string, index) => {
                const tabContent = `${text} (${index})`
                return <Text key={tabContent}>{tabContent}</Text>
            })}
    </ScrollView>
)
const TabThree = () => (
    <View>
        <Text>Tab Three</Text>
    </View>
)

const SettingTabs = () => {
    return (
        <Tab.Navigator>
            <Tab.Screen name="SettingsOne" component={TabOne} />
            <Tab.Screen name="SettingsTwo" component={TabTwo} />
            <Tab.Screen name="SettingsThree" component={TabThree} />
        </Tab.Navigator>
    )
}

const Settings = (): React.ReactElement => {
    return (
        <View style={styles.settingsBox}>
            <SettingTabs />
        </View>
    )
}

const styles = StyleSheet.create({
    settingsBox: {
        backgroundColor: '#ccc',
        width: 300,
        height: 500,
        borderWidth: 4,
        borderColor: '#000',
        borderRadius: 5,
    },
})

export default Settings

A small detail you will need to keep in mind when nesting navigators is that each navigator keeps track of its own history, params and options.

When navigating, React Navigation will search in its current scope for a navigator. If none is present, it will bubble up a level to the parent components until it finds a navigator to perform navigation actions on. For additional details, you should take the time (5 minutes tops) to read the official documentation.

// File: src/screens/SettingsScreen.tsx (partial)
const SettingsScreen = ({ navigation }: SettingsScreenProps): React.ReactElement => (
    <View style={styles.page}>
        <Text>SETTINGS</Text>
        <Settings />
        <Button title="back" onPress={() => navigation.goBack()} />
    </View>
)

When we add our new Settings component to our SettingsScreen, we now have a nested in-page navigation element that works independently from its parent navigation container.

Nested Navigation inside a navigator as a screen

Instead of placing a navigatable component within your screen, you can also use it as a screen on its own. Let's say our home screen consists of 3 different pages you can switch between.

For this example, we will use a more bare bone basic bottom-tabs navigator.

expo install @react-navigation/bottom-tabs

For this example, I will simply copy and adjust our existing home screen. Feel free to flesh it out a bit more to get something less copypasta and more life-like, if you want. You could turn them into a news, home and category screen for your app or something along those lines.

// File src/screens/HomeScreenB.tsx // and HomeScreenC.tsx
import React from 'react'
import { Text, View, StyleSheet, Button } from 'react-native'
import { MainNavigationProp } from '../../routing/types'
import { MainRoutes } from '../../routing/routes'

type HomeScreenProps = {
    navigation: MainNavigationProp<MainRoutes.Home>
}
const HomeScreenB = ({ navigation }: HomeScreenProps): React.ReactElement => (
    <View style={styles.page}>
        <Text>Seection B</Text>
        <Button title="settings" onPress={() => navigation.navigate(MainRoutes.Settings)} />
    </View>
)

const styles = StyleSheet.create({
    page: {
        flex: 1,
        backgroundColor: '#fff',
        alignItems: 'center',
        justifyContent: 'center',
    },
})

export default HomeScreenB

Now go to the routes.ts file and add our new routes. We'll define a new enum for the HomeRoutes and use it to create our HomeTabsParamList as we did before with our MainStackParamList.

In the MainNavigation component, we can now create a new Navigator using our HomeTabs instead of the MainStack and add 3 screens to it, our existing home screen and the 2 new ones.

A bit further down, we replace the HomeScreen component with our new Home Navigator component and that's it.

And that's it, we now have a 3-tabs nested navigator without our main stack on the same level as the settings screen.

Adding Persistence to our Redux Store

You might want to keep some user data stored locally between sessions. For that, we can make use of redux-persist and react natives async storage.

I've already started writing a separate article about Redux, Persist and different way to consolidate and rehydrate state data including ways to migrate old persisted data when the app changed. For now, I'll stick to the basics.

expo install redux-persist @react-native-async-storage/async-storage

For now, we want to make the user data persistent. This means that upon re-opening the app, the user email and logged in state will still be set so that we can skip the login screens.

Redux persist requires a few minor changes to our redux code and App file. First of all, we need to import AsyncStorage as well as persistStore and persistReducer in our central redux file.

// File: src/redux/index.ts (partial 1)
import { persistStore, persistReducer } from 'redux-persist'
import AsyncStorage from '@react-native-async-storage/async-storage'

const persistConfig = {
    key: 'root',
    storage: AsyncStorage,
    whitelist: ['user'],
}

const persistedReducer = persistReducer(persistConfig, rootReducer)

The persist config contains a key, our storage engine and a whitelist of the reducers we want to rehydrate when we restart the app. Key and the storage engine are required while the whitelist attribute is optional. We could go with a whitelist (mark what we keep), blacklist (mark what we don't want to keep) or neither and keek all the data.

I prefer whitelisting for this because I'm more in control when I later add more and more reducers that I might never need on the next startup. Persisted data should always serve a real purpose and should be chosen wisely. Hence, whitelists are the way to go.

When we set up our store with configureStore, we need to make 2 small changes. Instead of our rootReducer, we now use the persistedReducer (containing our rootReducer) and as we are currently using the serializableCheck middleware that comes with Redux Toolkit, we need to put a few things on the blacklist so they don't get checked. The actions you see here under ignoredActions are all imported from redux-persist as well.

// File: src/redux/index.ts (partial 2)
const store = configureStore({
    reducer: persistedReducer,
    middleware: getDefaultMiddleware =>
        getDefaultMiddleware({
            serializableCheck: {
                /* ignore persistance actions */
                ignoredActions: [FLUSH, REHYDRATE, PAUSE, PERSIST, PURGE, REGISTER],
            },
        }).prepend(rootMiddleware),
})

export const persistor = persistStore(store)

In addition to our regular redux code, we will also export a persistor, a higher-order function using our store. You will see in a moment, what we need it for.

Moving on to our central entry point, we need to make a small adjustment to our code. We are importing a PersistGate from the react specific module of redux-persist and our new persistor and we will wrap everything inside our Redux Store Provider in the PersistGate component.

// File: App.tsx
import React from 'react'
import { Provider } from 'react-redux'
import { StatusBar } from 'expo-status-bar'
import { enableScreens } from 'react-native-screens'
import { PersistGate } from 'redux-persist/integration/react'
import store, { persistor } from './src/redux'
import MainNavigation from './src/routing/MainNavigation'

enableScreens()

export default function App(): React.ReactElement {
    return (
        <Provider store={store}>
            <PersistGate loading={null} persistor={persistor}>
                <StatusBar hidden />
                <MainNavigation />
            </PersistGate>
        </Provider>
    )
}

The PersistGate will serve as a gatekeeper that will not let the user pass until the state has been rehydrated with the stored values. This will prevent a lot of bugs and issues to occur from working with an incomplete or wrong state in the redux store. Additionally, you can register a component with the PersistGate using the loading={} attribute. This component will b shown until the store is ready to be used again.

Persisted Login in our Navigation Flow

For our final adjustments to the authentification and navigation flow, I will briefly skip over some simple parts that are mostly variations of what we did before.

Our plan is as follows. A new user goes through the whole authFlow as before while a logged-in user skips a few screens.

=> start with Auth Stack
Splash
AppCheck
Login/SignUp (skip when already logged in)
AppLoading
=> switch to App Stack
Home / Settings / etc

A new slice for our store

First of all, we need to add a new reducer to our store. For now, we will only put the app state (app finished all checks and loading and is now properly running) here but it is important to NOT put this on the whitelist. We want this to be reset at each start of the app.

// File: src/redux/ducks/appState.ts
import { createAction, createReducer } from '@reduxjs/toolkit'
import { RootState } from '../index'

type AppState = {
    isRunning: boolean
}

const initialState: AppState = {
    isRunning: false,
}

export const setRunning = createAction('[APPSTATE] Set Running', (running: boolean) => ({
    payload: {
        running,
    },
}))

export const selectIsRunning = (state: RootState): boolean => state.appState.isRunning

const appStateReducer = createReducer(initialState, builder => {
    builder.addCase(setRunning, (state, action) => {
        const { running } = action.payload
        return {
            isRunning: running,
        }
    })
})

export default appStateReducer

Then we will replace the navigation and useEffect from the AppLoadingScreen and replace it with our new redux action in a useFocusEffect. The idea is to check all user data on this screen and once everything is checked and loaded, the user is switched over to the other navigation stack.

// File: src/screens/AppLoadingScreen.tsx (partial)
import React, { useCallback } from 'react'
import { Text, View, StyleSheet } from 'react-native'
import { useFocusEffect } from '@react-navigation/native'
import { useReduxDispatch } from '../../redux'
import { setRunning } from '../../redux/ducks/appState'

const AppLoadingScreen = (): React.ReactElement => {
    const dispatch = useReduxDispatch()

    useFocusEffect(
        useCallback(() => {
            setTimeout(() => {
                /* 
                 * fake timer where you would instead 
                 * load and check the user data before
                 * you send the user to the App Stack
                 */
                dispatch(setRunning(true))
            }, 1500)
        }, [dispatch]),
    )

    return (
        <View style={styles.page}>
            <Text>loading User Data...</Text>
        </View>
    )
}

In our MainNavigation, we need to make 2 smaller adjustments. For one we will now put the AppLoading screen into the auth stack (last screen). The second change is to switch from selectLogin to selectIsRunning.

On our login and signup screens, we will add a watcher to the login state and trigger a navigation action when isLoggedIn changes and is set to true.

Navigating based on state

On our AppCheck, we will take a look at the login state for our user and direct signed in users directly to the AppLoading while everyone else will see the sign in next.

Keep in mind that we need to use a useCallback hook here because otherwise our getRoute would be recreated on every render and trigger our other useCallback that is responsible for our login.

// File: sc/screens/AppCheckScreen.tsx (partial)
import React, { useCallback } from 'react'
import { Text, View, StyleSheet } from 'react-native'
import { useFocusEffect } from '@react-navigation/native'
import { MainNavigationProp } from '../../routing/types'
import { MainRoutes } from '../../routing/routes'
import { useReduxSelector } from '../../redux'
import { selectLogin } from '../../redux/ducks/user'

type AppCheckScreenProps = {
    navigation: MainNavigationProp<MainRoutes.AppCheck>
}

const AppCheckScreen = ({ navigation }: AppCheckScreenProps): React.ReactElement => {
    const isLoggedIn = useReduxSelector(selectLogin)

    const getRoute = useCallback(() => (
        isLoggedIn 
            ? MainRoutes.AppLoading 
            : MainRoutes.SignIn
    ), [isLoggedIn])

    useFocusEffect(
        useCallback(() => {
            setTimeout(() => {
                /* 
                 * fake timer where you would instead 
                 * load and check the app version
                 * and possible breaking changes before
                 * you send the user to the App Stack
                 */
                navigation.navigate(getRoute())
            }, 1500)
        }, [navigation, getRoute]),
    )

    return (
        <View style={styles.page}>
            <Text>loading App Data...</Text>
        </View>
    )
}

The last thing to do now is to adjust our userReducer so that when a user is logged our not only his login status changes but also the appStatus. This will cause him to be switched back to the AuthFlow navigation stack where he starts on the splash screen again and can log in or sign up as a different user.

Wrapping Up

I think we've covered a lot of ground today and learned a few useful techniques when working with navigation. Next time we will look into styling react native components with … styled-components, one of a few good solutions for writing CSS in JS. A few years back this sentence would have made my skin crawl but bear with me and I will show you how to do so and NOT feel like betraying years of Frontend Developer Experience.

SERIES: React Native (Step by Step) - Auth Flow Navigation with Mock User Login

Konrad Abe — Sun, 25 Apr 2021 21:12:28 +0000

Preparations

For our AuthFlow example, we need a few additional screens. For one we want to allow the user to both sign in (existing users) and sign up (new users) and in addition to the AppLoading screen (for loading / initialising user data) I've added an AppCheck screen where I will, later on, check for version updates in the app stores and such.

I went one step further and split them into AuthStack (sign in/sign up) and InitStack (splash screen, and a screen for the app to check version updates and such). We won't use this immediately but that way we won't have to reshuffle everything later on.

// File: src/routing/routes.ts
import { createStackNavigator } from '@react-navigation/stack'

export enum MainRoutes {
    // Init Stack
    Splash = 'Splash', // display a logo or splash image
    AppCheck = 'AppCheck', // check vital stuff, forced app updates and such

    // Auth Stack
    SignIn = 'SignIn', // existing user entry point
    SignUp = 'SignUp', // new user entry point

    // App Stack
    AppLoading = 'AppLoading', // Load User Data for signed in users
    Home = 'Home', // The first "real" page of the app
    Settings = 'Settings', // Default Settings Page
}

export type MainStackParamList = {
    // Init Stack
    [MainRoutes.Splash]: undefined
    [MainRoutes.AppCheck]: undefined

    // Auth Stack
    [MainRoutes.SignIn]: undefined
    [MainRoutes.SignUp]: undefined

    // App Stack
    [MainRoutes.AppLoading]: undefined
    [MainRoutes.Home]: { update: boolean } | undefined // just an example, "update" will later be used for version checks
    [MainRoutes.Settings]: undefined
}

export const MainStack = createStackNavigator<MainStackParamList>()

Here is a list of our old and new screen components, sorted by their stack. You can copy one of the existing screens, I copied the old SplashScreen as it already had the redux code we'll use later. For the AppCheckScreen I simply made a copy of our AppLoadingScreen from before.

Don't worry too much about this, we will address those later, one by one.

In our MainNavigation component, we add the new screens accordingly. The stacks separation I prepared above won't be represented here for now so Splash, AppCheck, SignIn and SignUp are all for the "not logged in" users.

// File: src/routing/MainNavigation.tsx
// (partial)
const MainNavigation = (): React.ReactElement => {
    const isLoggedIn = useReduxSelector(selectLogin)

    return (
        <NavigationContainer>
            <MainStack.Navigator headerMode="none">
                {isLoggedIn ? (
                    <>
                        <MainStack.Screen name={MainRoutes.AppLoading} component={AppLoadingScreen} />
                        <MainStack.Screen name={MainRoutes.Home} component={HomeScreen} />
                        <MainStack.Screen name={MainRoutes.Settings} component={SettingsScreen} />
                    </>
                ) : (
                    <>
                        <MainStack.Screen name={MainRoutes.Splash} component={SplashScreen} />
                        <MainStack.Screen name={MainRoutes.AppCheck} component={AppCheckScreen} />
                        <MainStack.Screen name={MainRoutes.SignIn} component={SignInScreen} />
                        <MainStack.Screen name={MainRoutes.SignUp} component={SignUpScreen} />
                    </>
                )}
            </MainStack.Navigator>
        </NavigationContainer>
    )
}
export default MainNavigation

Skippable Splash Screen

Starting with the SplashScreen, we're building a small mechanism to trigger a navigation event after a few seconds or when the user taps the screen to trigger it manually. This is a common pattern you see in many apps.

Instead of the useEffect hook you are probably familiar with by now, we will be using the useFocusEffect() hook from react navigation because it will "mount" and "unmount" when the screen gains and loses focus. A common pitfall of Navigation stacks is that screens do not "unmount" when you navigate away within the same stack which means that your useEffect() cleanup will not be triggered.

On focus of this screen, we start a timeout and store the timeoutID in a const to use for the clean-up of the running timer when the user taps on the screen to navigate. As recommended by the docs, we are wrapping our code in a useCallback() hook to prevent running the code too often and do the same for the navigate() function that we use for timer and onPress event.

// File: src/screens/SplashScreen.tsx
// (partial)
const SplashScreen = ({ navigation }: SplashScreenProps): React.ReactElement => {
    const navigate = useCallback(
        () => navigation.navigate(MainRoutes.AppCheck),
        [navigation],
    )

    useFocusEffect(
        useCallback(() => {
            const navigationTimer = setTimeout(() => {
                navigate()
            }, 3000)

            return (): void => clearTimeout(navigationTimer)
        }, [navigate]),
    )

    return (
        <TouchableWithoutFeedback onPress={() => navigate()}>
            /* skipped for brevity ... */
        </TouchableWithoutFeedback>
    )
}

I had to bump my eslint for hooks from 4.0.0 to 4.0.3 to get rid of a false positive for useFocusEffect as the "Effect" suffix triggered a rule it should not. If you use my code from the last session, you might need to do that too.

Version bumped to this => "eslint-plugin-react-hooks": "^4.0.3"

At this point and to test our new pages and routes, our SignUp and SignIn screens will be mocked placeholders, simply using the redux action to mock a successful login. I've also added a small button to navigate between SignUp and SignIn.

// File: src/screens/SignInScreen.tsx | SignUpScreen.ts
import React from 'react'
import { Text, View, StyleSheet, Button } from 'react-native'
import { MainNavigationProp } from '../../routing/types'
import { MainRoutes } from '../../routing/routes'
import { useReduxDispatch } from '../../redux'
import { setLogin } from '../../redux/ducks/user'

type SignInScreenProps = {
    navigation: MainNavigationProp<MainRoutes.SignIn>
}
const SignInScreen = ({ navigation }: SignInScreenProps): React.ReactElement => {
    const dispatch = useReduxDispatch()

    const handleClick = (): void => {
        dispatch(setLogin(true))
    }

    return (
        <View style={styles.page}>
            <Text>Sign In</Text>
            <Button title="Continue" onPress={() => handleClick()} />
            <Button title="Sign Up" onPress={() => navigation.navigate(MainRoutes.SignUp)} />
        </View>
    )
}

const styles = StyleSheet.create({
    page: {
        flex: 1,
        backgroundColor: '#fff',
        alignItems: 'center',
        justifyContent: 'center',
    },
})

export default SignInScreen

Mocking the login

I will briefly go over the mock login I'm using. To represent real server/api interaction, I've mocked a promise using a timeout that will return the expected mock values. I'm skipping the types I've used and advise you to simply copy the full file from GitHub as this is only a mock authentification and not the focus of this article.

const mockSuccess = (value: SuccessValue): Promise<SuccessValue> => {
    return new Promise(resolve => {
        setTimeout(() => resolve(value), 2000)
    })
}

const mockFailure = (value: FailureValue): Promise<FailureValue> => {
    return new Promise((resolve, reject) => {
        setTimeout(() => reject(value), 2000)
    })
}

We can now use this to create a simple login and register call. The fake login can be set to fail by supplying an additional boolean as a third parameter (useful for testing) but other than that will expect an email and password and tries to match those to our user array. All in plain text, as you would expect from a ~~first class~~ cheap mock api.

I've added a slight variation in form of a createAccount function as well for the SignUp. The response contains a token that would be saved and used in all following requests to pass as a logged-in user in a real application.

const mockCheckLoginData = (email: string, password: string): boolean =>
    fakeUserData.filter(data => data.email === email && data.password === password).length > 0

export const login = (
    email: string,
    password: string,
    shouldFail = false,
): Promise<mockRequestValue> => {
    if (shouldFail) {
        return mockFailure({ error: 500, message: 'Request failed successfully!' })
    }

    if (!mockCheckLoginData(email, password)) {
        return mockFailure({
            error: 401,
            message: 'Login failed, email or password did not match!',
        })
    }

    return mockSuccess({ authToken: 'mock_token_value' })
}

export const createAccount = (
    email: string,
    password: string,
    shouldFail = false,
): Promise<mockRequestValue> => {
    if (shouldFail) {
        return mockFailure({ error: 500, message: 'Request failed successfully!' })
    }

    return mockSuccess({ authToken: 'mock_token_value' })
}

Wiring up Redux and Mock API

We now need to do the real work, setting up the real redux code for users so our previous user.ts duck will now be rewritten completely.

Let's start with our annotations and initial state. The login will be a simple boolean, just as before but additionally we will keep track of the login state to make a differentiation between not logged in, logged out and failed to log in as well as loading during the login.

Also, we will store the user email, a message text and a flag to mark newly registered users. This way we can display login errors from our api or a message for a user that successfully logged out and perform additional things for new users that might not have been fully set up yet, depending on the app you are planning to build.

type LoginState = 'init' | 'loading' | 'denied' | 'loggedOut'

type UserState = {
    login: boolean
    loginState?: LoginState
    email?: string
    newUser?: boolean
    message?: string
}

const initialState: UserState = {
    login: false,
    loginState: 'init',
}

Actions

We will use the setLogin action to store a logged-in user's info in our state. This action will no longer be called directly from the app. Instead, we will use if in the userMiddleware we are about to write.

The new setLogout action will contain the new loginState and message, again mainly to be used within our middleware.

export const setLogin = createAction('[USER] Set Login', (email: string, newUser: boolean) => ({
    payload: {
        email,
        newUser,
    },
}))

export const setLogout = createAction(
    '[USER] Set Logout',
    (loginState?: LoginState, message?: string) => ({
        payload: {
            loginState,
            message,
        },
    }),
)

When the user tries to log in or sign up, he will only enter an email and password. We will do the rest in our middleware and reducer.

export const attemptLogin = createAction(
    '[USER] attempt Login',
    (email: string, password: string) => ({
        payload: {
            email,
            password,
        },
    }),
)

export const attemptSignUp = createAction(
    '[USER] attempt SignUp',
    (email: string, password: string) => ({
        payload: {
            email,
            password,
        },
    }),
)

Selectors

For easier access, we will set up a total of 3 selectors for different parts of our state to be used in the frontend. We know selectLogin already. Additionally, we now have a flag for isSubmitting during the api request and the loginMessage, to update the UI accordingly and provide useful feedback for user interactions.

export const selectLogin = (state: RootState): boolean => state.user.login
export const selectIsSubmitting = (state: RootState): boolean => state.user.loginState === 'loading'
export const selectLoginMessage = (state: RootState): string | undefined => state.user.message

Middleware

In our middleware, we will listen to login and signup attempts, call our mock code and dispatch additional actions according to the results from the mock api.

As you see, we simply dispatch the setLogout action to pass on the new loginState and error message.

export const userMiddleware: Middleware = ({ dispatch }) => next => action => {
    next(action)

    if (attemptLogin.match(action)) {
        const { email, password } = action.payload

        login(email, password)
            .then(() => dispatch(setLogin(email, false)))
            .catch(err => dispatch(setLogout('denied', err.message)))
    }

    if (attemptSignUp.match(action)) {
        const { email, password } = action.payload

        createAccount(email, password)
            .then(() => dispatch(setLogin(email, true)))
            .catch(err => dispatch(setLogout('denied', err.message)))
    }
}

Reducer

The last bit is our Reducer code. This is where it all comes together. When the user attempts to log in, we update state and message to reflect this in the UI and then wait for updates via setLogin and setLogout.

const userReducer = createReducer(initialState, builder => {
    builder
        .addCase(attemptLogin, state => ({
            ...state,
            loginState: 'loading',
            message: 'loading',
        }))
        .addCase(setLogin, (state, action) => {
            const { email, newUser } = action.payload
            return {
                login: true,
                email,
                newUser,
            }
        })
        .addCase(setLogout, (state, action) => {
            const { loginState = 'loggedOut', message } = action.payload
            return {
                login: false,
                loginState,
                message,
            }
        })
})

A proper login form

On our SignIn and SignUp screens, we can now replace the mock button with a propper login form from a separate component file.

// File: src/components/demo/UserForm.tsx
import React, { useState } from 'react'
import { Button, StyleSheet, Text, TextInput, View } from 'react-native'
import { useReduxSelector } from '../../redux'
import { selectIsSubmitting, selectLoginMessage } from '../../redux/ducks/user'

type UserFormProps = {
    submitHandler: (email: string, password: string) => void
    label: string
}

const UserForm = ({ submitHandler, label }: UserFormProps): React.ReactElement => {
    const [email, setEmail] = useState('hans@wurst.de')
    const [password, setPassword] = useState('wiener')

    const isLoading = useReduxSelector(selectIsSubmitting)
    const loginMessage = useReduxSelector(selectLoginMessage)

    return (
        <View>
            <TextInput
                style={styles.input}
                onChangeText={text => setEmail(text)}
                value={email}
                keyboardType="email-address"
            />
            <TextInput
                style={styles.input}
                onChangeText={text => setPassword(text)}
                value={password}
                secureTextEntry
            />
            <Button
                title={label}
                disabled={isLoading}
                onPress={() => submitHandler(email, password)}
            />
            {loginMessage && <Text>{loginMessage}</Text>}
        </View>
    )
}

const styles = StyleSheet.create({
    container: {
        flex: 1,
        alignItems: 'center',
        justifyContent: 'center',
    },
    input: {
        height: 40,
        width: 300,
        borderColor: 'gray',
        borderWidth: 1,
        marginTop: 20,
    },
})

export default UserForm

Aaaaand we're done.

Next time we will look at nested navigations and other navigation patterns. Until then I hope you enjoyed this lesson and were able to abstract this pattern for your own projects.

SERIES: React Native (Step by Step) - Strongly-Typed Navigation with React Navigation 5.x and Typescript

Konrad Abe — Sun, 18 Apr 2021 19:33:32 +0000

Last time we added redux to our app. This time we will integrate React Navigation (v5.x at the time of writing), a very flexible and robust navigation/routing solution and the primary recommendation made by the expo team too.

With the v5 update, React Navigation got a major overhaul. They split up their old repository into several smaller ones and introduced many breaking changes but the current version is in a very good state right now and worth the effort.

In our example today, I will show you how to set up your basic routes and how to implement navigation actions and conditional navigation and in the follow-up to this part, we will look at a very common authentification flow, nested sub navigations and a few tricks to make your life easier.

As always, you can find a link to the finished code on GitHub at the end of the article.

Preparations

If you want to code along and did not follow the previous episodes, simply go to my GitHub Repository here and grab the code from the v0.2 tag.

We will start by installing the core library for react native via npm.

npm install @react-navigation/native

There is a list of packages we're going to need but as we are using the expo managed workflow, we can simply use the expo install command to install compatible versions of these libraries.

react-native-gesture-handler
react-native-reanimated
react-native-screens
react-native-safe-area-context
@react-native-community/masked-view

A small note, we won't be using all of these in this part of the series but I'm including them here because they are part of my regular setup anyway.

expo install react-native-gesture-handler react-native-reanimated react-native-screens react-native-safe-area-context @react-native-community/masked-view

We will need 4 simple placeholder screens to showcase the navigation. You can simply create them under src/screens and add their names in a tag in a basic react component. That way we won't get any compiler warnings for missing module exports and can reference the correct files when we set up our routing.

Defining The Basic Routes

React Navigations can be nested and combined but for our main navigation, the one that will make whole page transitions, we are going to start with a simple stack.

Install the stack library in addition to the ones we grabbed earlier because we're going with a navigation stack for now.

expo install @react-navigation/stack

A stack navigation works like a stack of card and comes with basic page transition animations based on your current device/os. Each time you navigate in a stack, you put a new "card" on top of the stack and when you navigate back, you remove the top-most card again. Last in, first out. Using a stack navigation will give you an app-like feel of responsiveness right out of the box.

Create a new file called routes.ts under src/routing and import the createStackNavigator function from react-navigation/stack. We will also export an enum of all the screens we register in our routing setup, which will allow us to refer to screens via MainRoutes.Home instead of using a regular string, something that will be helpful when working with typescript and will also be picked up by your IDEs autocompletion.

// File: src/routing/routes.ts
import { createStackNavigator } from '@react-navigation/stack'

export enum MainRoutes {
    Splash = 'Splash',
    Loading = 'Loading',
    Home = 'Home',
    Settings = 'Settings',
}

export type MainStackParamList = {
    [MainRoutes.Splash]: undefined
    [MainRoutes.Loading]: undefined
    [MainRoutes.Home]: { update: boolean } | undefined // just an example, "update" will later be used for version checks
    [MainRoutes.Settings]: undefined
}

export const MainStack = createStackNavigator<MainStackParamList>()

The second thing you see in this file is the type for all our screens. React navigation allows us to call screens with params. Defining them as undefined means, that this route does not expect any params on load while the "Home" route can be called with an optional boolean flag for the "update" attribute.

We then export our MainStack created with the createStackNavigator and our list of possible stack params.

A common example for route params would be something like an userID for a profile page or a sorting param in a list.

// Example - don't add this to our project
type ExampleStackParamList = {
  Home: undefined
  Profile: { userId: string }
  Feed: { sort: 'latest' | 'top' } | undefined
}

Building Our Main Navigation

To build our MainNavigation component we are using a NavigationContainer from react navigation and map our Screen components with the navigation routes we defined. After importing our MainStack from './routes' we can use its Navigator and Screen components to organise our different screens/pages.

I'm using the attribute headerMode="none" on the Navigator to disable the default topBar header that comes out of the box with the component.

// File: src/routing/MainNavigation.tsx 
import React from 'react'
import { NavigationContainer } from '@react-navigation/native'

import { MainStack, MainRoutes } from './routes'

import SplashScreen from '../screens/SplashScreen'
import AppLoadingScreen from '../screens/AppLoadingScreen'
import HomeScreen from '../screens/HomeScreen'
import SettingsScreen from '../screens/SettingsScreen'

const MainNavigation = (): React.ReactElement => {

    return (
        <NavigationContainer>
            <MainStack.Navigator headerMode="none">
                <MainStack.Screen name={MainRoutes.Splash} component={SplashScreen} />
                <MainStack.Screen name={MainRoutes.Loading} component={AppLoadingScreen} />
                <MainStack.Screen name={MainRoutes.Home} component={HomeScreen} />
                <MainStack.Screen name={MainRoutes.Settings} component={SettingsScreen} />
            </MainStack.Navigator>
        </NavigationContainer>
    )
}
export default MainNavigation

Implementing The Main Navigation

To use the new main navigation we just have to put it in our root project file, the App.tsx and throw out all content other than the redux provider.

// File: App.tsx
import { StatusBar } from 'expo-status-bar'
import React from 'react'
import { Provider } from 'react-redux'
import store from './src/redux'
import MainNavigation from './src/routing/MainNavigation'

export default function App(): React.ReactElement {
    return (
        <Provider store={store}>
            <StatusBar hidden />
            <MainNavigation />
        </Provider>
    )
}

When you restart your app now, everything should work again for a limited amount of "work". What we have right now is one big stack of screens. The user will start on the first screen in the stack, our splash screen, and has no means to navigate around.

About Navigation Patterns

One of the most common navigation patterns is the so-called AuthFlow, where a different stack is used for the authentication of the user and the navigation of the actual app. I will show you a more complex AuthFlow in my next article but to show you the basics, we will mock a login with redux and use it to explain the principle.

While we are at it, go to your src/redux folder and rename the "demo/" folder to "ducks/", something I missed in my last article.

The idea behind ducks is to NOT have an actions.ts, middleware.ts and reducer.ts file for all your parts of the redux store but instead have one file with all parts of one slice combined.

If you want to know more about ducks and redux/reducks, I'll leave you with an article about the basic idea behind using ducks and the ducks proposal by Erik Rasmussen.

Create a new duck for our mock user and login code. For now, we will only include a setLogin action for toggling the login flag and a selector to access the stored value via a custom useState hook. Don't forget to register the new reducer in our rootReducer.ts and we are good to go.

// File: src/redux/ducks/user.ts
/* eslint-disable no-param-reassign */
import { createAction, createReducer } from '@reduxjs/toolkit'
import { RootState } from '../index'

type UserState = {
    login: boolean
}

const initialState: UserState = {
    login: false,
}

export const setLogin = createAction('[USER] Set Login', (isLoggedIn: boolean) => ({
    payload: {
        isLoggedIn,
    },
}))

export const selectLogin = (state: RootState): boolean => state.user.login

const userReducer = createReducer(initialState, builder => {
    builder.addCase(setLogin, (state, action) => {
        state.login = action.payload.isLoggedIn
    })
})

export default userReducer

With the new selectLogin selector, we can now adjust our navigation stack a bit.

// File: src/routing/MainNavigation.tsx
import React from 'react'
import { NavigationContainer } from '@react-navigation/native'

import { MainStack, MainRoutes } from './routes'
/* new */ import { useReduxSelector } from '../redux'
/* new */ import { selectLogin } from '../redux/ducks/user'

import SplashScreen from '../screens/SplashScreen'
import AppLoadingScreen from '../screens/AppLoadingScreen'
import HomeScreen from '../screens/HomeScreen'
import SettingsScreen from '../screens/SettingsScreen'

const MainNavigation = (): React.ReactElement => {
    const isLoggedIn = useReduxSelector(selectLogin)

    return (
        <NavigationContainer>
            <MainStack.Navigator headerMode="none">
                {isLoggedIn ? (
                    <>
                        <MainStack.Screen name={MainRoutes.Loading} component={AppLoadingScreen} />
                        <MainStack.Screen name={MainRoutes.Home} component={HomeScreen} />
                        <MainStack.Screen name={MainRoutes.Settings} component={SettingsScreen} />
                    </>
                ) : (
                    <MainStack.Screen name={MainRoutes.Splash} component={SplashScreen} />
                )}
            </MainStack.Navigator>
        </NavigationContainer>
    )
}
export default MainNavigation

As you can see, we are now using the selectLogin selector to set our isLoggedIn flag and use it in our Navigator to load a different stack of screens based on the login state. If the user is on the "Splash" screen and triggers a login, he will automatically be switched over to the first screen in the other stack and end up on the "Loading" screen.

Moving On

In our SplashScreen.tsx file we can now set up a simple clickable screen that triggers the fake login.

// File: src/screens/SplashScreen.tsx
import React from 'react'
import { Text, View, TouchableWithoutFeedback, StyleSheet } from 'react-native'
import { useReduxDispatch } from '../redux'
import { setLogin } from '../redux/ducks/user'

const SplashScreen = (): React.ReactElement => {
    const dispatch = useReduxDispatch()

    const handleClick = (): void => {
        dispatch(setLogin(true))
    }

    return (
        <TouchableWithoutFeedback onPress={() => handleClick()}>
            <View style={styles.page}>
                <View style={styles.titleBox}>
                    <Text>ALL BITS EQUAL</Text>
                    <Text>presents</Text>
                    <Text>The Expo Starter Kit</Text>
                </View>
                <View style={styles.contentBox}>
                    <Text>Touch Screen to start!</Text>
                </View>
                <View style={styles.footer}>
                    <Text>written by Konrad Abe</Text>
                </View>
            </View>
        </TouchableWithoutFeedback>
    )
}

const styles = StyleSheet.create({
    page: {
        flex: 1,
        backgroundColor: '#fff',
        alignItems: 'center',
        justifyContent: 'center',
    },
    titleBox: {
        width: '100%',
        height: '50%',
        alignItems: 'center',
        justifyContent: 'center',
    },
    contentBox: {
        width: '100%',
        height: '45%',
        alignItems: 'center',
        justifyContent: 'center',
    },
    footer: {
        width: '100%',
        height: '10%',
        paddingRight: '3%',
        alignItems: 'flex-end',
        justifyContent: 'center',
    },
})

export default SplashScreen

The important thing to note here is that we are basically NOT triggering a navigation event with this (we'll come to that in a moment) but switching to a separate navigation stack. For this reason, we don't need to access the navigation params of our Navigator at all.

As I said, you can read more about this AuthFlow navigation pattern in the next article. Moving on...

Navigating Our Routes

When using React Navigation within our app, all screens that are direct children of the navigator have access to the "navigation" object. Using this with strong typing can be a bit tricky because the type for the navigation prop takes 2 generics, the param list object we defined earlier, and the name of the current route.

We don't want to rebuild this in every screen component that needs to access the navigation prop so I will add a types.ts file to the routing/ directory and import both the MainRoutes enum and the MainStackParamList that holds all our defined routes and their annotations.

// File: src/routing/types.ts
import { StackNavigationProp } from '@react-navigation/stack'
import { MainRoutes, MainStackParamList } from './routes'

export type MainNavigationProp<
    RouteName extends keyof MainStackParamList = MainRoutes
> = StackNavigationProp<MainStackParamList, RouteName>

We can now use this to annotate the navigation prop in our components. For our first screen after the login/stack switch, we will define a small delay before navigating to the home screen and display a simple "loading..." text.

This would usually be the place to check the version of your app against your servers, load user data and stuff like that. This process would then replace the setTimeout() we used here to fake a real app flow.

// File: src/screens/AppLoadingScreen.tsx
import React, { useEffect } from 'react'
import { Text, View, StyleSheet } from 'react-native'
import { MainNavigationProp } from '../routing/types'
import { MainRoutes } from '../routing/routes'

type AppLoadingScreenProps = {
    navigation: MainNavigationProp<MainRoutes.Loading>
}

const AppLoadingScreen = ({ navigation }: AppLoadingScreenProps): React.ReactElement => {
    useEffect(() => {
        setTimeout(() => {
            navigation.navigate(MainRoutes.Home)
        }, 1500)
    }, [navigation])

    return (
        <View style={styles.page}>
            <Text>loading...</Text>
        </View>
    )
}

const styles = StyleSheet.create({
    page: {
        flex: 1,
        backgroundColor: '#fff',
        alignItems: 'center',
        justifyContent: 'center',
    },
})

export default AppLoadingScreen

On our home screen, we will place a regular navigation button as well as a logout button dispatching a redux action to check if we get redirected to the auth stack when we set the login state to false again.

// File: src/screens/HomeScreen.tsx
import React from 'react'
import { Text, View, StyleSheet, Button } from 'react-native'
import { MainNavigationProp } from '../routing/types'
import { MainRoutes } from '../routing/routes'
import { useReduxDispatch } from '../redux'
import { setLogin } from '../redux/ducks/user'

type HomeScreenProps = {
    navigation: MainNavigationProp<MainRoutes.Home>
}
const HomeScreen = ({ navigation }: HomeScreenProps): React.ReactElement => {
    const dispatch = useReduxDispatch()
    const logoutHandler = () => dispatch(setLogin(false))

    return (
        <View style={styles.page}>
            <Text>HOME</Text>
            <Button title="logout" onPress={() => logoutHandler()} />
            <Button title="settings" onPress={() => navigation.navigate(MainRoutes.Settings)} />
        </View>
    )
}

const styles = StyleSheet.create({
    page: {
        flex: 1,
        backgroundColor: '#fff',
        alignItems: 'center',
        justifyContent: 'center',
    },
})

export default HomeScreen

To wrap up this episode, the last thing I want to show you today is the goBack() function. On our SettingsScreen we will put a button that does not navigate to a specific screen but to the last screen on the stack prior to the SettingsScreen. This means that you could link to the settings from any page in the stack and when clicking the backlink, you would be taken back to the page you were before.

// File: src/screens/SettingsScreen.tsx
import React from 'react'
import { Text, View, StyleSheet, Button } from 'react-native'
import { MainNavigationProp } from '../routing/types'
import { MainRoutes } from '../routing/routes'

type SettingsScreenProps = {
    navigation: MainNavigationProp<MainRoutes.Settings>
}

const SettingsScreen = ({ navigation }: SettingsScreenProps): React.ReactElement => (
    <View style={styles.page}>
        <Text>SETTINGS</Text>
        <Button title="back" onPress={() => navigation.goBack()} />
    </View>
)

const styles = StyleSheet.create({
    page: {
        flex: 1,
        backgroundColor: '#fff',
        alignItems: 'center',
        justifyContent: 'center',
    },
})

export default SettingsScreen

Wrapping Up

Today we learned how to annotate both our routes and our navigation prop.

As promised, here is the finished code on GitHub at the v3 release tag.

Next time I will show you two more complex scenarios with react navigation including the useNavigation custom hook and how to trigger navigation events from redux middleware. We will build a better AuthFlow that mimics a real application (including some extra features), we will validate navigation events before they occur and I will show you how to implement a nested navigation to control parts of a page or modal window without moving away from the current screen.

Rapid Prototyping, test often and fail early

Konrad Abe — Sat, 10 Apr 2021 22:58:15 +0000

As the creator of games, it is often hard to see or judge if the core idea is fun to play and within the realms of reasonable complexity. Prototypes and playtests will allow you to dodge bullets and maybe even pull the plug before it is too late.

Why Prototypes and 'Proofs of Concept' (PoCs) matter?

I'm coming from a Web Dev background. When you are building a regular website and you are familiar with your tools and languages, this is a pretty straight forward task. Having spent my recent years working on a complex Product Information Management (PIM) Web App, I've seen both ends of the spectrum of complexity and over the years, simple PoCs and Prototypes have become a staple tool in my workflow.

A Proof of Concept with new toys

When deciding on the choice of your web/app stack, it can provide valuable insights and experience to start a small project with the new framework or library, learn the ropes, talk to the community, see the common questions on StackOverflow and run into a few dead ends yourself.

We recently evaluated VueJS for our company projects and no amount of reading reviews and documentation would have given us the same level of insight as simply building a small mini web app with it and finding out how to solve the same problems we know with a new tool.

Most libraries and frameworks have easy to follow tutorials that will allow you to create something simple in no time and expand on what you have learned by adding more features after finishing the original lessons.

Not sure if two things work well together? Maybe don't try to shoehorn both into an existing codebase at the same time and instead build a fresh app/tool/program using both on a clean slate. A good example of this? Try setting up a React Project using typescript exclusively with redux, routing, local storage and full linting for your workflow.

Bonus Points: By using clean slate projects, it is easy to share some or all of your code online when asking for help from the community, which is a big factor and really appreciated by those kind souls taking on your beginner questions. No need to delete sensitive client data or in-house code.

A Proof of Concept with new challenges

When a customer comes to you (or your project lead) and requires a new solution for something you have not done before, it might be a good idea to hack together a rough mini prototype as part of the feasibility check.

Create a dirty mockup in any tool you are familiar with and develop the known user journey required for the new feature. This will allow you to identify UX/UI issues early on, give you something to share between devs, art/concept and customer to develop the final solution and prevent communication issues when description and understanding of the tasks at hand do not match.

A/B Testing

Whether you are working on new features or making changes to existing ones, it is often a good approach to make a small test and run it by your peers or a small test group to see how it performs. In regards to user experience, performance and conversion rates are often not logical on a surface level unless you fully understand all the emotional and psychological elements of your change and their effect on the user.

Running a quick A/B test with a PoC of your change before you develop the final assets, start translations and run your full QA can save you a lot of time and in some cases even money.

How does this translate into game development?

I will go out on a limb here and claim that a large percentage of people trying to build games do not have the slightest grasp on what makes something fun.

This is an issue I've seen a lot with both young novel authors and inexperienced game developers. Their ideas, concepts and characters sound great in their heads but when presenting them to critics or consumers, those ideas often fall short for a variety of reasons.

Oftentimes, the problem is that taking two or more ideas from different games and simply glueing them together might not be as fun as it seems on paper. Even a full-on copy of a successful game can fall short for a variety of reasons.

What is fun

I'm not sure if you are familiar with the book "A Theory Of Fun" by Raph Koster. If not and you are planning to make entertaining games, I can only recommend you to buy it and read it asap... Fun is a very interesting term because it will be interpreted differently by almost everyone you talk to.

Take me for example. I'm a person that has fun writing spreadsheets with costs, values and production time to maximise the output of a little fantasy store on my smartphone. The game itself might be fun but the metagame of finding more efficient ways to do something is fun for me all the more while the next person might see this as tedious and cumbersome or downright boring.

When you are trying to find a "fun" concept for a game, you should test this basic concept as soon as possible and in the most simple way possible.

Keep It Simple

If you are working on a card game (analogue or digital), make a paper prototype. If it is a board game, guess what, make a paper prototype. Got a digital tool that allows you to easily define cards and rules and such, use that.

Try to find the most basic, simple and easy to use tool and level of abstraction and see if it works. For games that don't depend on 3d graphics, platformer action or anything like that to work, try to completely ignore the design part and make a text-based version. This works well for most RPGs, strategy games, idle games, sim/management games and their likes.

If you don't plan to make your prototype public in any way and plan to use it solely for internal tests but your game absolutely needs graphics/assets, it's even ok in my book to use copyrighted or unlicensed material/assets from other games. Just make sure to never use any of those in any form in a published piece of work, be it commercial, open-source or freeware.

I happen to know that some board game developers used other existing board games during their early planning and testing phase and simply stuck small slips of paper to the miniatures with labels or values.

Play, Watch and Ask

Ask your friends and family to play with you or, even better, for you. Explain the rules and let them play. Listen to their questions, make notes of their reactions, roadblocks and issues with the "gameplay" try to interrupt them as little as possible until they are done. Wait for them to finish or until you got enough notes and ask them what was fun about it and what was not.

Having other people play your game comes with two benefits. Feedback, as previously mentioned, and also the bonus of feeling good about your work when they sincerely enjoyed it. This can be really rewarding as a developer/game maker.

What should you test?

Again, there are two things to keep in mind:
1) Only because you like the concept or maybe even enjoy the execution, this does not need to hold true for a larger audience.
2) A feature that is fun in one game can fall short in another. Context, context, context.

While a crafting system might be really engaging in one game, it might not be solemnly the crafting itself but the setting, the environment, how it is tied into the game, the lore and the interaction with other players or other aspects of the game itself.

When you try a variation of an existing concept or, even better, a very rare and completely original idea, it might take you countless iterations until you "feel" the idea and enjoy it. I can only recommend to you to search the web for some Game Post Mortem articles or videos and watch closely.

Changing and finding the right theme can make a feature "click" with the player. Switching the setting, premise or end goal (even if it is only affecting the visuals, wording etc. and not touching any of the game mechanics) can make or break a game.

Is the basic idea fun?

Find out who your target audience is and try to see if you can match the core mechanic of your game with their expectations. Create a basic game loop (not in the "engine" sense, more like the flow of the game's core mechanic) and see if it is enjoyable to perform.

Is the basic idea fun repeatedly?

Can you replay (or continue to play) the game again and again without losing interest in it? Are there settings that change over time and are players well enough aware of these or does it feel repetitive for them? Are you using randomisation or map generation?

Does the fun evolve vertically?

Does your idea allow for any type of "power scaling" and linear progression? Is it fun to be more powerful and progress along the vertical line? Is it maybe even the main goal?

Does the fun evolve horizontally?

Does your idea allow for spreading/branching concepts that increase complexity while bringing new engagement into play?

What if early prototyping is hard to do

There are many cases where your concept is based on a working game with a twist. Building it from the ground up might not be feasible for an early prototype.

In some of those cases, modding is a good way to bridge this gap. Take an existing game with similar gameplay that is moddable and try to add your twist/idea/feature to it. Keep in mind that if you publish the mod, your own brainchild is out there and issues with copyright and ownership can follow (always a hot topic with the big game publishers) but as long as you only use it in-house... no harm's done, eh?

What if early prototyping is impossible

There will be some cases where the core concept is so special and complex, that you simply can't mock it. I'm sorry but there isn't much I could say to you that would help you out here. You will probably have to rely on market research, polls, interviews with potential players and such to gauge the value and viability of your idea before you start development.

Just keep in mind that prototypes and Proofs of Concept are not limited to early testing. You should definitely use them later on as well when the core mechanics of your project are already implemented. In many cases, small variations can make a large difference in the feel of the game and respectively its user experience.

Wrapping Up

With the full spectrum of possible game types, genres and all it would be impossible to touch on all aspects you might run into but I hope you got the global idea here.

The mantra of "fail fast, fail often" might be a terribly overused and beaten-to-death buzzword term but my advice is to "try fast and try often". You will most likely fail with some of those attempts but the earlier you find out via a prototype that an idea does not work, the faster you can pull the plug or make critical changes and change your path.

If a prototype fails or reaches the end of its life cycle, salvage it, take notes of your learning and discard the rest.

Images:

Photo by Christopher Paul High on Unsplash
Photo by Alvaro Reyes on Unsplash
Photo by Jaciel Melnik on Unsplash
Photo by Nika Benedictova on Unsplash

Freelancing & Pet Projects - Living The Dream Or Building Castles In The Sky

Konrad Abe — Wed, 31 Mar 2021 20:27:19 +0000

Working in their 9-5 jobs, many people dream about being independent, breaking out of the daily grind or simply being their own boss. While this is not impossible, it is also incredibly hard and depending on good timing and luck of all sorts.

Don't quit your day job just now. Wait a bit, listen to what I have to say and make an educated decision for your own path.

DISCLAIMER: This is an opinionated article and might be disillusioning for some, inspiring for others and there will always be a few to whom this will not apply at all. Use a bit of common sense and a good measure of realism when making life-changing decisions.

It's not uncommon to see videos and articles boasting about "5 simple steps to freelance success", "The one thing I changed to start making profits" or "How quitting my job and starting a small company was the best thing I ever did".

Keep in mind that we usually only hear about the success stories of the few victorious entrepreneurs that made it and then there are those stories about successful failure like the guy that bankrupted 3 companies before he made it big and founded a multi-million dollars company.

You don't see many port mortems about people that did not make it as a freelancer.

Most entrepreneurs and many freelancers fail and are never heard about. Right now, with covid around, this might be an even harsher truth and bitter pill to swallow. Don't expect to have an idea, act on it and then stonks... Big profit. Plan ahead, make backup plans and play the long game.

No matter whether you want to work freelance as an individual, build the next big indie game or plan to start a new venture or small company... if you run out of time or money, there's no helping it. You need a roof over your head, food in your belly and before you realise it, you are forced back into your office job (cubicle, if you live in the US) and slave away again.

Here are a few things to keep in mind when you plan to or dream about taking your first steps towards independence.

Step 1: Have Money, lots of it

As I previously said, if you run out of money before you are successful or at least able to cut even, you are out of luck. Having enough money can be achieved in multiple ways. If you are really lucky, you have a benefactor or partner with a steady and well-paying job that is willing to help you work on your dream. If that's not the case, start putting money on the side. No matter whether you start working freelance or found a small startup, you need to be able to buffer for a few months or even years until things start rolling. Otherwise, all you did will be for nought.

If you start a small business or open a store/shop/cafe, you might even need a sponsor or investor unless you happen to be sitting on a hoard of money from a lucky inheritance.

Don't Burn Bridges

This directly ties in with the last point, do not quit your job on a whim and go all-in unless you are absolutely sure about what you are doing. Keep on working and start small. Make sure you have a realistic idea of what's ahead of you before you take the leap.

Don't wait too long to do "something"

There is no reason to not start doing something. Get your research done, start making plans, talk to peers and mentors about your plans and do some networking to meet like-minded people. There are things you need to do in advance to raise your chances of success. Use your time of secured and stable income and regular working hours to prepare for your exit. You should already have some hands-on experience when you finally go for it.

Don't procrastinate

I've written about this in a previous article but this point is worth repeating. You probably have to work more to be successful, at least for a while. Starting your freelance career comes with lots of additional hurdles including taxes, insurances, home office stuff, legal stuff, customer acquisition, customer relations/management... The same goes for many other occupations. In most cases what we see online is only the tip of the iceberg of what those successful people do.

You might have to accept a severe cut in your playtime or time spent reading, eating out, having fun and slacking off. I'm not saying to stop doing all of that immediately and I am a firm believer in "recharging creative energy" but when working for yourself, things need to be done and most likely there won't be anyone nagging you about your last report or missing insurance documents for HR.

Start forming habits early

Whatever it is you want to do, you need to turn it into a habit. Start recording a video once a week and post it on a predefined weekday. Write an article a week with at least X words and have it proofread and corrected by Monday. Write at least one new prototype or refactor one open-source project's task or something like that.

Find a day (or series of days, depending on the task) AND JUST DO IT!

Change your rhythm, change your morning routine, create a new one and stick to it. The earlier you start getting rid of some old and possibly bad habits and take on new ones, the easier it will be for you to stick to those tasks at hand.

Keep realistic goals

Don't go too big, too soon. This advice might not apply for freelance work but if you try to post new work too often per week, you will most likely burn out soon and retroactively reduce your schedule again. If you plan on building an indie game title, keep it small and manageable. Maybe plan to release a v1 and have stuff if your backlog for a v2 or even release a follow-up title with the additional ideas and concepts.

Be ready to advertise

"Build it and they will come" hardly ever works.

Depending on the nature of your goals, you might need to build up mailing lists, cross-post articles on different blogs, join podcasts as a guest, do features with other influences or streamers or comic artists... This section alone could fill a whole article but I think you get the picture.

Expect trolls and harsh criticism

People will hate (or misunderstand) what you do and they will go to lengths to tell you about it. If you are female, things can get really ugly in some cases. The internet is a terrible place to put a piece of your heart, be prepared and brace yourself for the worst! It will not always be like this but it can and more often than not, it is completely outside of your own control.

Some communities are more welcoming than others (I've had some great experiences myself in the realms of comic and novel artists, IT in general and also hobbyist/indie game dev circles) but platforms like Twitch, YouTube and some subreddit can be unforgiving and unfair down to as much as bigotry and toxic masculinity all over the place. Be prepared for that is all I'm saying.

A few examples

Here are a few very basic examples with no claims of being complete. These are fueled by my own experiences and ongoing discussions with peers and friends both online and offline.

The Streamer/Youtuber

Do start streaming early, get used to it
Do record your streams and make short "best of" videos for youtube
Do think about your style and focus
Do decide if you want to show your face/identity or not
Don't go all out and buy the most expensive equipment (camera, mic, lights) on day 1
Don't expect people to start watching your stream with zero advertising

The Game Developer

Do start coding
Do write lots of prototypes
Do plan based on your limitations and skills
Do find a game type/genre that matches your skills and resources
Do think about your core gameplay
Do find out if it is fun if you strip it down to the very basic concept
Don't start working on that one big game idea that will revolutionise the industry
Don't ask around for people that might want to join you to build your game
Don't buy expensive software upfront without even testing the waters and learning the ropes
Don't start building a community, discord server, social media campaign and all that on day 1

The Freelance Developer

Do reduce your office hours before you quit cold turkey
Do start looking for customers and build up some resume projects
Do invest some time into your showcase, website etc.
Do keep in mind that customer acquisition and customer communications are time consuming and nerve-wracking
Do check out Clients from Hell
Do maintain open-source code from your own projects and contributions to others' if you can
Don't expect that this one well-paying company you currently work for as a regular freelancer will be a stable source of income
Don't continuously work for one client exclusively, some countries have laws against that (bogus self-employment)

Wrapping up

I have been working both as a freelancer and employed as a web developer for many years. Right after starting out in 2008 I started working freelance and had the incredible luck that a company I did a traineeship for agreed to send me all the stuff that went over their own capacities. That way I had a good financial backup that gave me ample time to find other customers and start making a living of it.

I switched over to full-time employment when we needed more financial stability (my wife was working freelance as well, which was a bit scary at times), and right now I reduced my office hours to have more time for my family and my writing career.

I did NOT switch over to game development to build that one game I've been dreaming of for 2 decades but decided to focus on writing articles about making games and websites and apps in general while keeping the indie game dev part as a small side hustle and pet project. I might, in the future but I'm not there yet.

Writing these articles and talking with peers online and at conferences gave me so much to think about, to learn, to research and to try out. Now I hope this article will help you too.

Juggling Home Office, Childcare and your own projects without losing your mind

Konrad Abe — Mon, 22 Mar 2021 22:12:07 +0000

Covid-19 is here to stay (for now at least) and with it, many of us in IT have changed their Modus Operandi. Companies have acknowledged that working from home 5 days a week is indeed a valid option in most cases and teams have found new ways to work together in these trying times.

But add in some children plus closed daycare/kindergarten and suddenly things are different again.

Setting the stage

Even before Covid-19 hit it off in early 2020, I had decided to spend more time with my child than my coworkers. Starting in January 2020, I was working 20h a week, spending 2 days at work and 1 day in my home office. That way I got to spend more time with our newborn daughter and my wife was able to get back to her own career part-time as well.

All was going well. My team and I had made arrangements for the most important meetings, we had dedicated communication channels for urgent and less important updates and ToDos and when we started sending her to kindergarten later that year (at that time, Germany was still mostly on top of the whole virus issue), I was able to get back to regular working hours (by now doing 100% home office work).

Little did we know what the year had in mind for us.

Get your priorities right

When the first lockdown started, we had to make some tough decisions but for me, one thing was clear. While I did not plan to neglect my projects or leave my colleagues hanging, I was going to stick to my original plan: Be a father first and an employee second. I started talking with my team lead and our management early during our pregnancy and had found an agreeable compromise of flexible working hours that fit both my team and work as well as my family life.

Make sure you talk with everyone as soon as possible and listen to their concerns and requests. There might be mandatory team meetings or steps of your team's workflow/release cycle that might require you to conform to certain time slots. List those, arrange your schedule around them and make sure to tell everyone on the team about it.

DON'T stop communicating

Nothing is worse than not being able to reach a colleague when you don't know about his current progress, status and workload.

Keep everyone in the loop without imposing on them. You might be the one thrilled about your current life changes but maybe not everyone on the team. Find a good balance of small talk outside of meetings, crucial information in regular (daily?) meetings and regular updates.

For example, I usually give a small heads-up during our daily meeting in the morning about changes to my availability, upcoming doctor appointments and such. I try to keep this short and concise and only inform about the most relevant things.

If you use a ticket system such as Jira, Clickup or the like, update your tickets every evening. Make sure you have a maximum of 2 tickets "in work", write short updates as comments in each ticket about possible blockers, dependencies and necessary feedback or your own progress. Don't make your project/team lead ask for updates that should be available for them in case you are indisposed when they need it.

Commit your code often. Don't hoard your changes in local branches, push daily at least and make sure your feature branch is up to date with the latest changes on develop (if you are using the "regular" git workflow with main/develop/feature branches)

Keep a reliable communication channel open during working hours. I am usually not a big fan of work-related chat apps on my smartphone but right now I am available for my colleagues via Slack and everyone knows that I might not read all chats at all times and certainly not emails but direct messages are a well-established way to get feedback from me as soon as I am available.

DO stop the meeting madness

While it is crucial to keep good communication up, don't waste your time in meetings that should have been an email. This is something you won't be able to do alone so get your team lead's support here (as well as your scrum master's, if you have one) and try to get to a point where:

every meeting has an agenda
people don't small talk or stray off-topic during the meeting
meetings end with actionable results and responsibilities
only the most relevant people attend the meeting

Most of these points were something I was striving for long before I cut my hours but now, more than ever, is this mandatory to stay productive.

As I said before, try to get support from your team lead/scrum master and stay respectful. It won't help your situation if you cut off people in meetings because you feel like they are wasting your time but try to communicate your concerns openly and honestly.

DON'T slack off

Set yourself definite goals and stick to them. Don't narrow this down to work-related tasks for your day job. For example, I try to find the time to work on my freelance career and post one article per week (preferably on a Monday but realistically anywhere during the week is fine right now), so I start planning a topic, make notes and keep a backlog of possible things to write about so that I can pick what fits my available time and creative mood.

During the day, I usually only have a few hours at my PC while our daughter sleeps so I don't plan with those. While I take care of our daughter, I only do the most important tasks like planning and code reviews on my smartphone while she is occupied playing by herself and when something important comes up, I try to arrange a switch with my wife to take care of it, delegate tasks and make notes of what still needs to be done. In the evening, after putting our daughter to bed, I sit down and work on the most pressing issues at hand such as planning tasks for my team, giving feedback on open issues and working on code that is needed by others to continue with their tasks.

Do your chores asap! They build up and then they will eat up all of your weekends. Seriously... With 2 working parents, things can pile up fast. It took us a while to find a healthy rhythm for running the washing machine and dishwasher, picking up random toys, planning the next shopping trip, ordering stuff and making sure to prepare the next meal.

Right now our daughter is 17 months old and I started including here in my daily chores routine. Things will take longer but she has fun helping and being part of the process. She can sit in and dig through a pile of clothes while I prepare the next load of our washing machine. She loves taking things out of the dishwasher and handing them to me (I always remove all dangerous objects first, before I "unleash" her) and when I put up the wet clothing she eagerly gets the next piece or two for me from the basket with only a few pieces falling to the floor.

Delegate where possible

This next piece of advice might sound like a first world problem but think about hiring someone to help you cleaning and staying on top of things at home when money isn't too tight. I wouldn't have thought about this option in the past but we are now considering it. I would pay some money to have more time with my family not spent cleaning and

DON'T stop playing

I personally think one of the biggest mistakes many people make, when trying to be more successful, is getting rid of all regular playtime on their quest for maximum productivity... THIS DOES NOT WORK FOR EVERYONE!

For me, crossing 3 things from my daily todo list at 8 am after 30 minutes of sport, a healthy breakfast drink and a cold water shower might feel good once every few weeks and will make me feel accomplished and productive but this is by far nothing I could keep on doing day in and out.

I am not one of those overly productive super achievers. I can not and I do not want to get rid of all play in my pursuit of success and I'll make the bold claim that neither are you.

During the week I try to find a healthy mix of late-night working and playing games with my wife. For us, nothing beats a round of Hearthstone, Divinity and sometimes we even dig out our old Diablo Accounts and start a new season character. If the little one falls asleep a bit earlier, maybe even pick out a good movie and make some popcorn.

I need this. We both need it. It's good for clearing the head and recharging your creative energy. We don't play games that grab you by the neck and drag you along for weeks on end. We stopped binging Netflix series and say no to MMO's, no to subscription games and stuff where you are forced to play with strangers on the internet, form bonds, meet expectations. Don't enter a new commitment.

DO stay healthy

Eat healthily! Sleep healthy! Yeah, right... I know, I know... You've got a kid keeping you up at night every now and then. Then, at least sleep as much as possible.

Try to form habits that help you manage your days. Make it a habit to eat a healthy breakfast in the morning. Make it a habit to go to bed early enough to be at least partly rested and relaxed the next day, even when you had to feed and put the child back to sleep in the middle of the night. Work out.

I started working out while spending time with our daughter. I'm going for longer walks with the dogs and her stroller and while we are in her playroom upstairs to create some space for my wife to get her work done undisturbed, I started incorporating exercises in our playtime. It's amazing what you can do with a toddler that she will enjoy and still serves as an exercise for you.

Did anyone say Cross Fit? Guess I'm now one of those people, only with more drool (not mine) and fewer tires and sledgehammers. Also, the weight gradually increases as you get stronger. How convenient is that?

Split up the mental workload

This is one thing I definitely need to work on, reducing the mental workload that my wife has.

If you don't know the term, mental workload describes the constant task of keeping track of appointments, deadlines, events, groceries, cooking (planning in advance), bills, chores and more.

In many relationships, the mental workload is still resting heavily on the shoulders of wives and with kids at home, this often increases.

To help you and your partner to stay on good terms while locked in at home with work and kids and everything else, try to share the mental workload. It would have been a good idea before Covid-19 started but now more than ever, this can make or break your relationship with your partner and second hand with your kid(s) as well.

Find a good balance of who is responsible for what. I'm not good at tracking tasks in my head, something my wife seems to have managed all too well. For way too long I took for granted that those things are taken care of. I'm now working with a special shared calendar that I manage and developed a small 5 stack system for all the paperwork that comes with taxes, bills, contracts, applications, kindergarten, vaccinations and all that.

Whatever you do, it will be tough but worth it

All in all, you can find ways to make it work, even with your kids at home most all of the time and both of you working. Just make sure to never direct any anger or frustration about issues at work towards your children. This might sound like a no brainer but one is way too quick with venting or showing frustration about things not going well and children take these things in, even if you did not mean to direct it at them.

Make sure you create a warm, loving and healthy place for them to grow up in.

Gambits - Behavioural Decision Patterns For A Game Development AI

Konrad Abe — Mon, 15 Mar 2021 13:58:38 +0000

Starting today, I'm kicking off my new series of articles about game development topics. These will mostly be theoretical and talk about concepts and techniques but will at times also include ideas and solutions, depending on the topic at hands such as different ways to go about pathfinding, grids and perspectives in games.

Our first topic will be Gambits.

What Is A Gambit?

A gambit (from ancient Italian gambetto, meaning "to trip") is a chess opening in which a player sacrifices material with the aim of achieving a subsequent positional advantage.
Source: Wikipedia

Photo by GR Stocks on Unsplash

Historically, gambits are risky moves in a strategical play. The term is nowadays used in many contexts, including strategical situations outside of games, even in politics.

But why are we talking about gambit today? Thanks to one game in particular, gambits have become a popular term in
game development circles as well.

How Are Gambits Used In Game Design?

When Square Enix released Final Fantasy XII for the PlayStation 2 in 2006, reception of one of the design choices created a lot of talk. To enable the player to play with multiple characters in an MMO style open-world RPG with (pausable) real-time combat, the developers added the gambit system. Using said gambits, the player could set several commands and triggers and the game would check those for a match and execute the respective action.

Overview of a magic focused unit's gambits (Final Fantasy XII)

While part of the player base disliked the subjective loss of direct control, the system enabled players to create their own mini AI with simple and easy to understand building blocks.

Subsequentially, gambit systems have been used and talked about in the context of RPGs and there are some other notable examples of games allowing the player to control the AI of his own heroes.

Alternatives to Gambits

A common alternative to this gambit system and Something around for a lot longer would be decision modelling trees. These allow a more detailed, flexible and expandable control about the AI's decision processes but at the cost of the player being able to add his own rules with simple tools.

Of course, there are also real AI solutions that implement real learning algorithms and mimic human decision models even more closely but that's a different topic altogether.

Pro And Con Of Using Gambits

As mentioned above, the main Con or constraint of a system alike the gambits of Final Fantasy XII is its limiting nature. It is hard to implement command chains (do A, then B and then follow up with C) and you also need to limit the number of rules or gambits. On top of that, you need to teach your players how to use that system.

On the Pro side, we have the player interaction, which can create a positive effect of ownership because the player is the creator of his own rulesets and it can turn into an interesting metagame to find the right solution for a special situation or set of constraints and keeps the player engaged into solving new challenges.

For me personally, the fact that it is a very simple style of programming available to people with no experience in the field is another great boon here.

Decisions need to be made by hand... (Final Fantasy Tactics)

Anatomy Of A Gambit

The Target

Any action needs a target. The target can be yourself, an ally, a foe or maybe even the target of one of your allies.

Depending on your game design, this could also include differentiations such as mercenaries, neutral bystanders, certain objects or even target areas.

The Condition

Depending on your chosen target, you can add a condition for each gambit. Say, for example, you want to use a healing spell on yourself but only when your own hit points are below 50%. In that case, you would pick target self (or any ally if you want to include your whole team/party)

Examples

- Use: Attack
- On: closest enemy
- Use: healing spell
- On: ally (hp<=50%)
- Use: potion
- On: self (hp<=25%)
- Use: fire spell
- On: enemy status=weak to fire

Choosing the right items to use in a gambit (Final Fantasy XII)

Bonus: Trigger Conditions

I'm currently working on my own implementation of a gambit-like system and I've added an extra component, trigger conditions.

Basically, this is nothing else than a second unit/character/enemy to check for a condition to activate the gambit. Say for example you want to use a certain skill only when your mana/energy is above a certain level but target it on an enemy. In that case, you would do the following.

Use: expensive spell
On: target hp>=3000
When: self mp=>75%

Or you want to use a defensive ability when the enemy is enraged

Use: defensive stance
On: self
When: enemy status=enraged

Gambits In The Wild

The basic idea of gambits for player-controlled units is easy to implement but in a game using gambits, you can take it a step further and use it to model enemy Ai the same way, maybe with a few options not available to the player, to keep it interesting.

You can also use it in more complex games if you implement logic to handle pathfinding, the cost of certain terrains and other stuff like more complex actions. Go wild and be creative. If it fits your game concept, there are lots of interesting combinations you can achieve with them.

Gambits In My Own Projects

I will soon publish another article on my prototype using gambits. It won't be a full and playable game but an interactive game demo showing how the decision modelling with gambits works and allowing the "player" to experiment with different combinations in different scenarios.

So stay tuned and be sure to follow me and future articles. The prototype should be ready in a week or two.

Typescript and Test Driven Design don't fix everything, but...

Konrad Abe — Tue, 09 Mar 2021 13:14:51 +0000

But they make you think differently about the issues at hand.

For a long time, I thought that I did not have the time to write tests or that I'll simply do it later. It took me a few years to see how my thinking was completely backwards.

Let me quickly draw you a picture...

I'm a slow adapter

When react made its big splash alongside angular, I had a look at it but decided to stick with vanilla Javascript for the time being. When redux added a convenient solution for managing state and storing data, I was still using local storage and other patterns for a while.

When I started using react and redux in tandem, I had a look at typescript and decided to stick with the jsx variant for the time being. And don't even get me started on test-driven design...

What has changed?

For once, it wasn't that I was totally against those libraries, languages and workflows. I just don't jump the wagon on the first mention of a new thing on the developers' horizon, an attitude that kept me save from framework fatigue during the recent years.

Another reason is reality. If you are not a student, working for one of the few big IT giants or do your own thing, it is very likely for you to be locked in with some legacy code base, monolithic projects or tight deadlines.

Starting to work with a new framework/library or even language (typescript being a superset of javascript) Might not even be possible for most of us unless we do our own projects after work or are in the luxury position to get some leeway from our bosses.

I was already comfortable with react and redux by the time I started working at Das Büro am Draht, a few years ago. We sat together as a team and later in one of our workgroups and discussed the merits of working with typescript. Management gave us time to both learn and practice working with typescript and agreed on slower deliveries while we started climbing the learning curve until we were comfortable using it for all new development.

Test-driven design is a different story altogether though. While typescript comes with a certain amount of overhead, it becomes manageable and doesn't impact development times after a while. Test-driven development on the other hand... First of all, it doesn't make sense to use it everywhere. Do you plan to test if your component actually renders that div? Do you repeat the "red until green" Cycle for every component you are going to write? Well, I don't.

Additionally TDD means you need to spend more time while developing new stuff for the first time, hacking away and writing tests later allows you to ship faster and... Probably never write those tests in the end, unless your project ever switches over from active development into a maintenance/support mode.

TDD is hard to sell to management or your project manager and in most cases, it's even harder to get the client to agree unless you simply don't tell him and do it silently.

But today is different. I'm here today to tell you that TDD has its uses and pairs very well with typescript too. Why? It makes you think.

I can't show you our customers' business logic here but I'll try to explain it on a private project I do after hours for fun. In the following examples, I'm setting up the basics to a pseudo-AI that determines the results of a decision-making model based on configurable sets of parameters. It's basically a way to tell your heroes in a game how to pick targets and choose skills and spells based on predefined rules.

Usually, I would sit down and simply write the basics and hack away from there. If it works, keep it and expand it. If not, discard and try again. I've previously written about rapid prototyping and I'm still a big fan but this time I have a very clear idea about what I want to end up with so I can sit down and properly plan ahead using the previously mentioned tools.

My Process

I'm dividing my process into the following steps:

paper prototype planning
Empty functions
Typescript types
Tests (red)
Actual code
Green test check

This process makes me think about what type of data I'm handling, how to process and transform it and this is also a good way to structure your code before you write it. When preparing coding sessions, tutorials and seminars, this has come in handy as well.

If you have no clue what I'm talking about when I mention gambits or unit behaviour rules, think of characters in a strategy / role playing game that need to decide what to do next based on rules. The enemy might attack the player or use a healing spell when his hitpoints are below a certain level... that sort of thing.

What do we need for this example? I spell it out and write it down. This is a step I often do on paper or my smartphone way before I write the first line of code.

1) Paper Prototype

the player can create and adjust gambits that will control his units
gambits will be checked one after another until a condition is met
- get all targets matching the selection
- filter them down based on the condition
- see if the skill/attack is available
- return the action and target or check the next gambit

Our next step is to put this general idea into functions we could implement.

2) Empty Functions

/* processBehaviourChain()
 * - check all gambits in the behaviour chain for a match
 */

/* getAvailableTargets()
 * - get all targets matching the target type
 */

/* getMatchingTargets()
 * - return only targets matching the selection criteria
 */

/* isActionAvailable()
 * - check if the action is possible 
 * - (enough resources, material and so on)
 */

/* compareTargetHP()
 * - check if the current target matches the hitpoint condition
 */

/* compareTargetStatus()
 * - check if the current target matches the status condition
 */

As you can see, from reading this rough sketch alone you already get a pretty good idea of what will happen when and why. All functions have fitting names (some may change during implementation anyway) and you also get a good idea about what these functions will need to do their job.

3) Typescript Types

// We need units to compare and some stats and status to check. 
// I will skill the imported 'Effect' and 'RaceName' types here
type UnitBase = {
    hp: {
        current: number;
        max: number;
    };
    status: Effect[];
};

export type Unit = UnitBase & {
    name: string;
    id: string;
    race: RaceName;
};


// possible selections for targeets and derived types
const targets = [
    "self",
    "currentAlly",
    "currentEnemy",
    "leader",
    "leaderCurrentEnemy",
    "leaderCurrentAlly"
] as const
type Target = typeof targets[number];

const conditionTargets = [
    ...targets,
    "ally",
    "enemy",
] as const
type ConditionTarget = typeof conditionTargets[number];

/*
 * skipped a few more types here including a selection of 
 * valid absolute numbers and percentage values as well as 
 * our previously used Effect type
 */

// comparison operators for numerical values like hitpoints
const comparisonOperators = ["lt", "lte", "eq", "gte", "gt"] as const
type ComparisonOperator = typeof comparisonOperators[number];

type PercentageComparison = [ComparisonOperator, Percentage];
type AbsoluteComparison = [ComparisonOperator, AbsoluteValue];
type StatusComparison = [boolean, Effect];

// last thing to do here is a simple mapping of valid combinations
type TargetComparison =
    | ["hp", AbsoluteComparison]
    | ["hp%", PercentageComparison]
    | ["mp", AbsoluteComparison]
    | ["mp%", PercentageComparison]
    | ["status", StatusComparison]

type TriggerCondition = [ConditionTarget, TargetComparison];

type Gambit = {
  target: ConditionTarget;
  comparison: TargetComparison;
  action: Spell | Skill | Item;
}

Let's put those types to good use by creating our functions.

const processBehaviourChain = (units: Unit[], gambits: Gambit[]): void => {
  // check all gambits in the behaviour chain for a match
}

const getAvailableTargets =(units: Unit[], targetType:ConditionTarget): Unit[] | null => {
  // get all targets matching the target type
} 

const getMatchingTarget = (targets: Unit[], comparison: TargetComparison): Unit | null => {
  // return only targets matching the selection criteria
}

const isActionAvailable = (actor: Unit, action: Action): boolean => {
  // check if the action is possible 
  // (enough resources, material and so on)
} 

const compareTargetHP = (target: Unit, comparison: TargetComparison): boolean => {
  // check if the current target matches the hitpoint condition
} 

const compareTargetStatus = (target: Unit, comparison: TargetComparison): boolean => {
  // check if the current target matches the status condition
}

As you can see, we have already built a lot of confidence in our code just by defining types. What do we want from the tests now? If we produce an output that does not match our types, the typescript compiler will already catch this. We don't write tests to reach a certain level of code coverage, we will write tests to check in those nooks and corners where typescript can't look.

If we were to implement tests for this demo project, we would check for validation issues with user input, application of filters (like getAvailableTargets()) and complexity levels inside our functions including whether or not certain subfunctions have been called and make sure that edge cases and such are caught correctly.

Conclusion

My initial point was that using Typescript and Test Driven Design makes you think differently about the issues at hand. They force you to think ahead and make a mental model before you start coding.

Is this slower?

Yes, to some extent it will be slower, even if we finish the whole project and can start to reap the benefits of our preparation. Unless you are very well accustomed to both TDD and TS, you will need a bit of extra time to plan, figure out types and write tests, but... !

If during the development of your project, you realise that you made a planning mistake and need to adjust some parts, allow for an extra case, different data or something, you will soon reap the fruits of your labour. One of the key strengths of Typescript compilers is to point out all the spots you might otherwise miss during refactoring or redesigning parts of your code and having those edge cases tested will make sure you don't miss any of those either, even with the new data structure.

Moving on

I will go into more detail about the actual testing of this pet project soon and you can then follow my progress commit by commit.

I've been writing Typescript projects with a lot more confidence and adding tests before code to some of my projects made me think an plan better. I hope I can share this experience with you in the future.

Scrum / Agile is not broken but we need to stop pretending

Konrad Abe — Mon, 01 Mar 2021 22:58:02 +0000

Scrum might be a foot-gun so stop trying to make it fit. There, I've said it.

Don't get me wrong, I love working on agile projects. I've done it in the past, I'm doing it for some of my projects and I will do it in the future. But right now, I am not working agile. Grab your favourite beverage (appropriate for your current time and location), sit back and listen to a story of horrors, pain and closure.

We will look at the Idea of Scrum, possible problems, ways to fix them and times when you should not force yourself into the corsage of agile workflows.

The Idea of Scrum

The idea of Scrum and working agile in software development has been around for a while and currently, it seems to be the craze in almost every company you encounter. There's scrum masters, daily meetings, reviews and retrospectives and people left and right are either cheering or crying about it.

Project managers love the idea of Scrum. All tasks broken down to stories you can put a t-shirt size on, the team has a velocity of 42 and you know exactly what you can achieve in the next 2 weeks.

The team loves the idea of Scrum. They understand what everyone on the team is doing. You get to know each other, sit together to talk and play planning poker for new tasks and never before was there so much confidence in everyone to get things done.

The customers love the idea of Scrum. They get small bite-sized chunks of his project delivered and can follow the progress while making changes where needed. They can get their money sack stories prioritised and everything is fine... but is it?

How come that everyone loves the idea of Scrum but in the end, in so many cases, so many people are unhappy with the process, the amount of micromanagement and meetings?

Possible Problems

There are several reasons, why your agile workflow is not working. Some of those can be solved, others not. It takes some experience and patience to tell them apart and turn the idea of Scrum into a reality.

Failed Sprints and Estimates

Problem

You and your team were eager to start working agile. You sit together, plan your tasks, work out realistic estimates and plan your first sprints. A few weeks go by and your team sits together in their second retrospective, talking - again - about a failed sprint where you did not meet your target. Hopefully, everyone works together to find solutions and changes are agreed on. Your start the next sprint and again, you fail. Obviously, this isn't working as intended.

Possible Reason

When starting to work agile as a team, it is very common to not meat your own goals. Maybe you finished the first sprint early and took in too many tasks/points for the next sprint. Maybe your team still needs more experience in making estimates, breaking down tasks and spotting issues before they occur.

Finding your own "velocity" in an agile team takes some time. I usually say, wait a few months before you start making big changes. Do talk about issues openly, even with the customer present, when they are part of the agile workflow. Communicate transparently and try to improve your estimates, plannings and sprints in very small iterations. If you have not been working agile for years, chances are, you and your team still need to grow into it and if the team size changes, you might even have to start over again.

Too much overhead and meetings

Problem

You have your daily meeting, a backlog refinement, a sprint planning, sprint review, sprint retrospective, feature kickoffs, lunch break and maybe, if you stay late, you even manage to get some programming done.

Possible Reason

This is something I can talk about at length as I recently started working part-time, taking care of my daughter for the rest of the week. Working only 24 hours a week, I can finally fully understand what many of my female colleagues were talking about in the past, telling people to send more emails and do fewer meetings.

Working in an agile team comes with many meetings but... they are there for a reason and you can make them work. There is one key point here I need to stress. Discipline!

Everyone in the team needs to adhere to meeting discipline! If you are a few minutes early to a daily meeting, it's ok to goof around for a bit until everyone is there and the meeting starts but a daily meeting should be as short as possible. Never start late, don't stand around waiting for the late-comers. It is often called "Stand-Up" for a reason, don't sit comfortably and talk lengthly. Keep it short and precise. "I did this task yesterday and will start this today. Bob, I need that chart by 12 for our customer call and I still need access to database X, this is a roadblock for me." And cut to the next person.

Ideally, you are all done after at tops 15 minutes and can start into another productive day. The same goes for other meetings. Keep them as short as possible, set a fixed time and when you are not done when the alarm goes off, finish next week. If the team can't do it on their own, hopefully, your Scrum Master can make up for that with moderation and people skills.

With the regular sprint meetings and a 3-week iteration, you will usually spend around 8 hours total in regular sprint meetings. Make sure these don't drag on and waste everyone's time.

The shoe does not fit

Problem

Your client is not working as agile as your company does or is at a remote location and can not join you for one reason or another, which means that they can not fill the role of the Project Owner. Your Project Manager now puts on the hat of the "Proxy-PO" and you move on. As your company is small and does not have a person to spare, you decide on one team member to take over the role of the Scrum Master in meetings and you hurriedly send them to a few seminars on the topic.

Possible Solution

The hard truth here is, there is no real clean-cut solution. Unless your team has loads of experience working agile and is confident about their workflows and everything, you need these roles! You really do.

The Project Owner is the stakeholder. The PO tells you what he wants or needs and in which order and priority. The PO decides which stories need to be added to a sprint and makes the tough call to drop another story or two to adjust to the team's velocity. The moment that your Project Manager is also the Project Owner, interest start to mix and this can lead to issues with setting the right priorities to make the customer happy and we all want a happy customer, don't we?

The Scrum Master is your bulwark and your problem solver. The scrum master needs to help everyone in the team to shine and get their work done. This can be a full-time job in many cases. An SM needs to make sure the team can do their work, has all the information and access to all systems and resources. Spotting possible roadblocks, dead ends, bottlenecks and other issues that might lead a sprint to fail early are some of the key tasks of a capable scrum master.

They defend the team against corporate and project lead interests that might clash with their tasks on the project. Some times the SM even protects the team from themselves and serves as a lightning rod for problems that arise during a retrospective meeting, gathering all available intel and help the team to identify solutions and actionable ideas to move forward.

You need those two, believe me. Be nice to your Scrum Master, he is your best friend at work.

The Customer demands "fixed price" / "fixed time" offers

Problem

You and your company are trying their best to be as agile and productive as possible but the client is not agile and due to corporate or "political" reasons does not agree to work agile and pay agile.

There is no solution for this... sorry

This is one of the moments where you need to face a sad truth, you will not be able to work fully agile. It just won't work.

Don't force yourself

There are situations where working agile will just not work. Maybe these reasons are outside of your circle of control. Trying to force the mantle of Scrum on a team or a company can lead to disgruntled and unhappy employees, bad project management and even completely destroy a team's productivity and happiness.

But there is still hope. There is still a way that is working quite well for me right now, gets things done, helps us meet deadlines and keep everyone happy. I like to call it "Agile'ish".

Take the best from working agile and apply it where possible.

Stay connected, Stay informed

Keep up regular short meetings to get everyone on track of current tasks. Plan tasks as a team. Get ideas and feedback from everyone and get everyone on the team involved. This does not only help people stay in touch and feel like they are part of the whole project, it creates a feeling of ownership.

This is our project, our code and our success.

Keep on shipping

Work iteratively and keep the main project running. Use the Git Workflow and keep features small. Write Proof of Concept features and build them up. Never let a branch get older than 2 weeks top before merging a working version back into the main trunk. The longer a feature exists in isolation, the more likely it is that you will run into major issues when you try to merge.

This is our project running on staging. Isn't that cool?!

Never stop improving

Get feedback from your peers about your work. Don't stop at code reviews (also never stop code reviews!!!) but ask for an honest and fair feedback. Create an environment of trust and honesty, where people can talk to their colleagues freely and with no fear or suspicion. Get together regularly in small groups and gather feedback on processes, refine them and commit to them.

This is the way we build our project. We all agreed on this.

Plan ahead and look back

Analyse and break down tasks into bite-sized chunks that you can understand and plan. Write down user stories that explain the task from the perspective of a real person using the software and then create tasks needed to perform to reach that goal. Look back on similar tasks and try to get a good feeling on the complexity and possible issues to put a number on those tasks.

This is what we need to do to finish our project. We have a plan.

Wrapping up

Maybe your company might not get the official "SCRUM Certified" label, maybe your customer doesn't want to work agile and maybe there are some things you just can't change but that is no reason not to try to be a better you tomorrow than you were yesterday.

Take from the Agile Idea what works for you and add it to your repertoire. See what works and what doesn't and keep iterating. Maybe don't tell your friends and business partners that your company is working agile, maybe stand proud and say:

WE ARE AGILE'ISH AND WE GET THINGS DONE!

Happy Coding, everyone!

React Bootstrapping — Deep Dive into Redux Messaging Patterns

Konrad Abe — Mon, 22 Feb 2021 20:39:34 +0000

Today we will dive a bit deeper into the way I work with redux and why I think that, despite recent developments of react hooks, redux still has its place in our infrastructure.

I've got multiple requests for more information about my redux setup after writing my last article so I decided to make a small deep dive into the topic this week and I will probably follow up with another one in the next article about routing with redux and typescript, should I get a similar response.

As always, you can find the GitHub Link to the finished code at the end of the article.

What is redux?

Redux is a predictable state container that uses the concept of actions and reducers to change data in a single source of truth, the redux store.

Wow... This sure sounds important but what does it actually mean? What is the state of a website or, for that matter, a store?

Redux store

The redux store is nothing more than an object containing our websites data and UI state, ideally in a normalised form. If, for example, a user navigates to the article listing page of our website and filters the listed articles by a topic, our state contains the following:

Navigation state: the current page/URL
Data state: the list of articles (response from an API call)
UI state: the current filter mask

Redux actions

Actions are messages of intent. An action does not change any data in our stored state. An action is nothing more than a message containing an identifier and a payload to be handled by a reducer.

If the user navigates to a page, we dispatch a navigation action and the navigation updates
If the page wants to load data from the website, it dispatches an API action
If the user selects a filter in the UI, an action is dispatched to update the filter for the currently displayed data

Redux reducer

Reducers handle all incoming actions and decide on applicable state changes. If a dispatched action has a matching reducer, the reducer will check the action's identifier (type), accept the data (payload) and make changes by creating a new state. "New" is important here, in redux we do not mutate the state. Every action creates a new state.

BONUS: Redux middleware

Redux also has an optional third layer called middleware. The middleware is sitting between actions and reducers, reads
every action passing through
and handles it based on the content.

This (optional) part is the most interesting in my opinion. I usually have zero logic inside my actions and as little as possible in my reducers. Actions are nothing but messages with an intent and reducers only handle the state change in a predictable way. They should be as clean as possible, returning the same output every time they receive the same input.

Another thing to keep in mind when you decide on whether or not to use middleware is that redux is synchronous. If you want asynchronous interactions (like API requests), the middleware is the right place to implement this. A few common examples of middleware are the following:

Filter

Filter middleware looks at incoming actions and makes decisions based on its own logic. You might, for example, want to throttle user actions that result in an API request or UI change. In that case, you can do so here, only letting an action through every n seconds.

Async API requests

API requests are another use case. Let's say the user loads a list of articles. The article action signals its intent to load data from an API as well as callbacks to execute on the success and failure of the request. The middleware will let the action pass through so that the message is following the correct flow and then dispatches a neutral API action with the payload of the original request.

The API action does not need to know about the source of the request (our articles page) and only cares for the requested data and URL. This way you only need to write and test the API logic once and it is fully reusable. Once the API request is resolved, the response is passed on to the success action (store articles) or error action (handle a failed request).

This might sound verbose and like a lot of actions are dispatched for a simple request of data from an API but it allows us to look at the state of our app and the flow of messages and see exactly what happened.

[ROUTER] Navigate
[ARTICLES] Request article List
[API] Request data
[API] Request success
[ARTICLES] Store articles

Splitter

If you take it one step further, you might want to update your UI based on the loading/pending request. In that case, you would set up the articles middleware to trigger the API request and update the UI accordingly.

The middleware would then "split" or dispatch multiple separate actions and the action/message flow could then look like this.

[ROUTER] Navigate
[ARTICLES] Request article List
[UI] Set page loading
[API] Request data
[API] Request success
[ARTICLES] Store articles
[UI] Set page idle

In some cases more is more

The official redux guidelines recommend a different pattern where you write one action and multiple reducers handle it accordingly but I recommend not to do so.

Don't get me wrong. I, too, prefer to write less code and chose to work with redux toolkit, exactly for this reason, but dispatching more actions and handling them separately, turning your application into a message-based system, has its benefits regarding scalability and readability, two qualities that can make a big difference in the future if your project.

If you follow the path described above, the separation of your project's different concerns is much clearer and is following well-established design patterns developed and described many years ago by people (links at the end of the article) with loads of hands-on project experience.

Demo Time

We have outlined where we want to go with our project so let's see what we need to get our article page working with redux.

Preparation

I've prepared a new project using create-react-app and a typescript template. I've also added some linting and an article component to showcase our store.

Right now, we are displaying a list of articles that is hardcoded. We want to move this to a mock-api server, which I've prepared, including the mocked server response for our articles.

You can check out the prepared project including the mock api server here to get started.

Additionally, we will work with a pattern called redux ducks. A duck is a single file containing all the actions, middleware and reducers needed to define and handle one slice of our stored data.

You can read more about the Redux ducks proposal to get a better idea of what our file/directory structure is based on.

Starting the development environment

In addition to starting the web project using npm start, we also need to start the mock server, which is a separate and simple express server. To do so, simply run npm run mock-server in a separate terminal tab. You could also chain both in a combined script in the package.json but I prefer them to run in separate tabs so that their logging is clean and separated in case of issues.

Redux articles duck

We will start by defining our imports and types. The Article type can be copied from our articles.tsx while the rest is new.

// File: src/redux/ducks/article.ts

/* eslint-disable no-param-reassign */
import { Middleware } from 'redux'
import { createAction, createReducer } from '@reduxjs/toolkit'
import { apiRequest } from './api'

export type Article = {
    title: string
    author: string
    date: number
    tags: string[]
    excerpt: string
    urls: {
        page: string
        url: string
    }[]
}

export type RequestStatus = 'idle' | 'pending'

type InitialState = {
    data: Article[] | null
    status: RequestStatus
}

For our actions, we need to be able to

request articles
store articles
set the status of the UI
handle a request error

// File: src/redux/ducks/article.ts

export const requestArticlesData = createAction(
    '[ARTICLE] request data'
)
export const setArticlesStatus = createAction(
    '[ARTICLE] set status',
    (status: RequestStatus) => ({ payload: { status } })
)
export const storeArticlesData = createAction(
    '[ARTICLE] store data',
    (data: Article[]) => ({ payload: { data } })
)
export const cancelArticlesRequest = createAction(
    '[ARTICLE] cancel failed request',
    (error: string) => ({ payload: { error } })
)

In our middleware, we will match all actions that match our requestArticleData action, to dispatch the UI update and send off the API requests via API actions. We tell the API the type and target of our request and what to do with the resulting success or error. This is the splitter pattern, we talked about earlier.

We also match for cancelArticleRequest actions because we want to both log the error (for now temporary to console) and update the UI to cancel the "pending" state.

// File: src/redux/ducks/article.ts

export const articleMiddleware: Middleware = ({ dispatch, getState }) => next => action => {
    next(action)

    if (requestArticlesData.match(action)) {
        const state = getState()
        if (!(state.article && state.article.status === 'pending')) {
            dispatch(apiRequest({
                url: '/articles',
                method: 'GET',
                onSuccess: data => storeArticlesData(data),
                onError: error => cancelArticlesRequest(error)
            }))
            dispatch(setArticlesStatus('pending'))
        }
    }

    if (cancelArticlesRequest.match(action)) {
        const { error } = action.payload
        console.log("Error while requesting articles: ", error) // eslint-disable-line no-console
        dispatch(setArticlesStatus('idle'))
    }
}

Our last bit here is the default export for our articleReducer. We only need to handle actions that either store the article data or simply update the UI state.

// File: src/redux/ducks/article.ts

const articleReducer = createReducer(initialState, (builder) => {
    builder
        .addCase(setArticlesStatus, (state, action) => {
            const { status } = action.payload
            state.status = status
        })
        .addCase(storeArticlesData, (state, action) => {
            const { data } = action.payload
            state.data = data
            state.status = 'idle'
        })
})

export default articleReducer

Redux API duck

Our API code is not trivial and I'd advise you to simply copy it for now if you feel like you still need a better understanding of how redux with typescript works but I'll try to outline the basics.

First of all, we need to define our API endpoint (API_HOST). Our example assumes that there is only one and it's currently set to our mock API server.

Then we need to define all different types of requests ("GET", "POST", "PUT", "DELETE") and how an API payload is structured including onSuccess and onError actions.

// File: src/redux/ducks/api.ts

import { Middleware, Action } from 'redux'
import { createAction } from '@reduxjs/toolkit'

const API_HOST = 'http://localhost:3031'

export type SuccessAction<T> = (data: T) => Action
export type ErrorAction = (message: string) => Action

export type ApiBaseRequest = {
    url: string
    headers?: Record<string, string>
}

export type ApiGetRequest = ApiBaseRequest & {
    method: 'GET'
}

export type ApiPostRequest = ApiBaseRequest & {
    method: 'POST'
    data: Record<string, unknown>
}

export type ApiPutRequest = ApiBaseRequest & {
    method: 'PUT'
    data: Record<string, unknown>
}

export type ApiDeleteRequest = ApiBaseRequest & {
    method: 'DELETE'
}

export type ApiRequest = ApiGetRequest | ApiPostRequest | ApiPutRequest | ApiDeleteRequest

export type ApiRequestPayload<T = never> = ApiRequest & {
    onSuccess: SuccessAction<T>
    onError: ErrorAction
}

Our actions are relatively simple, now that we have defined all the typings above. We have our apiRequest as well as the apiSuccess and apiError actions.

// File: src/redux/ducks/api.ts

export const apiRequest = createAction(
    "[API] Request",
    (api: ApiRequestPayload<any>) => ({ // eslint-disable-line @typescript-eslint/no-explicit-any
        payload: { ...api },
    })
)

export const apiSuccess = createAction(
    "[API] Success",
    (onSuccess: SuccessAction<unknown>, data: unknown) => ({
        payload: { onSuccess, data },
    })
)

export const apiError = createAction(
    "[API] Error",
    (onError: ErrorAction, message: string) => ({
        payload: { onError, message },
    })
)

The final part here is our middleware because the API does not have a state in our store. Our middleware is responsible for resolving the request via fetch and handling the success and error cases with the respective actions, dispatched with the original callbacks from our article action.

// File: src/redux/ducks/api.ts

export const apiMiddleware: Middleware = ({ dispatch }) => next => action => {
    next(action)

    if (apiRequest.match(action)) {
        const {
            url,
            method,
            headers,
            onSuccess,
            onError,
        }: ApiRequestPayload<any> = action.payload // eslint-disable-line @typescript-eslint/no-explicit-any


        fetch(`${API_HOST}${url}`, {
            method,
            headers
        })
            .then(response => response.json())
            .then(reponseData => dispatch(apiSuccess(onSuccess, reponseData)))
            .catch(error => { dispatch(apiError(onError, error.message))
            })
        return
    }

    if (apiSuccess.match(action)) {
        const { onSuccess, data } = action.payload
        dispatch(onSuccess(data))
    }

    if (apiError.match(action)) {
        const { onError, message } = action.payload
        dispatch(onError(message))
    }
}

Redux - wiring everything up

We now need to register our reducers with the rootReducer and add a rootMiddleware to register our new apiMiddleware and articlesMiddleware.

// File: src/redux/rootReducer.ts

import { combineReducers } from '@reduxjs/toolkit'
import articleReducer from './ducks/articles'

const rootReducer = combineReducers({
    articles: articleReducer,
})

export default rootReducer

// File: src/redux/rootMiddleware.ts

import { apiMiddleware } from './ducks/api'
import { articlesMiddleware } from './ducks/articles'

export default [
    apiMiddleware,
    articlesMiddleware,
]

To add our middleware to the store, we can append it to the already existing default middleware that redux toolkit brings to the table. We also need to make an exception to our serializableCheck middleware (from redux toolkit) because our onSuccess and onError actions are not serializable.

React Redux, hook things up with the new store

We already have our redux provider component as a wrapper around our app (part of the prepared setup I made) but right now, our Articles.tsx component does not know how to access the article state.

In the past, it was common to use the connect() function from react-redux to allow components to access the state but with the advent of react hooks, this changed. We already have a typed useReduxDispatch and useReduxSelector hook (also part of the prepared setup) and could use them directly in our Articles component but I personally prefer to keep them separate in a .hooks.ts file for each component.

We will create a new articles.hooks.ts file next to our articles.tsx component file and add our redux interaction there to keep our Articles component as clean as possible.

// File: src/components/pages/articles.hooks.ts

import { useEffect } from 'react'
import { requestArticlesData, Article } from '../../redux/ducks/articles'
import { useReduxDispatch, useReduxSelector } from '../../redux'


export const useArticlesData = (): Article[] | null => {
    const data = useReduxSelector(state => {
        return state.articles.data || null
    })
    const dispatch = useReduxDispatch()

    useEffect(() => {
        if (!data) {
            dispatch(requestArticlesData())
        }
    }, [dispatch, data])

    return data
}

With this in place, we can clean up our Articles.tsx and remove everything by replacing all the state logic with our new hook.

// File: src/components/pages/articles.tsx

import React from 'react'
import { useArticlesData } from './articles.hooks'

const Articles = (): React.ReactElement => {
    const data = useArticlesData()

    return (
        // nothing changed here so I skipped this part
    )
}

export default Articles

Wrapping up

With all said and done, we've successfully hooked up our website with a mock API using a clean and scalable message pattern in redux, allowing for a readable and easy to understand message flow.

Link to the finished code/tag v0.1.1 on GitHub

There are two minor changes I did not show in the article above. For one I had to adjust my linting to allow for imports using './articles.hooks' as the linter thought .hooks was the file ending... we can't have that.

"import/extensions": [
      "error",
      "never",
      {
        "style": "always",
        "hooks": "always" // this is new
      }
    ],

The other thing I did change was adding a key attribute to my list of articles because react always needs a key attribute when rendering lists of elements.

<li key={`article_${date}`}>

Links and Recommendations

Nir Kaufmann has a great presentation on Advanced Redux Patterns on YouTube, and while he does some things differently, you will be able to see the same patterns emerge.

Additionally, I can really recommend this old book because many of the ideas and concepts are still relevant today.

Enterprise Integration Patterns

Outlook

Next time we will look at routing and page navigation in detail before we move on to applying layout and styling our app with styled-components and themes.

Build A Bot (DiscordJS) - Better Logging And A Persistent Bot Config

Konrad Abe — Mon, 15 Feb 2021 13:01:57 +0000

Last time we left off, we had turned our simple bot into a bot factory, allowing us to spawn multiple bots with different configs. Those configs though were still pretty simple and not persistent. The user could not make any changes unless he made them directly to the config files.

Today we will spend a little bit of time on a prettier logger and then allow our bot to read and write his own config file on the server.

As always, the link to the finished code in GitHub is at the end of the article.

Credits: Today's session will include code influenced and partly taken from the Liora Bot Project. Feel free to look at their code for more inspiration.

Better logging

To start today's session, we will implement a prettier solution for our console logs using Winston for the logging and chalk for the pretty colours.

You know the drill, grab what we need from npm and then let's get busy.

npm i -S winston chalk

Winston is working with log levels and colours so let's start by setting up some sensible defaults. Right now we will mostly work with error, warn and info but later on, those other levels will be used too.

// File: src/index.js

// add this at the top
const winston = require('winston')
const chalk = require('chalk')

// define log levels
const logLevels = {
    error: 0,
    warn: 1,
    info: 2,
    modules: 3,
    modwarn: 4,
    modinfo: 5,
    debug: 6,
}

// define log colours
winston.addColors({
    error: 'red',
    warn: 'yellow',
    info: 'green',
    modules: 'cyan',
    modwarn: 'yellow',
    modinfo: 'green',
    debug: 'blue',
})

Then we create a new logger instance with the basic setup and formating. Within the printf function, we can format our desired logout format. We want a timestamp here along with the log level and of course the logged message.

// File: src/index.js

// add the configured new logger using winston.createLogger()
const logger = winston.createLogger({
    levels: logLevels,
    transports: [new winston.transports.Console({ colorize: true, timestamp: true })],
    format: winston.format.combine(
        winston.format.colorize(),
        winston.format.padLevels({ levels: logLevels }),
        winston.format.timestamp(),
        winston.format.printf(info => `${info.timestamp} ${info.level}:${info.message}`),
    ),
    level: 'debug',
})

What's left to do now is to wire it up with our bot object, finally getting rid of that eslint-disable...

... and apply it in the places where we used the old and too simple logger and add our desired log levels and use chalk to paint the message where we see fit.

When you are done, your console logging should now look like this. If you want to see my choice of colours, check out this commit.

One thing that we can now get rid of is putting the tag everywhere by hand. We can let Winston handle that for us. Change the line where we assigned the winston.createLogger() result and turn it into a fat arrow function that passes in the tag and returns the logger. This way we can include the tag in our printf output via ${tag}.

// File: src/index.js
const logger = tag =>
    winston.createLogger({
        levels: logLevels,
        transports: [new winston.transports.Console({ colorize: true, timestamp: true })],
        format: winston.format.combine(
            winston.format.colorize(),
            winston.format.padLevels({ levels: logLevels }),
            winston.format.timestamp(),
            winston.format.printf(info => `${info.timestamp} ${info.level}: ${tag}${info.message}`),
        ),
        level: 'debug',
    })

Now we need to add the tag (including a sensible default) to our log assignment and we're done.

// File: src/index.js
// Define the bot
    const bot = {
        client: new discord.Client(),
        log: logger(initialConfig.tag || `[Bot ${initialConfig.index}]`),
        commands: new discord.Collection(),
    }

The difference in the visual output is minimal but in our code, we just removed a lot of redundancy.

Before we move on to the config, we still need to clean up a bit. There are still useless tags scattered throughout our code.

Read & Write Configs

Some of the tools we're going to use for our config are prebaked in Node but in addition to those, we will need a way to work with json files, a way to create directories and to open files.

npm i -S jsonfile mkdirp opn

Let's start by adding our new tools to the imports and defining a useful small sanitise function to radically clean up user input. We'll use this later to create directories for the bots' config files and we don't want any funny characters in those directory names.

// File: src/index.js
const os = require('os')     // nodeJS
const path = require('path') // nodeJS
const fs = require('fs')     // nodeJS
const opn = require('opn')
const mkdirp = require('mkdirp')
const jsonfile = require('jsonfile')


const sanitise = str => str.replace(/[^a-z0-9_-]/gi, '')

As we are going to implement proper configs now, let's put some work in here and define a more detailed config schema. We can replace our old configSchema with this.

I'm using this schema to define what type of data the config accepts. This way we can run a basic check later to make sure every attribute resembles our requirements and we can include defaults in case the user has not set an attribute. Anything not in this list or of a wrong type will be discarded from the user input or old copies of the bot's config. This way we can make sure that the current config is always compatible.

One advice, don't put your token into the configSchema by hand. Include it in the initialConfig on bot start, as we had set it up last time. You would not want to hard code your bot's token (or upload it to a public repository in any case!) as it better sits in the non-versioned .env file or environment config of your hosted project.

// File: src/index.js

// Config
const configSchema = {
    discordToken: { type: 'string', default: 'HERE BE THE TOKEN' },
    owner: { type: 'string', default: '' },
    name: { type: 'string', default: 'BotAnon' },
    defaultGame: { type: 'string', default: '$help for help' },
    prefix: { type: 'string', default: '$' },
    commandAliases: { type: 'object', default: {} },
    defaultColors: {
        type: 'object',
        default: {
            neutral: { type: 'string', default: '#287db4' },
            error: { type: 'string', default: '#c63737' },
            warning: { type: 'string', default: '#ff7100' },
            success: { type: 'string', default: '#41b95f' },
        },
    },
    settings: { type: 'object', default: {} },
}

You should also add 2 lines to the rules in out .eslintrc file because we will need them soon to not get bugged by the linter about stuff that is working as intended / we want it to be.

// File: .eslintrc
    "no-param-reassign": ["error", { "props": false }],
    "valid-typeof": 0

1) Setting the config directory

We will need a way to keep track of config file paths to a certain directory. We simply store those in our bot object.

// File: src/index.js

    // Set the config directory to use
    bot.setConfigDirectory = function setConfigDirectory(configDir) {
        this.configDir = configDir
        this.configFile = path.join(configDir, 'config.json')
    }

2) Run it once initially

Here we are using the sanitise function we defined earlier to take the bot name and use it to create a directory for each bot. If you run the script on your own PC during test and development, the config files will be written to your home/user directory instead of the server's respective directory. Simply check for files starting with .discord- followed by your bot's name.

// File: src/index.js
    // Set default config directory
    bot.setConfigDirectory(
        path.join(os.homedir(), `.discord-${sanitise(initialConfig.name)}-bot`)
    )

3) Open generated config files for proofreading

Furthermore, I want to be able to open the files our script has created on the first run so that the user can check if his values have been merged correctly.

For this we will use something node provides us with, opn and if one of the bots had his config generated for the first time, we will open the generated file exit the process. On the next run of our script, all bots will connect regularly.

// File: src/index.js

    // Open the config file in a text editor
    bot.openConfigFile = function openConfigFile() {
        bot.log.info('Opening config file in a text editor...')
        opn(this.configFile)
            .then(() => {
                bot.log.info('Exiting.')
                process.exit(0)
            })
            .catch(err => {
                this.log.error('Error opening config file.')
                throw err
            })
    }

4) Check the configSchema

We also need a function to validate the user-supplied config and merge it with our schema to generate the new bot config. We'll go through our schema step by step, compare the existence and type of the respective attribute in the bot config and either delete or overwrite it depending on our checks. For objects, it will call itself recursively layer by layer.

// File: src/index.js

    // Recursively iterate over the config to check types and reset properties to default if they are the wrong type
    bot.configIterator = function configIterator(startPoint, startPointInSchema) {
        Object.keys(startPointInSchema).forEach(property => {
            if (!has(startPoint, property)) {
                if (startPointInSchema[property].type !== 'object') {
                    startPoint[property] = startPointInSchema[property].default
                } else {
                    startPoint[property] = {}
                }
            }
            if (startPointInSchema[property].type === 'object') {
                configIterator(startPoint[property], startPointInSchema[property].default)
            }
            if (
                !Array.isArray(startPoint[property]) &&
                typeof startPoint[property] !== startPointInSchema[property].type
            ) {
                startPoint[property] = startPointInSchema[property].default
            }
        })
    }

5) The big one, loadConfig

This is the place where it all comes together. I broke it down into 5 subsections that we will go through piece by piece.

Our new loadConfig function will do a lot of things so I stripped it down to the shell and some comments to give you the outlines.

First of all, check for the existence of a config file. We will need this in a moment.

// File: src/index.js
    bot.loadConfig = function loadConfig(config, callback) {
        bot.log.info(`Checking for config file...`)
        const configExists = fs.existsSync(this.configFile)

        /* [ALPHA]
         *  If the file does not exist, create it
         */


        /* [BETA]
         * Load the config file from the directory
         */


        /* [GAMMA]
         * iterate over the given config, check all values and sanitise
         */


        /* [DELTA]
         * write the changed/created config file to the directory
         */


         /*
          * read the new file from the directory again 
          * - assign it to the bot's config
          * - execute callback() or abort on error
          */
    }

ALPHA

If no old config is found, we simply create a new config.json in our chosen location using mkdirp, a small package resembling the desktop command mkdir -p, and prepare it with the most basic and important fields from what we are passing in on project start; discordToken, Prefix and

// File: src/index.js

        /* [ALPHA]
         *  If the file does not exist, create it
         */
        if (!configExists) {
            bot.log.info(`No config file found, generating...`)
            try {
                mkdirp.sync(path.dirname(this.configFile))
                const { token, name, prefix } = initialConfig
                const baseConfig = {
                    discordToken: token,
                    prefix,
                    name,
                }
                fs.writeFileSync(this.configFile, JSON.stringify(baseConfig, null, 4))
            } catch (err) {
                this.log.error(chalk.red.bold(`Unable to create config.json: ${err.message}`))
                throw err
            }
        }

BETA

Next step, we load the config file, no matter if it's an old one or we just created it.

// File: src/index.js

        /* [BETA]
         * Load the config file from the directory
         */
        this.log.info(`Loading config...`)
        try {
            this.config = JSON.parse(fs.readFileSync(this.configFile))
        } catch (err) {
            this.log.error(`Error reading config: ${err.message}`)
            this.log.error(
                'Please fix the config error or delete config.json so it can be regenerated.',
            )
            throw err
        }

GAMMA

Now call our configIterator with the config we read from the disk and compare it to our schema. As previously written, this makes sure that no old or mismatched values remain in the config once we decide to change the schema in the future.

// File: src/index.js

        /* [GAMMA]
         * iterate over the given config, check all values and sanitise
         */
        this.configIterator(this.config, configSchema)

DELTA

Write the checked and clean config back to the server.

// File: src/index.js

        /* [DELTA]
         * write the changed/created config file to the directory
         */
         fs.writeFileSync(this.configFile, JSON.stringify(this.config, null, 4))

EPSILON

Last but not least, reload the config from the directory and check one last time. If everything is fine, execute the callback to continue and otherwise abort with an error.

// File: src/index.js

        /* [EPSILON]
         * read the new file from the directory again
         * - assign it to the bot's config
         * - execute callback() or abort on error
         */
        jsonfile.readFile(this.configFile, (err, obj) => {
            if (err) {
                bot.log.error(chalk.red.bold(`Unable to load config.json: ${err.message}`))
                throw err
            } else {
                bot.config = obj
                callback()
            }
        })

If you want to make sure you got everything, have a look at the finished function in all it's glory and complexity.

bot.loadConfig = function loadConfig(config, callback) {
        bot.log.info(`Checking for config file...`)
        const configExists = fs.existsSync(this.configFile)

        /*
         *  If the file does not exist, create it
         */
        if (!configExists) {
            bot.log.info(`No config file found, generating...`)
            try {
                mkdirp.sync(path.dirname(this.configFile))
                const { token, name, prefix } = initialConfig
                const baseConfig = {
                    discordToken: token,
                    prefix,
                    name,
                }
                fs.writeFileSync(this.configFile, JSON.stringify(baseConfig, null, 4))
            } catch (err) {
                this.log.error(chalk.red.bold(`Unable to create config.json: ${err.message}`))
                throw err
            }
        }

        /*
         * Load the config file from the directory
         */
        this.log.info(`Loading config...`)
        try {
            this.config = JSON.parse(fs.readFileSync(this.configFile))
        } catch (err) {
            this.log.error(`Error reading config: ${err.message}`)
            this.log.error(
                'Please fix the config error or delete config.json so it can be regenerated.',
            )
            throw err
        }

        /*
         * iterate over the given config, check all values and sanitise
         */
        this.configIterator(this.config, configSchema)

        /*
         * write the changed/created config file to the directory
         */
        fs.writeFileSync(this.configFile, JSON.stringify(this.config, null, 4))

        /*
         * read the new file from the directory again
         * - assign it to the bot's config
         * - execute callback() or abort on error
         */
        jsonfile.readFile(this.configFile, (err, obj) => {
            if (err) {
                bot.log.error(chalk.red.bold(`Unable to load config.json: ${err.message}`))
                throw err
            } else {
                bot.config = obj
                callback()
            }
        })
    }

Link to the finished code / tag v0.0.4 on GitHub

Wrapping up

Using nodeJS for the first time to access and work with files can be a daunting task so depending on where you are/were with your experience, I hope I was able to keep it nice and basic and understandable.

Our Bot(s) can now be started by creating a new or loading an existing config file. Next time we will add some commands that let the users with the right roles and permissions change the config on the fly, add new tags and maybe even access those from a dashboard... stay tuned.