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 .

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:

yarn add @bluebase/plugin-launcher @bluebase/plugin-material-ui @bluebase/plugin-react-native-paper @bluebase/plugin-responsive-grid @bluebase/plugin-vector-icons @bluebase/plugin-settings-app @bluebase/plugin-react-router @bluebase/plugin-react-navigation @bluebase/plugin-responsive-grid @bluebase/plugin-json-schema-components

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

expo install react-native-safe-area-context react-native-gesture-handler react-native-reanimated

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:

yarn add @bluebase/components

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 Supabase.

Go to supabase.com and Sign up to create a new account.

Step 2: Create a New Project

Next, we need to create a new project. Click the "New Project" button once you login into the Supabase app, and follow the wizard to create your API project.

3. Create Database Table

Now we need to create our database table to store our to-do tasks.

Start by clicking the Table Editor button on the left sidebar menu. Once you're on this page, press the "Create a new table" button.

When the form opens, add the following columns to match the screenshot below:

id (uuid)
title (varchar)
description (text)

Make sure "Enable Row Level Security" is NOT checked.

4. Build GraphQL Schema

Since we are going to be building our app on top of query language, we need to tell Supabase to build its schema.

On the left sidebar menu click the "SQL Editor" button. Once on this screen, press the "+ New Query" button.

Now enter the following code snippet in the editor and press "RUN"

5. API Details

Go to Settings => API page. Here you can find the API URL and Key as shown in the screenshot below.

That's all. We're done with creating our API for the project. All we need to do is consume it now.

2.2 Setup Apollo Client

To consume our GraphQL API on the app, we will be using the popular Apollo 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

yarn add --dev @apollo/client @bluebase/plugin-apollo graphql

Step 2: Use the plugin

Same as the last time, we import the apollo plugin:

Step 3: Create Apollo Configs

Now we need to input our API URL as well as the API Token into the Apollo client. We do this by using .

Create the following file in the root folder:

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

Step 4: Use the configs

Similar to how we use the plugins, we need to pass our configs object as a prop to the BlueBaseApp component.

Change the contents of the App.tsx to match below:

Step 5: Bypass Apollo Bug

At the time of writing this tutorial, the latest version of Apollo Client (v3.5.4) has compatibility an with react-native. Add the following file in the root folder to bypass it.

This is it. Our App is configured to use the GraphQL API through the Apollo client.

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.

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:

CreateTaskScreen
EditTaskScreen
CompletedTasksScreen

So now we should have 4 screens in total.

Step 2: Adding Edit Route

Add the following EditTask route to the routes array:

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

Step 3: Create a Button to Navigate

But we still need a way to navigate to this route in our UI. Let's modify our PendingTasksScreen component to add a button:

Notice, that we use the push method from BlueBase's useNavigation hook. The method takes route name and optional params object as its arguments.

Run your app, you should now be able to navigate between routes.

Step 4: Extract Route Param

Notice that the value of path property in the route is :taskId. This means that any value that is entered in this part of the URL will be captured in the taskId param. For example the URL http://localhost:19006/p/tasks/123 will extract value 123 in the taskId variable.

Let's see how we can use this value, modify the EditTaskScreen component to match the following content:

Notice the code on Line 7, we use the getParam function to extract the URL param.

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.

src/routes.ts

export const routes = [
{
	name: 'CreateTask',
	screen: 'CreateTaskScreen',
	path: 'create',
	exact: true,

	options: {
		title: 'Create Task',
	},
},
{
	name: 'EditTask',
	screen: 'EditTaskScreen',
	path: 't/:taskId',
	exact: true,

	options: {
		title: 'Edit Task',
	},
},
{
	name: 'TasksApp',
	screen: 'PendingTasksScreen',
	path: '',
	exact: false,

	options: {
		title: 'My Tasks',
	},
}];

Import this array to your plugin file:

src/index.ts

import { createPlugin } from '@bluebase/core';

import { ToDoAppIcon } from './components/ToDoAppIcon';
import { routes } from './routes';
import { screens } from './screens';

export default createPlugin({
	key: 'tasks',
	name: 'Tasks',
	description: 'A todo app made with BlueBase framework.',

	components: {
		// Components
		ToDoAppIcon,

		// Screens
		...screens,
	},

	icon: {
		component: 'ToDoAppIcon',
		type: 'component',
	},

	indexRoute: 'TasksApp',

	routes,
});

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

Step 2: Create a Button to Navigate

But we still need a way to navigate to this route in our UI. This time we will add an icon button in the header.

Create the following component:

Also, create an index file to export the component:

Step 3: Add Button in Header

To add our new TaskCreateButton to the screen, add the headerRight property in the route options like so:

That's it, run your app to test it out.

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

4. CRUD Operations

4.1 Creating Tasks

The first thing to do would be to create a form to insert a new task in the database.

