REAXIOM

Reaxiom is a library to help react projects to communicate with backends. With reaxiom you have boilerplates, built-in components and a file generator to fasten your work. The current version is only a beta and focuses on firebase basic integration.

INSTALLATION

First you need to use create-react-app :

npx create-react-app <project>

From the project folder, install reaxiom :

npm install reaxiom

You can then launch the reaxiom init tool ;

npx reaxiom init

You have 3 options to initialize a project :

• Vanilla : minimal project structure and dependencies

• Redux : just like a vanilla project but with redux preset

• Firebase : complete project with every backend tools available

STRUCTURE OF A PROJECT

Reaxiom initialize projects with a certain folder structure in ./src

The following structure is given for a firebase project :

• /components : UI and Entities components

  • /UI : pure UI components you build

  • /Entities : entity item, entity list and entity form

• /helpers :

  • /Aux.js : wrapper component for JSX validity

  • /ObjectUpdater.js : merge old object with updated properties

• /layout : main layout of your app

• /pages : components used as page with react-router

• /repositories : CRUD methods to use with your entities

• /routes : routes of your app

• /rxmconfig : reaxiom configuration

  • /backend :

    • /fbconfig.js : firebase configuration (credentials, roles, auth and misc...)

    • /rules.md : exemple of rules to add in firebase

  • /styles : css modules used by reaxiom built-in components

  • /translations : translations of built-in components texts

• /store : redux folder with actions and reducer preset

  • /actions : index of actions, action types and actions files

  • /reducers : redux reducers

Reaxiom add in the root folder a jsconfig.json file to shorten imports statements:

{
    "compilerOptions": {
    "baseUrl": "src"
},
    "include": ["src"]
}

Reaxiom also modify those files :

• src/App.js

• src/App.css

• src/index.js

• public/index.html

DEPENDENCIES INSTALLED

A set of dependencies is automatically installed with project initialization

• Vanilla :

  • react-router-dom

  • react-helmet

  • recompose

• Redux :

  • +vanilla

  • redux

  • react-redux

  • redux-thunk

• Firebase :

  • +redux

  • firebase

SET-UP FIREBASE

Set up the app :

• First you need to create a new project on firebase

• Configure authentification with email (more provider will be added in the futur)

