1 of 83

BlueBase

Introduction

BlueBase is a framework built on top of React & React Native. It provides an opinionated application structure to create cross-platform native and web apps using the same code base.

Apart from this, BlueBase comes with a lot of features that are essential to all modern apps:

🔌 Plug-ins

Create modular applications by breaking different features into independent plug-ins. Plug-ins are powerful enough to enhance or modify any part of the application and can be hosted in their own repositories. This also allows code reuse across applications.

🎁 Components

Create pluggable components that can be dynamically replaced or modified through third-party plugins, without needing to change the original code. This makes it extremely easy to enhance existing views or screens in the app by writing your own plugin.

🚏 Routes

Create cross-platform routes to navigate between screens by using a simple JSON syntax.

⚙️ Configurations

BlueBase provides API to get or set application-level configurations. This allows developers or even end-users to change app settings.

🎨 Themes

A theme is a collection of styles that's applied to an entire app or component. When you apply a theme, every component in the app applies each of the theme's attributes that it supports. Developers can create their own themes as well as allow end-users to select one to their own liking.

🎡 Lifecycle events

Your application can use lifecycle hook methods to tap into key events in the lifecycle of an application to initialize new instances, initiate change detection when needed, respond to updates during change detection, and clean up before reboot.

💬 Localization

Use the localization feature to translate and adapt your app into multiple languages and regions. Create multi-lingual and even right to left apps by using the simple to use API.

🌚 Dark mode

The Dark Mode is a first-class citizen in BlueBase and the feature comes out of the box 😎.

🖼 Asset management

Add dynamic Images and assets (i.e fonts, sounds, etc), to your app that may be replaceable through plugins. Moreover use dynamic images that render different versions on mobile, desktop, light, and dark modes.

Tutorial

1. Getting Started

1.1 Setup

We will learn concepts of BlueBase by creating a production-ready To-Do app.

We will use Expo CLI to create a new project and add BlueBase to it. If Expo CLI is not installed, go to the Expo CLI Installation guide before proceeding.

Step 1: Initialize the project

Initialize an expo app by executing the following commands:

# Create a project named my-app.
# Select the "blank (Typescript)" template when prompted
expo init bluebase-todo-app

# Navigate to the project directory
cd bluebase-todo-app

More info here.

Step 2: Install BlueBase package

Step 3: Update App File

Step 4: Run App

This will open the expo console.

You can launch the web or native version of the app from here.

1.2 Add Plugins

All functionality in BlueBase is added via plugins. Let us add some ready-made plugins to our project to take a head start on building our app.

Step 1: Install plugins

Start by adding following devDependencies:

Some of the plugins (react-navigation) require some more dependencies to be installed:

Step 2: Create plugin files

Now in the root folder create the following file plugins.ts:

The file above exports an array of plugins, imported from their respective modules.

Create another file similar to the one above and name it plugins.native.ts. This way react-native compiler will load this version rather than plugins.ts on native platforms.

So by doing this, we can add web-specific plugins in plugins.ts and native specific code in plugins.native.ts.

In this case, the difference in the above 2 files is that plugins.ts uses:

@bluebase/plugin-react-router
@bluebase/plugin-material-ui

While plugins.native.ts uses the following instead:

@bluebase/plugin-react-navigation
@bluebase/plugin-react-native-paper

Step 3. Import plugins

Now edit the App.tsx file and add the following content.

Here, we import the plugins array and pass them to the BlueBaseApp component as a prop.

Step 4: Add Babel plugin

Lastly, modify the contents of babel.config.js file to:

Step 5: Run

Now run the app again:

You should see the following screen on launch:

Home Screen

Settings App

Explanation

So as you can see, by just installing a few plugins, we were able to add a lot of functionality in a very short span of time, by writing very few lines of code.

I'll try to briefly describe what purpose each plugin serves.

Plugin

Purpose

1.3 Create Custom Plugin

By now it should be clear that all functionality in BlueBase is added via plugins. So in order to add views to our To-Do app, we need to create our own plugin.

