Complete template for REACT SPA (2021)

INDEX

• Startup

• Store

• CRA

• AJAX

• I18N

• MOCK

• ROUTING

• UI COMPONENTS

• URL

• AUTH

• TECNOLOGY

• github

• codesandbox
  (in some cases MSW in sandbox does not work. Try open in new window)
  

STARTUP

This TEMPLATE allows you to derive a project in a fast and clean way.
You have full control of the code as it is a classic CRA.
Many typical management problems are solved in the template
and it can be a good way to learn.

clone:
git clone https://github.com/priolo/jon-template.git
enter:
cd jon-template
install npm modules:
npm install
install MSW
npx msw init public/ --save
run:
npm run start

The template is based on a library for managing the STORE in REACT:
Jon
and the concepts solved are:

STORE

When you use REACT for medium-large projects the first urgency is:

Separate the VIEW from the BUSINESS LOGIC
There are libraries for this! The most famous isREDUX
But, in my opinion, it is too long-winded and cumbersome.
So I started using the native REACT methodsREDUCER andPROVIDERS
Eventually I ended up with a VERY VERY light bookcase inspired byVUEX!
Jon
Check it out!

CRA

There isn't much to say! If you want to make an app in REACT it is better to useCRA
You just don't have to managebabel andwebpack:
The APP will have a pre-established and reproducible setup.

DIRECTORY

The structure in the file system of the TEMPLATE:

components

it contains everything that is not a PAGE or DIALOG.
In general: conceptually "reusable" components.

hooks

Specifichooks used in the APP.

locales

The translation json fori18n

mock

• ajax/handlersthe functions for mock responses to HTTP requests
• datathe mock data to be used instead of the DB

pages

REACT components that rendering the "body" of the layout.
You intuitively start from the page, which is unique,
then go to the component that (theoretically) is used in several places.

plugin

They are services accessible at any point in the program. They allow you to access an external service, translate, make calculations etc etc

stores

They are the CONTROLLERs of the VIEWs.
The STORE is not the perfect solution but it works well in most cases!

BUSINESS LOGIC simply has to modify or read the STORE
without worrying about how VIEW is implemented.

It is ESSENTIAL for large projects because it allows you to:

• distribute the code on several units, improving maintainability
• clearly separates the VIEW from the BUSINESS LOGIC
• you can modify the VIEW or the CONTROLLER (keeping the same BINDs) independently

Maintaining the APP after years or by several people is something to be expected.
Impossible if you have a tree of components that pass functions and properties to you making them highly context dependent.

Using the STOREs I can copy and paste a component to another point of the APP without problems.
componentsSHOULD HAVE NO PROPS
The componentsNOT HAVE PROPS (with the exception, of course, of "children" or "className").

Models and API

In reality in this TEMPLATE the APIs and the STOREs are "mixed"!
Aquestionable solution but given the simplicity of the API I didn't want to complicate the structure.
One could think of a "Models" folder for managing POCO objects
and "API" for HTTP requests.

AJAX

Being a SPA, all data arrives via AJAX.
I built a very simple classhere.
I wanted a default SINGLETON SERVICE that could keep some properties (for examplebaseUrl)
But if necessary, since it is aclass, several instances can be created.

I can use STORE even outside REACT (and therefore in SERVICE AJAX)

For example, here I set the STATEbusy of the STORElayout when the SERVICE is busy:
in SERVICE (outside REACT)

// I download the "layout" storeconst{setBusy}=getStoreLayout()// if necessary set "busy" == truesetBusy(true)

While in theSTORE layout

// I define the `busy` prop in readable / writableexportdefault{state:{busy:false,}.mutators:{setBusy:(state,busy)=>({busy}),}}

In VIEW
I can catch this event

