@tao.js/react

Adapter to use tao.js with React

See the tao.js website Usage with React.js for more information or the issues associated with this package.

Install

Using npm:

npm install --save @tao.js/react

or using yarn:

yarn add @tao.js/react

NOTE: @tao.js/core is a peer dependency

Importing

The package provides 3 different ways to import based upon how it's being used.

All @tao.js packages use the following pattern to provide keys in package.json telling Node and bundlers where to find the packages distributed code:

• module - provides a ES Module version of the package (in the dist folder)
• main - provides a CommonJS version of the package (in the lib folder)
• bundles - provides keys for any UMD bundles of the package (in the bundles folder)
  • currently there is no bundler using this pattern but now you know where to find it

Why NO browser key in package.json

The current pattern for packaging bundles meant for browser import is to provide a browser key in package.json. This should be the way to go but unfortunately doing this doesn't provide control to you in certain situations.

For instance, in Webpack 4, which is used by create-react-app, the default configuration is to prefer the browser bundle when packaging a build intended for a browser. Unless you are controlling this configuration in your create-react-app (and most don't) then the build process will use the UMD bundle and not be able to leverage tree-shaking if you only import and use parts of the package library.

In this circumstance, even if you do what you think is correct and:

import { Provider } from '@tao.js/react';

in your file, because webpack is using the UMD bundle, it will import the whole UMD bundle and make that part of your output.

Current vs Original API

The @tao.js/react package has recently had a complete update to its API (now called the current API) while keeping its original API. This has been done because consumers of the package may want to use the simplified original API which has only 2 exports.

The Current API is provides a more React-like developer experience and is geared towards React 16 using the Context API.

Because of this, @tao.js/react builds 3 different versions of bundles for CommonJS and UMD for the current, original and all (both).

ES Module

If you are using import statements to import @tao.js/react then package.json identifies a module key to tell Node or your bundler of choice where to find the version packaged as ES Modules (the dist folder).

When using ES Modules, there is no default export, so anything imported from @tao.js/react must be a named import, e.g.:

import { Provider } from '@tao.js/react';

Because ES Modules rely on static import and export statements, they are designed for tree-shaking, so there is only one bundle built for @tao.js/react with the entire API (current and original), assuming whatever bundler is being used can tree-shake out whatever is not used.

This is the recommended way to import the package and most modern builders & bundlers can handle it

CommonJS

If you are using require statements and not a bundler that understands ES Modules, the package.json identifies the main key to tell Node or your bundler where to find the version packaged as a CommonJS module (the lib folder).

When using CommonJS, there is no default exports, so anything imported from @tao.js/react must be used by its key, e.g.:

const { Provider } = require('@tao.js/react');

// OR
const Provider = require('@tao.js/react').Provider;

// OR
const TaoReact = require('@tao.js/react');
TaoReact.Provider;

Current API

The importing above refers to importing the Current API only and will not have any of the original API components/exports available.

Original API

In the CommonJS build, because CommonJS is not designed to aid tree-shaking, the Original API[https://tao.js.org/client-react/orig-api/] is not included in the default package build for CommongJS found in the lib folder and pointed to by package.json's main key.

If you want to make use of the Original API[https://tao.js.org/client-react/orig-api/] then you must import from @tao.js/lib/orig, e.g.:

import { Adapter } from '@tao.js/lib/orig';

// OR
const { Adapter } = require('@tao.js/lib/orig');

UMD Bundles

If you are not using a bundler to build your web application or just want to use a full bundled version of the package by importing directly into a <script> tag then you will find the bundles in the bundles folder (also identified in the bundles key in package.json).

• bundles/browser.umd.js - this is the current API bundled without the original API as global tao.react
• bundles/orig.umd.js - this is the original API bundled without the current API as global tao.react.orig
• bundles/all.umd.js - this is both the current & original API bundled together as global tao.react.all

tao.react.Provider

// OR
<tao.react.Provider TAO={tao.TAO}>
  …
</tao.react.Provider>

// OR
tao.react.orig.Adapter

// OR
tao.react.all.Adapter

In the future, this will be published to a CDN for convenience.

All Packages in the @tao.js family

package	description	docs page
npm @tao.js/core	Core Javascript implementation of the TAO ☯ programming paradigm	tao.js.org
npm @tao.js/utils	Extensions to Core used to build out the Signal Network	tao.js Utilities for Implementers
npm @tao.js/react	Adapter to use tao.js with React	Usage with React.js
npm @tao.js/socket.io	socket.io middleware to run tao.js seamlessly on server & client	tao.js for Socket.io
npm @tao.js/koa	Expose a TAO signal network over http using a koa app server	tao.js for Koa
npm @tao.js/router	connects url routing with tao.js	URL Handling with @tao.js/router