Step 1: Install components library

Start by adding the following dependency:

This library provides typescript typings of components imported from the BlueBase context.

Step 2: Create a plugin icon

The first thing that we will do is to create a plugin icon component. Create the following files:

The code above uses the BlueBase theme syntax to customize styles. Read more about it in the .

Step 3: Create plugin

Time to create the plugin itself. Create the following file:

In the above code, we use the createPlugin function from the the @bluebase/core library. This function takes attributes as input, and returns a BlueBase Plugin.

The key property servers as the plugin ID, as well as the slug in the plugin URL path. So in this case the path to access this plugin would be: http://localhost:19006/p/tasks.
The name and description properties are pretty self explanatory. The name property is rendered below the icon on the home screen.

Step 4: Use the plugin

Now we're all set to use our shiny new plugin Edit our plugin files to add our own plugin to the list.

Step 5: Run

Now run the app again:

You should see the following screen on launch:

2. Backend API

2.1 Create Backend API

Before we start creating our app, we first need to create an API connected to a database. For this purpose, we will use a free tool called .

Go to and Sign up to create a new account.

2.2 Setup Apollo Client

To consume our GraphQL API on the app, we will be using the popular Graphql Client. Luckily, we already have an Apollo plugin available for BlueBase that takes care of all the setup.

Step 1: Install the BlueBase Apollo plugin

2.3 Generate Typescript Interfaces

The last step is to generate typescript interfaces from our GraphQL schema. This step is used to enhance the developer experience to strongly type our API.

1. Add dependencies

Install the following dev dependencies:

yarn add @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations graphql --dev

2. Make your API accessible

Add the following script to the script section of your package.json file:

3. Create the codegen config file

Create a file codegen.yml in the root directory:

Replace [[API_URL]] and [[API_KEY]] with the values relevant to your project.

3. Create Screens

3.1 Pending Tasks Screen

Ok, so now with the configurations out of the way, it's time to start coding our app. The first thing we need to do is to create an application skeleton by developing empty screens and configuring the navigation mechanism.

The first screen that we are going to create is going to show a list of pending tasks.

Step 1: Create Screen View

Let's start by creating our screen view component. Let's call it PendingTasksScreen. Feel free to copy the code below.

src/screens/PendingTasksScreen/PendingTasksScreen.tsx

import React from 'react';
import { Text, View } from 'react-native';

export const PendingTasksScreen = () => {
	return (
		<View style={{ padding: 10 }}>
			<Text>PendingTasksScreen</Text>
		</View>
	);
};

PendingTasksScreen.displayName = 'PendingTasksScreen';

All we're doing right now is rendering the component name. Don't worry we will add the actual list later.

Also, create the following index file:

And also:

Step 2: Create Route

BlueBase provides an abstraction to create navigation plugins. This allows us to be able to use any navigation library in our app. For now, we have created & integrations.

The navigation API is loosely based on . It is very simple to create your own routes. Just add the routes property to your plugin. This is an array of objects:

Explanation of the code above:

Line 12: We changed the plugin's index route to the new one created at Line 23. By doing this, whenever we press the task icon on our launcher, we get navigated to this screen.
Line 19: Notice we added the PendingTasksScreen component to BlueBase. This is so we can reference it in our route configuration at Line 24. This is where we tell BlueBase what component to render once we have navigated to that route.
Line 23: Name of the route. We use this name to navigate to this screen. We will see an example of this later.

That's all. Run your app, and test your new screen.

3.2 Edit Task Screen

Next up, we are going to create a screen that will allow a user to edit a task.

Step 1: New Screens

Before we move forward to adding new routes, let's quickly create 3 copies of our PendingTasksScreen component, and give them the following names:

3.3 Task Create Screen

We also need a screen to create a new task.

Step 1: Create Route

Similar to the previous section, now we create our third route. Notice that I have now moved the routes array dedicated file, to keep to code readable.

Import this array to your plugin file:

This should create the third route, which should be accessible via the following URL:

3.4 Tab Navigation