BlueBase provides a utility to create forms quickly by just writing a simple JSON-based schema. Let's get right to it.

Step 1: Install the plugin

Add the following plugin as a dependency to the project:

yarn add @bluebase/plugin-json-graphql-components

Then import and use this plugin to BlueBase:

Step 2: Create Mutation

Now we're going to write a GraphQL mutation to insert a new task in the database. Create the following file.

This tutorial does not cover how GraphQL works. If you are new to it, head over to this .

Step 3: Generate Typings

We will now generate typescript interfaces for our GraphQL API. Execute the following command:

This will create a new file at: src/graphql-types.ts.

Step 4: Create Form

Create the follwing files:

Here's what's happening in the file above:

Line 8: We import the JsonGraphqlForm from the BlueBase context. This component was added to our app by the @bluebase/plugin-json-graphql-components plugin.
Line 15: We create a callback function, that will be called once the form is successfully submitted to the API. Here we want to navigate to the main page after success.

Finally, we create the index file to export the component:

Step 5: Use Form on Screen

Now that we have created our form, it's time to add it to our layout. Change the the CreateTaskScreen component match the following code:

We're all done. Time to take our form for a test drive. Input some data into the form and submit it.

If all goes well, you should now be redirected to the task list screen. Go to Supabase admin panel, and then to the table editor to check if the data was in fact inserted into the database.

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:

Loading State: When data is loading from the database. The modern way is to show a placeholder component. To achieve this, we use the @bluebase/plugin-rn-placeholder plugin. This will add the components from the library in BlueBase. Make sure you install and add this plugin to your project.
Data State: This will render the task data after it is loaded from the database. For this, we will use List.Item component.

See the following code for a reference implementation:

Step 2: Task List Empty State

We also need to create a component that will be rendered when a list is empty. This component will show an empty message, as well as a call to action button to create a new task:

Step 3: GraphQL Query

Now with these views out of the way, it's time to start creating the actual list. The first step is to write our GraphQL query.

We intend to create our list with infinite scrolling enabled. So, whenever new data is loaded, we need to merge it with the existing data, to show it as one list. To achieve this, we also create a function in this file called TasksCollectionQueryUpdateQueryFn .

There is a in Supabase that doesn't let us send "last" and "before" params. When it is fixed, these lines should be uncommented.

Step 4: Generate Typings

We will now generate typescript interfaces for our GraphQL API. Execute the following command:

This will update the file src/graphql-types.ts.

Step 5: Task List

With all the prep work now complete, let's finally create our list. For this we will use the GraphqlList component from the @bluebase/plugin-json-graphql-components plugin. This component takes care of all the heavy lifting.

We create this component with a complete prop so that we can filter task based on this value. This will be passed as a variable to the GraphQL query.

Create the index file:

Step 6: Update screens

Last but not the least, lets add this list to the PendingTasksScreen and CompletedTasksScreen screens:

Refresh the app, and see it come to life. Enjoy!

Loading State

Empty State

Data State

4.3 Updating Tasks

Our users may want to edit their tasks or mark them as complete. We will have to create a form very similar to the one in Chapter 4.1. The only difference is that we need to query task data and prefill the form with it.

Step 1: Create Mutation

Let's start by creating an update mutation. This will be used when a user submits the form.

src/components/EditTaskForm/UpdateTaskMutation.graphql.ts

import gql from 'graphql-tag';

export const UpdateTaskMutation = gql`
	mutation UpdateTaskMutation(
		$id: UUID!
		$title: String
		$description: String
		$completed: Boolean
	) {
		updatetasksCollection(
			filter: { id: { eq: $id } }
			set: {
				title: $title,
				description: $description,
				completed: $completed
			}
		) {
			affectedCount
			records {
				id
				title
				description
				completed
			}
		}
	}
`;

Step 2: Generate Typings

We will now generate typescript interfaces for our GraphQL API. Execute the following command:

This will update the file src/graphql-types.ts.

Step 3: Create Form

Create the following component:

Explanation:

Line 22: We take task ID as a prop. This will be used as a query variable.
Line 28: A function that takes the query result as input (array of tasks) and returns a single task. This task is used as the initial value of the form.
Line 33: A function that takes form data and converts it into mutation variables. This function is called when a user submits the form.

Step 4: Add Form to Screen

Let's add our form to the EditTaskScreen component:

When you run the app, you should results similar to the screenshot below:

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.3 Dynamic Images

Let's make our app a bit visually pleasing by adding some images. The perfect place to do this is in the TaskListEmptyState component.

Step 1: Download Image

Download the following image and put it at ssets/no-tasks-light.png.

Step 2: Add the Image to the Plugin

Modify your plugin to add an assets property like the in the code below:

Basically, we're telling BlueBase that the said image has an ID NoTasks and where to find it. Now we can just reference this image by this ID and BlueBase will take care of loading and rendering it across formats.