• Initialize the firestore database (reaxiom doesn't work with realtime db)

• Initialize the cloud storage

• Add a new application in firebase and copy the given configuration in

  • src/rxmconfig/backend/fbconfig.js => fbconfig.sdkConfig.firebase

Set up rules and create an admin user

• Go to your database and add the rules given in src/rxmconfig/backend/rules.md

• Launch your app with "npm start" and go to SIGN UP

• Create a new account, it will be the admin account

• Back to your database copy the new user id in your clipboard

• Create a new collection called : roles

• Past the copied ID to the doc ID instead of the auto generated one

• Add an ADMIN field with a bool value of true

• Go back to your app and refresh

• If everything is well setup you must see the DASHBOARD button in the navbar

FILE GENERATOR

Launch the file generator with :

npx reaxiom gen

GENERATE STATELESS & STATEFUL COMPONENTS

Options to select in the GUI :

> Stateless Component or Stateful Component

> Give a name to the component like 'CompName'

> Choose a kind of component : UI or Page

• UI : the component will be created in src/components/UI/CompName

• Page : the component will be created in src/pages/CompName

  • A new route is automatically created in src/routes/routes.js

  • A route is automatically added in App.js with path '/compname'

Select options for the component :

• With router : add imports for router connexion as well as withRouter export

• With redux map : add redux imports and mapStateToProps / mapDispatchToProps methods

• With firebase map : add redux imports and specific firebase mapStateToProps

• With auth protection : add reaxiom imports and withAuthorization exports

• No option selected : you can press enter to generate component with no options

GENERATE ENTITY AND REPOSITORY

Options to select in the GUI :

> Entity & Repository

> Give a name to the entity like 'EntityName'

> Choose the first property name like 'property'

> Choose a type of field to use as input in the entity form

> Add another property if needed

• You will have to add rules to firestore to enable access to the entity

Note about file type :

• Reaxiom can currently handle only one file type property

• The file can currently only be images

• The file type property will be enhanced in the futur to offer more flexibility

• You have to manage cloud storage rules in firebase to secure your data

USE A REPOSITORY

• Generate a stateful component with at least firebase option

Get all entities in real time and display a list

• Imports in the component your EntityRepository

  • "import EntityRepository from "repositories/EntityRepository";"

• Create a property in the component state and initializes it as null

• Create a listener in componentDidMount with the getAllInRealTime() method from the repo

• The getAllInRealTime method needs two arguments :

  • this.props.firebase (from the mapStateToProps method)

  • A callback method (exemple : this.setEntities) to update the state

• Then in componentWillUnmount() unsubscribe to the listener to prevent memory leaks

• Finally Create the setEntities method to update the state with datas

Example :

state = {
    news : null
}

componentDidMount(){
    this.newsListener = NewsRepository.getAllInRealTime(
						    this.props.firebase, 
						    this.setNews);
}

componentWillUnmount(){
    this.newsListener();
}

setNews = news => {
    this.setState({
	    news : news
    })
}

• Imports the EntityList from components/Entities/Entity/EntityList

• If needed you can import the EntityForm from components/Entities/Entity/EntityForm

• Create a conditional rendering on the state property and pass datas as props to the List

Example :

render(){

    return(
	    <div  className={styles.Container}>
		    <NewsForm/>
		    {this.state.news &&
			    <NewsList datas={this.state.news}/>
		    }
	    </div>
    );
}

• You can then use props.datas.property to display the wanted property in the main Entity file

Example :

import React from 'react';
import styles from './News.module.css';

const News = (props) => {
    return(
	    <div className={styles.Container} key={props.datas.newsId}>
		    <h2>{props.datas.title}</h2>
		    <img src={props.datas.fileUrl} alt={props.datas.title}/>
		    <p>{props.datas.content}</p>
	    </div>
    )
}

export default News;

Get all entities and display a list

• Follow the same guidelines as real time but use getAll method instead

Get one entity with its ID

• Follow the same guidelines as real time but use getOne method instead

• getOne needs three arguments :

  • this.props.firebase (from the mapStateToProps method)

  • The unique ID of the entity (avalaible as entitynameId field)

  • A callback method (exemple : this.setEntity) to update the state

• You then need to imports the Entity main file and pass datas as props

CRUD OPERATIONS

Create an entity

• Use the create method from the repository

• It needs three arguments :

  • this.props.firebase (from the mapStateToProps method)

  • this.props.session (from the mapStateToProps method)

  • Datas as an object to create the entity

Update an entity

• Use the update method from the repository

• It needs three arguments :

  • this.props.firebase (from the mapStateToProps method)

  • The unique ID of the entity (avalaible as entitynameId field)

  • Datas as an object to update the entity

Delete an entity

• Use the delete method from the repository

• It needs two arguments :

  • this.props.firebase (from the mapStateToProps method)

  • The unique ID of the entity (avalaible as entitynameId field)

Create custom repository methods :

• You can create your custom repository methods in the EntityRepository file

• It is useful if you need to order or limit the datas in read operations

BUILT-IN COMPONENTS

Reaxiom offers a set of specials built-in components

<AnonContent>

The content passed as children will only be visible to anonymous users

import { AnonContent } from "reaxiom";

...

    <AnonContent>
    
	    <span>Only visible for anonymous users</span>
    
    </AnonContent>

<AnonLink>

It's a wrapper of the react router component. The link will only be visible for the anonymous users. It uses the "to" props as a path

import { AnonLink } from "reaxiom";

...

    <AnonLink to={ROUTES.signin}>
	    Signin
    </AnonLink>

<AuthContent>

The content passed as children will only be visible to auth user. You can specify roles as a props to authorize only certains users

import { AuthContent } from "reaxiom";

import { roles } from "reaxiom";

...

    <AuthContent roles={roles.ADMIN}>
    
	    AdminInfos
    
    </AuthContent>
    

<AuthLink>

It's a wrapper of the react router component. The link will only be visible for the auth user You can specify roles as a props to authorize only certains user. It uses the "to" props as a path

import { AuthLink } from "reaxiom";

import { roles } from "reaxiom";

...

    <AuthLink to={ROUTES.signin} roles={roles.ADMIN}>
    
	    AdminDashboard
    
    </AuthLink>

<SigninForm> | <SignupForm> | <PasswordForgetForm>

A set of forms to signin, signup and password reset

• Those forms can be customize in rxmconfig/styles

• Experimental translation available in rxmconfig/translations

<EmailVerify> - experimental

• A component displayed as a placeholder for unverified users

• It allows the user to send another confirmation email

ADD CUSTOM ROLES

• Custom roles can be added in rxmconfig/backend

• Follow the existing pattern and add roles in your roles collection

FUTUR UPDATES

Reaxiom is in an early beta state, it will be heavily updated in the futur.

Upcoming features :

• Multiple file types and file fields in forms
• Role generator and firebase rules generator
• Plugins manager
• Multiples auth providers for Firebase
• AWS cloud support
• Custom Node.js server support

LICENSE

Reaxiom is an open source library under GPL-3.0 license. Please make sure to let the sources available if you reuse the project.