react-backend - npm Package Compare versions

Comparing version 1.0.3 to 1.0.4

src/samples/package.json

+{
+  "name": "react-backend-samples",
+  "version": "1.0.4",
+  "description": "Samples for react-backend",
+  "main": "index.js",
+  "scripts": {
+    "build-samples": "webpack --config config/webpack.config.js --progress --profile --colors",
+    "start-samples": "node ../../dist/server.js"
+  },
+  "keywords": [
+    "react",
+    "data",
+    "dataprovider",
+    "serverside"
+  ],
+  "author": "Jean-Michel Meyer, by Hextrakt",
+  "license": "MIT",
+  "dependencies": {
+    "react": "^16.2.0",
+    "react-backend": "^1.0.3",
+    "react-dom": "^16.2.0",
+    "react-helmet": "^5.2.0",
+    "react-router-dom": "^4.2.2"
+  },
+  "devDependencies": {
+    "babel-cli": "^6.26.0",
+    "babel-core": "^6.26.0",
+    "babel-loader": "^7.1.2",
+    "babel-plugin-transform-es3-member-expression-literals": "^6.22.0",
+    "babel-plugin-transform-es3-property-literals": "^6.22.0",
+    "babel-preset-es2015": "^6.24.1",
+    "babel-preset-react": "^6.24.1",
+    "babel-preset-stage-2": "^6.24.1",
+    "babel-register": "^6.26.0",
+    "body-parser": "^1.18.2",
+    "express": "^4.16.2",
+    "mocha": "^5.0.0",
+    "nocache": "^2.0.0",
+    "restful.js": "^0.9.6",
+    "webpack": "^3.10.0",
+    "webpack-dev-middleware": "^2.0.4",
+    "webpack-hot-middleware": "^2.21.0",
+    "webpack-hot-server-middleware": "^0.3.2",
+    "whatwg-fetch": "^2.0.3"
+  }
+}

package.json

 {
   "name": "react-backend",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "A framework which help fetch data from backends and provide them to React.js components.",
@@ -8,4 +8,2 @@ "main": "index.js",
     "build": "babel src --ignore src/config,src/samples,src/test  --out-dir .",
-    "build-samples": "webpack --config src/samples/config/webpack.config.js --progress --profile --colors",
-    "start-samples": "node dist/server.js",
     "test": "set NODE_ENV=development && mocha --no-deprecation --recursive --require babel-register src/test"
@@ -39,6 +37,4 @@ },
     "express": "^4.16.2",
-    "lowdb": "^1.0.0",
     "mocha": "^5.0.0",
     "nocache": "^2.0.0",
-    "restful.js": "^0.9.6",
     "sinon": "^4.3.0",
@@ -45,0 +41,0 @@ "unit.js": "^2.0.0",

README.md

 # react-backend
