Skip to main content

React

Welcome to the React quick start guide. This tutorial will introduce you to AgileTs and teach you how to use its basic functionalities in React. By the time you finish this guide, you should be able to start building your own AgileTs applications. We recommend proceeding from top to bottom because some sections build on each other.

🔽 Installation#

Let's start with the installation. If you haven't planned to install AgileTs yet, you can skip the Installation Section and jump straight into the 'Create first State' guide.

In order to use AgileTs in a React Environment, we need to install two packages.

npx create-react-app my-app --template agile

If you have planned to start a project from scratch using AgileTs, feel free to use the create-react-app command with the AgileTs template. This will automatically generate a fully functional react-app with AgileTs installed. Otherwise, you can install the core and react packages directly in your existing React application.

📁 @agile-ts/core#

npm install @agile-ts/core

The core package contains the State Management Logic of AgileTs and therefore offers powerful classes such as the State Class.

📂 @agile-ts/react#

npm install @agile-ts/react

The React Integration, on the other hand, is an interface to React and provides useful functions like the useAgile() hook to bind States to React Components for reactivity.

💡 Create first State#

After we have set up a project with AgileTs installed, we can start creating our first AgileTs State. But first things first, what is a State in AgileTs?

❓ What is a State#

A State provides a global information we need to remember at a later point in time. Such information might be the current theme or the logged-in user, which we need to access globally in multiple Components. In AgileTs States are created with the help of an instantiated Agile Instance often called App.

const MY_FIRST_STATE = App.createState("Hello World");

After a successful instantiation, we can dynamically and easily manipulate its value.

MY_FIRST_STATE.set("Hello There"); // Set State Value to "Hello There"
MY_FIRST_STATE.undo(); // Undo latest change
MY_FIRST_STATE.is("Hello World"); // Check if State has a specific Value
MY_FIRST_STATE.persist(); // Persist State Value into Storage

Agile Instance (App)#

As you have just seen, States are created with the help of an instantiated Agile Instance called App.

const App = new Agile();

But what is this Agile Instance and why do we need it to create a State? Simply put, the Agile Instance is the brain of AgileTs and manages all our States. It should be noted that it doesn't store the States; It only manages them. Each State has an Instance of the Agile Class, for example, to ingest its changes into the runtime. In summary, the main tasks of the Agile Class are to:

  • queuing Agile Sub Instance changes in the runtime and preventing race conditions
  • update/rerender subscribed Components through Integrations like the React Integration
  • Integrating with persistent Storage
  • provide configuration object

🔴 Live Example#

To get a better understanding of how to use a State, we should try it out. Therefore, we have created a Live Example, where we can see a State in action. The sample project we'll look at is a small counter that lets us increase a number as we click the 'Update State' button. It may not be fascinating, but it shows all the essential pieces of a React + AgileTs application in action. After playing a bit with the live example, we recommend taking a look at the Important Code Snippets Section below, where important code snippets related to AgileTs are described in more detail. In case you have any further questions, don't hesitate to join our Community Discord.

Live Editor
Result

Hello World

Check out the code sandbox to see the whole example in a production near environment.

💻 Important Code Snippets#

const App = new Agile();

1️⃣ In order to instantiate any State, we need an AgileTs Instance. Such an Instance can be seen as the brain of AgileTs, which manages all our States. Be aware that you should avoid having multiple Agile Instances in one application!

const MY_FIRST_STATE = App.createState("Hello World");

2️⃣ Now, we can create our first State using the previously instantiated AgileTs Instance. In our example, we have assigned the initial Value 'Hello World' to the State.

const myFirstState = useAgile(MY_FIRST_STATE); // Returns 'Hello World x'

3️⃣ Here we bind our created State to the React Component using the useAgile() Hook. This ensures that the Component rerenders whenever the State value mutates. The useAgile() Hook returns the current value of the State. So in our case 'Hello World'. Be aware that React Hooks can only be used in Function Components! For Class Components we have provided a Higher Order Component called AgileHOC as alternative.

MY_FIRST_STATE.set(`Hello World ${++helloWorldCount}`);

4️⃣ To bring some life into our small application, we update the State value with the help of the set() function on each 'Update State' button press.

😱 Troubleshooting#

Component doesn't rerender when State mutates.#