To improve the user experience of our app, we want to add tabs on the main page. One tab will show all pending tasks, while the other one will show the completed tasks.

Step 1: Add Tab Navigator

It is possible to add nested routes in BlueBase. Whenever we want to do this, we will add a navigator property in the route. There are several navigators available to use (i.e. switch, stack, tab

4. CRUD Operations

4.2 Reading Tasks

It's time to query our API for all pending and completed tasks and display them as a list.

Step 1: Task List Item

The first step is to create a list item that will render a single task.

Let's create a new component called TaskListItem . This component will have 2 states:

Key Concepts

Consuming Selected Theme

BlueBase exports a ThemeConsumer component to utilise current theme. This is a render prop component, which means it takes a function as a child. The function gets an object in the param with the following interface:

interface ThemeContextData {

    // Helper method to change current theme.
    changeTheme: (slug: string) => void,

    // Current theme
    theme: Theme
}

Usage

The following snippet illustrates how to use a ThemeConsumer component.

const ThemedComponent = () => (
    <ThemeConsumer>
    {
        ({ theme, changeTheme }: ThemeContextData) => {
            // Use theme context here..
        }
    }
    </ThemeConsumer>
);

Example: ThemePicker

The following example shows how to use ThemeConsumer component to create a theme picker. This renders a picker component with a list of all installed themes. It not only uses the current theme to style itself, but also utilises the changeTheme method to switch themes.

API

Logger

BlueBase's Logger API allows you to log messages to any number of logging services.

Working with the API

You can call logger for different console message modes:

BB.Logger.log('log bar');
BB.Logger.info('info bar');
BB.Logger.debug('debug bar');
BB.Logger.warn('warn bar');
BB.Logger.error('error bar');

When handling an error:

try {
    ...
} catch(e) {
    BB.Logger.error('error happened', e);
}

Integrations

To add support for a Logging Provider see this .

Guides

Components

PluginIcon 📌

Displays an icon of a Plugin. The icon properties are taken from plugin.icon property of plugin.

If no plugin is found, renders an error message.
If a plugin has no icon, renders null.

System Component 📌

This component is shipped with BlueBase Core.

Usage

Properties

Noop 📌

A component that does... nothing!

System Component 📌

This component is shipped with BlueBase Core.

ErrorObserver 📌

Observes any exceptions in child tree hierarchy. When an exception is caught, displays an Error state to gracefully handle it on the frontend.

System Component 📌

This component is shipped with BlueBase Core.

Usage

Properties

View

5.1 Internationalisation

Internationalisation is a big part of modern apps. BlueBase has built-in support for translations and right-to-left (RTL) text support.

Go you the Settings app, and select a language. If the language needs RTL, BlueBase will change orientation automatically.

Changing content direction on native requires app to be restarted.

You can add support for any language you desire. Here are the steps on how to do this:

Step 1: Adding Language to the system

We support English and Urdu languages by default. If you need to add support for any other language just pass them to the locale.options object in your configs file, where the key of the object is the language code, and value is the language name.

Step 2: Provide Translations

Next, we have to create a dictionary, that the system can refer to when attempting to translate a string. The dictionary is an object where where original string is the key, and the translated version is the value.

The way to do it is, we create a function that takes a dictionary as input, and we return that dictionary by appending our own translations to it. This is because the translations feature in BlueBase is built upon its feature.

The filter key for format to add translations is: bluebase.intl.messages.${language_code}. So for french language it would be bluebase.intl.messages.fr.

When we have all our language filters setup, we just need to add them to the filters object in the plugin.

Step 3: Translating Strings

While we attempt to give built in conversion support for our official plugins, you may still need to do one additional step to convert your string to the current locale.

We'll take example of our TaskListEmptyState component. When you select a language different than English, you will note that the text is still not translated. Let's change that.

Go to your component and change to code to the following:

You will note that:

Line 2: We import useIntl hook from @bluebase/core.
Line 9: We extract the __ function from the useIntl() hook.

That's all! Since we have already provided translations to these strings in previous step, when you refresh the app you will now observe the text to be converted.

5.4 Settings & Configurations

Now that we have created our plugin that adds the Tasks functionality to our app, let's see if we can make it configurable.

There are "configurable", we mean 2 things:

A developer that is using this plugin, can configure it via the configs prop.
An end-user can configure the feature through the "Settings" UI.

We will attempt to do both these things in this chapter. For this example, we will make the number of items our Task List loads per page.

Step 1.1: Consume a Variable from the Config

Let's go back to our TaskList component from .

Change Line 32 from:

To:

Basically, rather than having a hardcoded number in the code, we extract it from config with key 'tasks.itemsPerPage'. We utilize the useConfig hook for this purpose, that is imported from the @bluebase/core package.

Note that the useConfig hook has the same API as the useState hook in the react library.

This should be your final code now:

Step 1.2 Add Default Configs

Now that we are using the config, we also need to define its default value. Add the defaultConfigs object to your plugin as shown in the code below:

Now run your app and inspect. You will observe that BlueBase has successfully loaded the default config, which has been passed onto the GraphqlList component.

Step 1.3: Override Config Value

Now comes the fun part. Let's override this value from our app's configs:

Run your app again. You will observe that the value in the configs was loaded and preferred over the defaultConfigs.

Now, let's see how we can allow the end-user to customize the value too.

Step 2.1: Create a Form

Let's create a form that will allow the user to input a value, and update the config when he presses the submit button.

For this purpose, we will use the JsonForm component from the @bluebase/plugin-json-schema-components.

The props of JsonForm component are very similar to the GraphqlJsonForm that we have previously usesd.

This is because the GraphqlJsonForm too uses JsonForm internally.

JsonForm component is built using the library.

Add the index file to export the component.

Step 2.2 Add Screen in the Settings App

Now we want to create a screen for "Tasks" in the Settings app. Luckily the Settings app allows this to be done via bluebase.plugin.setting-app.pages filter.

This filter inputs an array of screens in the settings app, all we have to do is to append our own screen configs and return the array. Create a new file and copy the following code:

Note that in Line 22 till 27 we define the "Task Settings" panel and use the TaskSettingsForm component that we created in the previous step.

Let's add this filter to the plugin (See Line 13):

Run the app and go to the settings section. You will see the "Tasks" settings page is added.

When you use and submit the form, you will observe that it will update the config to achieve the desired result:

import { getComponent, useNavigation } from '@bluebase/core'; import { JsonGraphqlFormProps } from '@bluebase/plugin-json-graphql-components'; import React, { useCallback } from 'react'; import { TasksCollectionQueryQuery, TasksCollectionQueryQueryVariables, TasksInsertInput, UpdateTaskMutationMutationVariables } from '../../graphql-types'; import { TasksCollectionQuery } from '../TaskList/TasksCollectionQuery.graphql'; import { UpdateTaskMutation } from './UpdateTaskMutation.graphql'; const JsonGraphqlForm = getComponent<JsonGraphqlFormProps<any>>('JsonGraphqlForm'); export interface EditTaskFormProps { id: string; } export const EditTaskForm = (props: EditTaskFormProps) => { const { navigate } = useNavigation(); const { id } = props; const onSuccess = useCallback(() => { navigate('TasksApp'); }, []); const mapQueryDataToInitialValues = useCallback( (data: TasksCollectionQueryQuery) => { return data?.tasksCollection?.edges[0]?.node; }, []); const mapFormValuesToMutationVariables = useCallback( (task: TasksInsertInput): UpdateTaskMutationMutationVariables => { return { id: task.id, title: task.title, description: task.description, completed: task.completed }; }, []); const queryVariables: TasksCollectionQueryQueryVariables = { filter: { id: { 'eq': id } } }; return ( <JsonGraphqlForm query={{ query: TasksCollectionQuery, variables: queryVariables }} mutation={{ mutation: UpdateTaskMutation, refetchQueries: [TasksCollectionQuery], awaitRefetchQueries: true }} onSuccess={onSuccess} mapFormValuesToMutationVariables={mapFormValuesToMutationVariables} mapQueryDataToInitialValues={mapQueryDataToInitialValues} {...props} schema={{ validateOnBlur: false, validateOnChange: false, fields: [ { autoFocus: true, label: 'Title', name: 'title', required: true, type: 'text', }, { label: 'Description', name: 'description', type: 'text', }, { label: 'Completed', name: 'completed', type: 'checkbox', }, { name: 'status', type: 'status', }, { name: 'submit', title: 'Update Task', type: 'submit', }, ], }} /> ); }; EditTaskForm.displayName = 'EditTaskForm';

Higher Order Components

A higher-order component's role is to wrap a regular component to pass it a specific prop (such as a list of posts, the current user, the Router object, etc.). You can think of HOCs as specialised assistants that each hand the component a tool it needs to do its job.

The first argument of set is the component's name, the second is the component itself, and any successive arguments will be interpreted as higher-order components and wrapped around the component.

For example, this is how you'd pass the currentUser object to the Logo component:

await BB.Components.register({
    key: 'Logo',
    value: LogoComponent,
    hocs: [withCurrentUser]
});

"Delayed" HoCs

There are a few subtle differences between registering a component with register and the more standard export default Foo and import Foo from './Foo.jsx' ES6 syntax.

First, you can only override a component if it's been registered using register. This means that if you're building any kind of theme or plugin and would like end users to be able to replace specific components, you shouldn't use import/export.

Second, both techniques also lead to different results when it comes to higher-order components (more on this below). If you write export withCurrentUser(Foo), the withCurrentUser function will be executed immediately, which will trigger an error because the fragment it depends on isn't properly initialised yet.

On the other hand, register doesn't execute the function (note that we write withCurrentUser and not withCurrentUser()), delaying execution until app's initialisation.

But what about HoC functions that take arguments? For example if you were to write:

The withList(options) would be executed immediately, and you would have no way of overriding the options object later on (a common use case being overriding a fragment).

For that reason, to delay the execution until the start of the app, you can use the following alternative syntax:

Add HOCs to existing Components

You can add new HOCs to the already registered components any time by using the addHocs method.

BlueBase

Introduction

🔌 Plug-ins

🎁 Components

🚏 Routes

⚙️ Configurations

🎨 Themes

🎡 Lifecycle events

💬 Localization

🌚 Dark mode

🖼 Asset management

Tutorial

1. Getting Started

1.1 Setup

Step 1: Initialize the project

Step 2: Install BlueBase package

Step 3: Update App File

Step 4: Run App

1.2 Add Plugins

Step 1: Install plugins

Step 2: Create plugin files

Step 3. Import plugins

Step 4: Add Babel plugin

Step 5: Run

Home Screen

Settings App

Explanation

1.3 Create Custom Plugin

Step 1: Install components library

Step 2: Create a plugin icon

Step 3: Create plugin

Step 4: Use the plugin

Step 5: Run

2. Backend API

2.1 Create Backend API

Step 1: Sign up

2.2 Setup Apollo Client

Step 1: Install the BlueBase Apollo plugin

2.3 Generate Typescript Interfaces

1. Add dependencies

2. Make your API accessible

3. Create the codegen config file

3. Create Screens

3.1 Pending Tasks Screen

Step 1: Create Screen View

Step 2: Create Route

3.2 Edit Task Screen

Step 1: New Screens

3.3 Task Create Screen

Step 1: Create Route

3.4 Tab Navigation

Step 1: Add Tab Navigator

4. CRUD Operations

4.2 Reading Tasks

Step 1: Task List Item

Key Concepts

Consuming Selected Theme

Usage

Example: ThemePicker

API

Logger

Working with the API

Integrations

Guides

Components

PluginIcon 📌

System Component 📌

Usage

Properties

Noop 📌

System Component 📌

ErrorObserver 📌

System Component 📌

Usage

Properties

View

2.3 Generate Typescript Interfaces

1. Add dependencies

2. Make your API accessible

3. Create the codegen config file