functionHeader(){const{state:layout}=useLayout()return(<AppBar>{// In this case the "progress" is displayed if the SERVICE AYAX is busylayout.busy&&<LinearProgress/>}</AppBar>)}

I18N

Sooner or later you will have to use it .... so better think about it first!
It's not just for "translating" the app
It allows you not to have the content directly in the VIEW ... which is more beautiful !!!
It is useful for testing in Cypress: you can use the translation PATH to locate components
instead of the text (which may change).

Inside a REACT COMPONENT
use the HOOK to import thet translation function

import{useTranslation}from'react-i18next'...const{t}=useTranslation()

Translate via PATH

<TableCell>{t("pag.user.tbl.username")}</TableCell>

Or, outside of a COMPONENT, use thePLUGINi18n

importi18nfrom"i18next"...consttitle=i18n.t("pag.default.dlg.router_confirm.title")

The translations are inside JSON files in thesrc\locales directory

doc

MOCK (MSW)

The APP must work offline! Of course withmock data

This allows to divide the tasks of those who do the FE and those who do the BE:
It is enough to share good documentation on the API (which must be done anyway)
You don't need the whole environment to develop.
It is also immediately "testable" (for example by Cypress).
Finally, the APP in mock can be presented as a demo to the CUSTOMER without "unexpected behavior" (= "panic")
Too many benefits!

I have configured and startedMSW in/plugins/msw.js
It is calledhere starting aService Worker

AService Worker acts as a proxy between the APP and the WEB: "simulating" low-level network.
This is cool because it is completely transparent to the APP:
basically when you usefetch it still works ... even offline! The data is given to you by theService Worker

Inmocks/ajax/handlers there are simulated "CONTROLLERs"
Inmocks/data there are ... the data! Used to emulate the DB

The APP starts theService Worker if it is indevelopment or theREACT_APP_MOCK environment variable is" true "(string!)

Environment variables in CRA are documentedhere
However CRA (at compile time) takes from.env all variables that starting withREACT_APP
and makes them available in the browser

Example: To "simulate" the response to the request of adoc object by itsid

HTTP request:
GET /api/docs/33

taken from:src/mocks/ajax/handlers/docs.js

import{rest}from"msw"importlistfrom"../../data/docs"rest.get('/api/docs/:id',(req,res,ctx)=>{constid=req.params.idconstdoc=list.find(item=>item.id==id)if(!doc)returnres(ctx.status(404))returnres(ctx.delay(500),ctx.status(200),ctx.json(doc))}),

ROUTING

Also in this case it is easy to choose:reactrouter

CONDITIONAL RENDER based on the current browser URL?

UseSwitch by specifying one or morepaths

/* ATTENTION: the order is important */<Switch><Routepath={["/docs/:id"]}><DocDetail/></Route><Routepath={["/docs"]}><DocList/></Route><Routepath={["/","/users"]}><UserList/></Route></Switch>

CHANGE THE PAGE in REACT?

Use theuseHistory HOOK:
src\components\app\Avatar.jsx

import{useHistory}from"react-router-dom";exportdefaultfunctionAvatar(){consthistory=useHistory()consthandleClickProfile=e=>history.push("/profile")return...}

CHANGE PAGE outside REACT?

Use the browser's nativehistory

window.history.push("/docs/33")

Access the URL PARAMETERS?

Use theuseParams HOOK.
src\pages\doc\DocDetail.jsx

import{useParams}from"react-router"exportdefaultfunctionDocDetail(){const{id}=useParams()useEffect(()=>{if(!id)fetchById(id)},[id])return...}

Confirm ON CHANGE

An example can also be found on thereact-router-dom websitehere, I report it for completeness.

I created a custom hookuseConfirmationRouter

that simply blocks navigation and asks for confirmation to continue.

I use it in the detail of the DOChere

WARNING
Being the TEMPLATE aSPA:

• On URL change it does not make any HTTP requests to the server but simply updates the rendering
• Of course, the data is always retrieved via AJAX requests
• The only requests "about the APP structure" is the first loading or reload of the page.
• The SERVER must be set appropriately to always reply with the same page

P.S.:
Are you like me? Is installing a plugin always a doubt? What if this library doesn't do what I need? What if it becomes obsolete the day after putting it into production? What if the author vows to God never to touch a pc again? What if I notice that there is an unsolvable BUG in the library? And then ... do you want to have full control of the software ??
So ... this plugin could be replaced by managing the url with the STORE.
But I will not cover the subject here :D

LAZY IMPORT

It is very very simple! If we have to create a portal with many pages
Even if werender only one page at a time

with the classicimport we load ALL COMPONENTs! Even the ones the user will never see!
To load COMPONENTs only if necessary you need to use anative REACT function:React.lazy

I do it in theMainhere

constDocDetail=lazy(()=>import('../../pages/doc/DocDetail'))exportdefaultfunctionMain(){return(<Switch><Routepath={["/docs/:id"]}><Suspensefallback={<div>LOADING...</div>}><DocDetail/></Suspense></Route>            ...</Switch>)}

Suspense is also anative REACT component.
Allows you to view an alternate render while the component is loading.

UI COMPONENTS

Of course you can make your own components (it doesn't take much)
butMaterial-UI is very used and solid!
Nothing else is needed!

BINDING

First thing: link the STORE to the VIEW.
RememberuseState BUT, instead of being in the COMPONENT REACT, it's in the STORE.

We define a STORE with avalue in read / write

exportdefault{state:{value:"init value",},mutators:{setValue:(state,value)=>({value}),},}

I import the STORE and "binding" of itsvalue in the COMPONENT REACT

import{useStore}from"@priolo/jon"exportdefaultfunctionForm(){const{state,setValue,getUppercase}=useStore("myStore")return<TextFieldvalue={state.value}onChange={e=>setValue(e.target.value)}/>}

Asandbox (that does NOT use MATERIAL-UI)
To find out more, check outJon

However, in this TEMPLATE you can find the BINDINGSeverywhere

VALIDATOR

Form validation is always left for last 😄
There is a simple mechanism for validating Material-UI components.

Just connect a value to arule (with a HOOK)
and assign the obtainedprops to the MATERIAL-UI component

import{rules,useValidator}from"@priolo/jon";functionForm(){const{state:user,setSelectName}=useAccount()// I create a custom "rule". If there is a violation I return a string with the errorconstcustomRule=(value)=>value?.length>=3?null:"Enter at least 3 letters."// I link two "rules" with the STORE ACCOUNT property "user.select?.name"constnameProps=useValidator(user.select?.name,[rules.obligatory,customRule])// ... and I get "nameProps"return<TextFieldautoFocusfullWidth// report an error if the value does not meet one of the rules{...nameProps}value={user.select?.name}onChange={e=>setSelectName(e.target.value)}/>}

And validate in the STORE before sending the data

import{validateAll}from"@priolo/jon"conststore={state:{select:{name:""},},actions:{save:async(state,_,store)=>{// check if there is an error in the displayed "rules"consterrs=validateAll()// if there are errors I can view them ... or ignore them :)if(errs.length>0)returnfalse// else ... save!},},mutators:{setSelectName:(state,name)=>({select:{...state.select,name}}),},}

an examplehere

DYNAMIC THEME

Once you understand how the STORES work, you use them for everything
... of course also to manage the THEME

In theSTORElayout I put everything that characterizes the general appearance of the APP
The THEME of MATERIAL-UI
but also the title on the AppBar, if the APP is waiting (loading ...), if the side DRAWERS are open, the main menu, the "message box", where the focus is set etc etc

However the THEME settings must be kept even whenreload the page
The problem is that in this case the browser makes a new request to the server and theSTORE is reloaded from scratch!
So I used thecoockies to store the name of the selected THEME
you can see ithere

The store theme is initially set with the cookie
and when the THEME is changed. (here)

exportdefault{state:{theme:Cookies.get('theme'),},mutators:{setTheme:(state,theme)=>{Cookies.set("theme",theme)return{theme}},}}

Even if you use the cookies to memorize the name of the THEME
however, it is necessary to modify the STORE variable (more correctly "the STATE of the store")
Otherwise the VIEW does not receive the event!
In general the VIEW updates ONLY IF thestate object of the STORE changes

Responsive Design

There are tools in MATERIAL-UI for thishere
But what if we don't use MATERIAL-UI?

We can use the STORE! I initialize the STORE by hooking it to the window resize event

conststore={state:{device:null,},// chiamato UNA SOLA VOLTA per inizializzare lo storeinit:(store)=>{constcheckDevice=()=>{constdeviceName=window.innerWidth<767?"mobile":window.innerWidth<950?"pad":"desktop"store.setDevice(deviceName)}window.addEventListener("resize",(e)=>checkDevice());checkDevice()},mutators:{setDevice:(state,device)=>({device}),},}

And I use it to modify the VIEW based on the device

functionMainDrawer(){const{state:layout}=useLayout()constvariant=layout.device=="desktop"?"persistent":nullreturn(<Drawervariant={variant}...>...</Drawer>)}

Of course you can also use it for: classes and style css or conditional render

URL

SEARCH AND FILTER

If I use a WEB APP and I copy the URL and send it to a friend

I expect him to see exactly what I see (with the same permissions of course)
Then the selected TABs, filters and sorting on the lists.

They must be kept in thesearch of the current URL (also calledquery string)
... in short, what is after the "?" in the URL

In STORERoute I can get or set a variable ofquery string which can be used in VIEW

An excerpt from the STORE:

exportdefault{state:{queryUrl:"",},getters:{getSearchUrl:(state,name,store)=>{constsearchParams=newURLSearchParams(window.location.search)return(searchParams.get(name)??"")},},mutators:{setSearchUrl:(state,{name,value})=>{constqueryParams=newURLSearchParams(window.location.search)if(value&&value.toString().length>0){queryParams.set(name,value)}else{queryParams.delete(name)}window.history.replaceState(null,null,"?"+queryParams.toString())return{queryUrl:queryParams.toString()}},},}

then I use it in thelist to filter the elements

functionDocList(){const{state:route,getSearchUrl}=useRoute()const{state:doc}=useDoc()// it is executed only if the filter or the "docs" changesconstdocs=useMemo(// actually I do this in the STORE DOC()=>{// I get the "search" value in the current urllettxt=getSearchUrl("search").trim().toLowerCase()// I filter all the "docs" and return themreturndoc.all.filter(doc=>!txt||doc.title.toLowerCase().indexOf(txt)!=-1)},[doc.all,route.queryUrl])// render of docsreturn{docs.map(doc=>(...))}}

meanwhile in theHEADER I have the text-box to modify the filter

import{useRoute}from"../../stores/route"functionHeader(){const{getSearchUrl,setSearchUrl}=useRoute()return(<SearchBoxvalue={getSearchUrl("search")}onChange={value=>setSearchUrl({name:"search",value})}/>)}

To recap: With theSearchBox I change the url
linked (via the store STOREroute) to the VIEWDocList

and then this updates the list.
If I were to duplicate the page in the browser the filter would remain intact.

AUTH

The AUTH is not complete (a matter of time ... I'll finish it)!

It is managed by the STOREauthhere

JWT (JSON Web Token)

How does it work?

This is atoken (ie an "identifier string") that the server gives to the client when the client logs in successfully.

At this point the client at each subsequent request no longer has to authenticate,
but it just puts thetoken in theHEADER of the HTTPS request.

Or the server puts thetoken in anHttpOnly COOKIE, and will find it on every request.
In this case javascript will not be able to access thetoken(more secure)

The server seeing the correcttoken and assumes that that HTTP request was made by someone who has already passed authentication.

User data is directly in thetoken (including permissions): there is no need to query the db
Thetoken have an "expiration" forcing the client to re-authenticate to generate a newtoken.
Of course you have to use an HTTPS connection to be safe.

Assuming you want to implement the token in the HEADER:
The ajax plugin includes thetoken if availablehere

import{getStoreAuth}from"../stores/auth"...exportclassAjaxService{...asyncsend(url,method,data){const{state:auth}=getStoreAuth()...constresponse=awaitfetch(url,{method:method,headers:{"Content-Type":"application/json",...auth.token&&{"Authorization":auth.token}},body:data,})...}...}

The token is accessible in theSTORE auth.
I used cookies to avoid having to login again on "reload"(it does not work with MSW)

Cookies should only be used with HTTPS

importCookiesfrom'js-cookie'exportdefault{state:{token:Cookies.get('token'),},getters:{isLogged:state=>state.token!=null,},mutators:{setToken:(state,token,store)=>{if(token==null){Cookies.remove('token')}else{Cookies.set('token',token)}return{token}},}}

TECNOLOGY

Template di uno stack tecnologico
per realizzare un Front End SPA

MANAGE PROJECT

CRA

VIEW LIBRARY

React

STORE

Jon

COMPONENTS

Material-UI

ROUTER

reactrouter

INTERNAZIONALIZZATION

react-i18next

MOCK

msw

TEST

Cycpress