Such an issue might occur when the automatic integration of React has failed. It often helps to manually integrate the React Integration into the Agile Instance then.

import {Agile} from "./agile";
import reactIntegration from "@agile-ts/react";
const App = new Agile().integrate(reactIntegration);

If the problem continues to occur. Join our Community Discord. We are looking forward to helping you.

💡 Create first Collection#

Now that we know the basics of the State Class, we can continue learning something about Collections. Simply put, a flexible array of States.

❓ What is a Collection#

A Collection provides a global set of information we need to remember at a later point in time. It is designed for arrays of data objects following the same pattern. For example, it can be used to remember a flexible list of todo items globally. Like a State, it is created with the help of an instantiated Agile Instance often called App.

const MY_COLLECTION = App.createCollection();

After a successful instantiation, we can dynamically and easily manipulate its value.

TODOS.collect({id: "id1", todo: "Clean Bathroom"}); // Add new Data
TODOS.update("id1", {todo: "Clean Room"}); // Update already collected Data
TODOS.remove("id1").everywhere(); // Remove Data at 'id1'
TODOS.persist(); // Persist Collection Value into Storage

Each data we collect needs a unique primary key like an id to be correctly identified later.

TODOS.collect({id: "id2", todo: "Try AgileTs"});

In the above code snippet, 'id2' at the primary key property id is the unique primary key. Every collected data will be automatically transformed into an extension of the State Class called Item. Such an Item has the collected data as value, so in the above example, that would be '{id: "id2", todo: "Try AgileTs"}'. A so-called Item has the same functionalities as normal States.

MY_COLLECTION.getItem('id2').patch({todo: "Clean Bathroom"});

Besides Items, a Collection consists primarily of Groups. A Group allows us to split a Collection into multiple individual sections without losing any redundant behavior. By default, each Item will be added to the default Group, representing the default Collection pattern. Keep in mind, that a Group doesn't store the Item itself. It only holds an array of primaryKeys like a keymap of the data it represents.

const USER_TODOS = TODOS.createGroup("user-todos", ["id1", "id2"]); // TODOS of a specifc User
const TODAY_TODOS = TODOS.createGroup("today-todos", ["id3", "id2", "id5"]); // TODOS for Today

You can imagine a Group like an interface to the Collection Data.

🔴 Live Example#

In this Live Example, we see a simple Collection in action. The sample project we'll look at is a small todo list that lets us create todos with the help of a text input and remove them with a button below each todo item. In case you have any further questions, don't hesitate to join our Community Discord.

Live Editor
Result

Simple TODOS

Clean Bathroom

Check out the code sandbox to see the whole example in a production near environment.

💻 Important Code Snippets#

const MY_FIRST_COLLECTION = App.createCollection({
initialData: [{id: 1, name: "Clean Bathroom"}]
}).persist('todos');

2️⃣ In order to create our first Collection, we need the previously instantiated Instance of AgileTs called App. Then we can bring our first Collection to life and add the initial data {id: 1, name: "Clean Bathroom"} to it. Besides the creation, we store the Collection permanently in the localStorage with the help of the persist() method. So if you refresh the page, your modifications to the todo list shouldn't be lost.

const myFirstCollection = useAgile(MY_FIRST_COLLECTION);

3️⃣ Here we use the useAgile() React Hook to bind our Collection to the React Component. When passing a Collection, useAgile() returns the default Group value in array shape. So in our case, something like:

[
{id: 1, name: 'Clean Bathroom'},
{id: 5, name: 'Learn AgileTs'}
]
MY_FIRST_COLLECTION.collect({id: generateId(), name: currentInput});

4️⃣ To add new Data to the Collection, we can use the collect() method. In the example snippet, we add the currentInput with a random id as primaryKey to the Collection.

TODOS.remove(value.id).everywhere();

5️⃣ If we have done a todo, of course, we want to remove it. For this, we can use the remove() method and pass the primaryKey of the Item to be removed. The everywhere() tag means that the Item will be removed from the whole Collection and not just from a specific Group.

🔍 Next Steps#

Now that you know the basics of AgileTs, you can take a look into the Style Guide Section, to learn something about: How to structure an application using AgileTs? Or you check out the specific package documentations, where everything is described in more detail.

Last updated on