@realtoken/realt-commons

Links

• RealT-commons 🧰
  • Stack
  • Technologies used
    • React
    • Typescript
    • Mantine
    • web3-react
    • Jotai
    • Eslint and Prettier
    • dotenv
• Documentation structuration
  • User
  • Developer:
• User doc
  • How install the package ?
  • Setup
    • [MANDATORY] Realt provider
    • Web3
      • How does is works ?
      • Web3 networks (chain)
        • Defaults chains
        • Custom chain
      • Available connectors in library
        • Metamask
        • Gnosis Safe
        • Wallet Connect V2
        • Read Only
        • Frame (coming soon)
    • Providers
      • Web3 provider (Web3Providers)
      • MantineProviders
    • Translation
  • Modules
    • Layout and built-in components
      • Customizing theme
  • Modals
    • Add provider
    • Create new modals
    • Use my custom modals
    • Customize modals theme
• Developer doc
  • How does the library is structured ?
  • How to build the package ?
  • How to use package localy ?
  • Handle translation
• Contributing

RealT-commons 🧰

RealT-interface-commons is a toolkit designs to help realt's community devs to create unified interfaces. This toolkit is base

Some cool features:

• Web3 wallet connection modal
• Header and Footer
• Filtering hook

Stack

This toolkit has strong dependency with react and mantine.

But you are free to use any web framework you want: Next.js, Gatsby, Express, React routing, etc...

Technologies used

React

React is used to create dynamic interface.

Typescript

Typescript is a top-layer technology used to typed (add boolean, number etc...) types to javascript. It also significantly reduces errors during development.

Mantine

Mantine is the UI development kit we choosed to create the YAM interface. We choose it because Mantine is under intensive developmenent and is opensource. It also perfectly match with React, our front-end framework.

web3-react

Web3-react is a typescript/javascript library used to connect YAM to blockchain through different wallet: Injected (Metamask, Frame, etc...), Coinbase, Wallet-connect, etc...

Jotai

Jotai is a small state manager.

Eslint and Prettier

EsLint and Prettier are too software used to check and clean code, and check for synthax errors into the code.

dotenv

DotEnv is a library used to read environement variable from .env file.

Documentation structuration

The documentation is divided in two distinct parts, for two different profile.

User