-A framework which help fetch data from backends and provide them to React.js components.
+A framework which help fetch data from backends and provide them to 
+[React](https://reactjs.org/) components.
 
-Documentation will come before end of February 2018...
+## Motivations
+
+React.js doesnt' provide any core feature to interface with a database back-end 
+nor with a REST API. We wanted a simple (and beautiful) solution, and didnt' want to learn a new language such as [GraphQL/Relay](https://facebook.github.io/relay/).  
+[Redux](https://redux.js.org/) provides the frame to manage UI state, and respond to user actions, but doesn't help on the server side, where initial state is immutable.
+So we built this framework to :
+* be able to render a complete DOM tree at the server side
+* be able to specify which data are needed at each application path
+* write code in a declarative way, in a "react-like" way, leveraging React Router API v4
+* provide data at the server side as well as at the client side
+* provide preloaded data (in a javascript variable) to initialize client side components
+
+## Requirements
+
+There is no specific requirement to use this framework. It is written in ES6, but the package is translated using Babel into plain javascript so that everybody might "require" it. You just need to use React Router API v4.
+
+## Installation
+
+To use the framework
+```js
+yarn add react-backend 
+```
+or 
+```js
+npm install react-backend
+```
+
+To test it, first clone the [Git repository](https://github.com/Hextrakt/react-backend). Then, run
+
+```js
+yarn install
+yarn build
+yarn test
+```
+
+To run the samples, do the three steps above, then
+```js
+cd src/samples
+yarn install
+yarn build-samples
+yarn start-samples
+```
+and navigate to [http://localhost:3000](http://localhost:3000)
+
+## Features and usage
+
+Use the `NeedsData` component to **declare the application data needs**.
+Example 1. Tell that *getUserInfo* is needed when navigating to `/user` :
+
+```jsx
+<Route path='/user' render={() => (
+  <NeedsData needs="getUserInfo"/>
+  )}/>
+</Route>
+```
+
+Data **needs are additive**.
+Example 2. Tell that both "getUserInfo" and "getUserProfile" are needed when navigating to `/user/profile`:
+```jsx
+<Route path='/user' render={() => (
+  <NeedsData needs="getUserInfo">
+)}/>
+<Route path='/user/profile' render={() => (
+  <NeedsData needs="getUserProfile"/>
+)}/>
+```
+
+Data needs **can be nested**.
+Example 3. This is the same as example 2, but written in a nested way:
+
+```jsx
+<Route path='/user' render={() => (
+  <NeedsData needs="getUserInfo">
+    <Route path='/user/profile' render={() => (
+      <NeedsData needs="getUserProfile"/>
+    )}/>
+  </NeedsData>
+  )}/>
+</Route>
+```
+
+Write a `DataProvider` class to **resolve the needs** into Promise objects.
+Your DataProvider might fetch data from the session, from the database, or from
+REST services.
+
+```js
+class MyDataProvider extends DataProvider {
+  getUserInfo() {
+    return database.loadUserInfo(userId) // should return a Promise
+  }
+  getUserProfile() {
+    return database.loadUserProfile(userId) // should return a Promise
+  }
+}
+```
+
+You can have a different DataProvider at the server side (to load data from database) and at the client side (to load data from REST services).
+
+You can **declare dependencies** between your data using the `DataProvider.when()` function. For instance, if *getUserInfo* needs the session user id, you can write this in your DataProvider class:
+
+```js
+getUserInfo() {
+  return when("getUserId").then(id => return database.loadUserInfo(id))
+}
+getUserId() {
+  return Promise.resolve(session.getCurrentUserId()) // depending on your session implementation
+}
+```
+
+Needs are **resolved once** and cached. If several needs share the same base need, the shared need will be loaded only one time. Use the `DataProvider.invalidate(someNeed)` function to tell the dataprovider that *someNeed* should be **reloaded at the next UI refresh**.
+
+Wrap all your data needs with a `ProviderRules` component, and give it the dataProvider instance:
+
+```jsx
+<ProviderRules dataProvider={myDataProvider}>
+  <Route path='/user' render={() => (
+    <NeedsData needs="getUserInfo"/>
+  )}/>
+</ProviderRules>
+```
+
+The ProviderRules component will be responsible to collect all the data needs which are declared in its subtree.
+
+Place all your **presentational components** within a `WithData` component. This will have two benefits:
+
+* First, your presentation will not be rendered until the data needs are resolved
+* Secondly, you can access the dataProvider instance, either from the React context or from the *dataProvider* prop when using the `withDataProvider` [HOC](https://reactjs.org/docs/higher-order-components.html).
+
+Use either `DataProvider.getData()`, `DataProvider.getError()`, `DataProvider.hasErrors()` within your presentational componenents to access the resolved data or errors.
+
+```jsx
+<WithData dataProvider={dataProvider}>
+  <UserForm/>
+</WithData>
+```
+
+```js
+class _UserForm extends React.Component {
+  render() {
+    const {dataProvider} = this.props
+    if (!dataProvider.hasErrors()) {
+      const userInfo = dataProvider.getData("getUserInfo")
+      // add here your rendering logic
+    }
+    else if (dataProvider.getError("getUserInfo")) {
+      // show specific error
+    }
+  }
+}
+const UserForm = withDataProvider(_UserForm)
+```
+
+In order to **render the complete DOM tree at the server side**, you can use the `ServerRenderer` class, this way:
+
+```jsx
+const context = {}
+const myDataProvider = new MyDataProvider()
+
+new ServerRenderer(serverProvider, 
+  (<StaticRouter location={ req.url } context={ context }>
+    <Fragment>
+      <ProviderRules dataProvider={myDataProvider}>
+        <DataNeeds/>
+      </ProviderRules>
+      <WithData dataProvider={serverProvider}>
+        <App/>
+      </WithData>  
+    </Fragment>
+  </StaticRouter>)
+)
+.render()
+.then(markup => {
+  let data = serverProvider.values
+  res.status(200).send(Template({data, markup}))
+})
+.catch (function (error) {
+  console.log("There was a problem : ", error)
+})
+```
+
+The `Template` function can look like this (a bit simplified):
+
+```js
+export default ({ data, markup }) => {
+    return `<!doctype html>
+    <html>
+    <head>
+      <script>var data = ${JSON.stringify(data)}</script>
+    </head>
+    <body>
+      <div id="root">${markup}</div>
+      <script src="/js/client.js" async></script>
+    </body>
+    </html>`
+}
+```
+
+## Samples
+
+You can fin all the sample code in the [samples](https://github.com/Hextrakt/react-backend/tree/master/src/samples) 
+directory of the [react-backend git repository](https://github.com/Hextrakt/react-backend).
+
+How to declare your data needs: [DataNeeds.jsx](https://github.com/Hextrakt/react-backend/blob/master/src/samples/common/DataNeeds.jsx)
+Write your server data provider: [ServerDataProvider.js](https://github.com/Hextrakt/react-backend/blob/master/src/samples/server/ServerDataProvider.js)
+Write your client data provider: [ClientDataProvider.js](https://github.com/Hextrakt/react-backend/blob/master/src/samples/client/ClientDataProvider.js)
+Write your react application: [App.jsx](https://github.com/Hextrakt/react-backend/blob/master/src/samples/common/App.jsx)
+Write your client bundle: [Client.jsx](https://github.com/Hextrakt/react-backend/blob/master/src/samples/client/Client.jsx)
+Write your server handler: [Server.jsx](https://github.com/Hextrakt/react-backend/blob/master/src/samples/server/Server.jsx)

src/samples/client/Client.jsx

@@ -5,3 +5,3 @@ import React, { Fragment } from 'react'
 
-import { ProviderRules, WithData } from '../../'
+import { ProviderRules, WithData } from 'react-backend'
 import ClientDataProvider from './ClientDataProvider'
@@ -8,0 +8,0 @@ import DataNeeds from '../common/DataNeeds'

src/samples/client/ClientDataProvider.js

@@ -1,2 +0,2 @@
-import DataProvider from '../../'
+import DataProvider from 'react-backend'
 
@@ -3,0 +3,0 @@ class ClientDataProvider extends DataProvider {

src/samples/common/App.jsx

 import React, { Fragment } from 'react';
 import { Switch, Route, Link } from 'react-router-dom'
 
-import { withDataProvider } from '../../'
+import { withDataProvider } from 'react-backend'
 
@@ -6,0 +6,0 @@ const HomePage = withDataProvider(props => {

src/samples/common/DataNeeds.jsx

 import React, { Fragment } from 'react';
 import { StaticRouter, Switch, Route, Link } from 'react-router-dom'
-import { NeedsData, NoDataNeed } from '../../'
+import { NeedsData, NoDataNeed } from 'react-backend'
 
@@ -5,0 +5,0 @@ function DataNeeds() {

src/samples/server/Server.jsx

@@ -9,5 +9,5 @@ /**
 
-import { ProviderRules, WithData } from '../../'
+import { ProviderRules, WithData } from 'react-backend'
 import ServerDataProvider from './ServerDataProvider'
-import ServerRenderer from '../../ServerRenderer'
+import ServerRenderer from 'react-backend/ServerRenderer'
 
@@ -14,0 +14,0 @@ import DataNeeds from '../common/DataNeeds'

src/samples/server/ServerDataProvider.js

@@ -1,2 +0,2 @@
-import DataProvider from '../../'
+import DataProvider from 'react-backend'
 
@@ -3,0 +3,0 @@ class ServerDataProvider extends DataProvider {

src/nbproject/private/private.properties

-browser=Chrome.INTEGRATED
-server=EXTERNAL

src/nbproject/private/private.xml

-<?xml version="1.0" encoding="UTF-8"?>
-<project-private xmlns="http://www.netbeans.org/ns/project-private/1">
-    <open-files xmlns="http://www.netbeans.org/ns/projectui-open-files/2">
-        <group>
-            <file>file:/C:/Projets/react-backend/src/index.js</file>
-        </group>
-    </open-files>
-</project-private>

src/nbproject/project.properties

-auxiliary.org-netbeans-modules-javascript-nodejs.enabled=true
-auxiliary.org-netbeans-modules-javascript-nodejs.run_2e_enabled=true
-auxiliary.org-netbeans-modules-javascript-nodejs.start_2e_file=index.js
-files.encoding=UTF-8
-run.as=node.js
-source.folder=

src/nbproject/project.xml

-<?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://www.netbeans.org/ns/project/1">
-    <type>org.netbeans.modules.web.clientproject</type>
-    <configuration>
-        <data xmlns="http://www.netbeans.org/ns/clientside-project/1">
-            <name>src</name>
-        </data>
-    </configuration>
-</project>

New alerts

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Fixed alerts

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

343201

66.34%

Dev dependency count

20

-9.09%

Number of lines in readme file

213

4160%

Worsened metrics

Number of package files

42

-4.55%

No dependency changes