This part of the doc is dedicated for people who wants to use the library in one of their project.
[User doc](# User doc)

Developer:

This part of the doc is dedicated for developers who wants to modify/contribute to the library's development.
User doc

User doc

How install the package ?

# With npm
npm i @realtoken/realt-commons

# With yarn
yarn add @realtoken/realt-commons

Also some mandatory packages are also needed:

yarn add react-i18next i18next

More infos:

Package name	Utilization
react-i18next	Used for translation
i18next	Used for translation

Setup

[MANDATORY] Realt provider

Requirement:
You need to install mandatory packages.

The RealtProvider component is a key and mandatory component to work with realt-commonns library. To setup it wrap your entire application within it (e.g in next it's in the _app.tsx component):

<RealtProvider
  value={{ ...values }}
>
  ...others providers
</RealtProvicer>

Values are object like:

Key name	Description	Values	Default value
env	Wanted environement	("production" or "staging" or "development") or from environment constant file.	"production" (environment.PRODUCTION)
showAllNetworks	Define if networks marked as testnet should be available in DAPP or not.	true or false	false

Web3

Requirements:
Follow those steps:

• Follow the mandatory RealtProvider step.
  
• Add modals modules: Modal module
• Add the Web3Providers provider
  
  

Web3 connection is handled internaly by @web3-react package. Connections are handled by "connectors. You can check the connectors list here (‼️ not every connectors are compatible).

How does is works ?

When we developed the library, we tried to make it as modular as possible. That's why the connectors must be instantiated in a certain way.

When you have created you Web3Providers provider, you should have given a libraryConnectors object. This object is teh key to connect your Dapp with the web3. You can instantiate a libraryConnectors object like this:

import { getConnectors } from '@realtoken/realt-commons';
const libraryConnectors = getConnectors({});

IT'S MANDATORY to instantiate libraryConnectors outside any react components to avoid re-rendering. Check example website.

Web3 networks (chain)

There is two different type of network in the library: mainnet and testnet. You can add both of them.

Defaults chains

There are

Custom chain

Available connectors in library

You can check here which connector is compatible with the library.

Metamask

Gnosis Safe

Wallet Connect V2

Read Only

Frame (coming soon)

Providers

Some providers are need to use library modules.

Web3 provider (Web3Providers)

The provider is needed when you want to deal with web3 connection. you can create one by wrapping your app like this:

import { Web3Providers } from '@realtoken/realt-commons';
<Web3Providers libraryConnectors={libraryConnectors}>
  ... Other app components
</Web3Providers>

‼️ Provider will not work after this, you need to configure libraryConnectors details, by checking web3 setup.

MantineProviders

Requirements:
Follow the mandatory RealtProvider step.

MantineProviders is a key component (a provider) when you want to use built-in components, create new one, customize theme or manage modals.

First import the MantineProviders component from library, the wrap your application under RealtProvider:

import { MantineProviders, RealtProvider } from '@realtoken/realt-commons';
<RealtProvider>
  <MantineProviders>
    ... your app component
  </MantineProviders>
</RealtProvider>

Translation

Modules

Layout and built-in components

This library provides a buch of components that you can use to create interfaces.

Customizing theme

look at MantineProvider doc part

Modals

This package internaly use @mantine/modals (DON'T INSTALL IT, IT'S ALREADY INSTALLED) to handles modals that are needed by others modules/components.

Add provider

Follow the MantineProviders step to needed provider.

Create new modals

Modals are created following the mantine @mantine/modals documentation:

import { ContextModalProps, modals } from "@mantine/modals"
import { FC } from "react"

interface MyTestModalProps{
  // You can put here variables you want to pass to your modals when you call it  
}
export const MyTestModal: FC<ContextModalProps<MyTestModalProps>> = () => {
    return(
        <>
            {'test'}
        </>
    )
}

After you need to pass them to the library, for that you can create a typescript (.ts) file, then import your modals:

export const modals: Record<string,FC<ContextModalProps<any>>> = {
  testModal: MyTestModal
};

Then give your object to MantineProviders provider:

<MantineProviders modals={modals}>
  ...Other components
</MantineProviders>

Use my custom modals

To use your custom modals, you first need to import modals object from @mantine/modals package then open a context modals. Here is a example code:

import { modals } from "@mantine/modals";

export const MyTestComponent = () => {
  return(
    <button
      onClick={() => modals.openContextModal({
        title:  'My Test modal',
        modal: 'testModal', // the key you put in your modal object at previous step
        innerProps: {} // if you want to pass variable to your modal
      })}
    >
      {'Open my custom modal'}
    </button>
  )
}

Customize modals theme

Create a modal style typescript file (.ts):

export const modalStyles: ModalProps['styles'] = {
  header: {
    ... css variables
  },
  body: {
    ... css variables
  },
  root: { 
    ... css variables 
  },
  overlay: { 
    ... css variables 
  },
  inner: { 
    ... css variables
  },
  content: {
    ... css variables
  }
};

Then give your object to MantineProviders provider:

<MantineProviders modalStyles={modalStyles}>
  ...Other components
</MantineProviders>

Developer doc

How does the library is structured ?

To build the library and be able to publish it to npm we need to bundle it: create a unique file containing everything (components, hooks, utils, etc...).
Tools used to bundle are called bundlers and there are a lot. We decided to used rollup through vite.js library mode.

How to build the package ?

# With yan
npm run build

# With npm
yarn build

Now you will have a dist folder in your root folder, containing bundled files:

• realt-commons.js -> bundle file in common js format.
• realt-commons.umd.js -> bundle file in umd format.

and declarations files (*.d.ts).

How to use package localy ?

Maybe you want to use this package localy. For this:

# NPM
npm i 'PATH_TO_PACKAGE'

# YARN
yarn add 'PATH_TO_PACKAGE'

For example, in example website we used:

yarn add ../../packages/realt-commons

Handle translation

(checker ) MantineProviders

Contributing