Quick Start

Installation#

Install overreact using yarn or npm:

npm install @microsoft/overreact

Setup your app#

In this guide, we're going to build an app that talks with the infamous TripPin service, which exposes a typical OData endpoint at https://services.odata.org/v4/TripPinServiceRW

Configure your network requestor#

overreact doesn't explicitly use any specific API to issue network requests ($.ajax, fetch, etc.), instead, it allows you to customize how your application wants to make requests to the network. In our app, we'll go with the fetch API.

network-requestor.js

export function networkRequestor(uri, requestVerb, headers, body) {    const endpoint = 'https://services.odata.org/v4/TripPinServiceRW';    const requestUrl = `${endpoint}${uri}`;
    return fetch(requestUrl, {        method: requestVerb,        headers,        body: JSON.stringify(body),    }).then(response => response.json());}

Configure a schema#

A schema describes what entities are available and what name (alias) your app should call those entities internally.

schema.js

import { Schema } from '@microsoft/overreact';
const schemaToModelMapping = {    people: 'People',    trip: 'Trip',    airline: 'Airline',    // more entities go here ...};
export const schema = new Schema(schemaToModelMapping, () => {});

Initialize a DataFetcher#

Now let's initalize overreact to run in your app. To do that, simply put a DataFetcher component in your app, and have it wrap all UI components that requires data operations:

app.js

import React from 'react';import {     DataFetcher,    Environment,    Store,} from '@microsoft/overreact';
// Previously defined schema and network requestorimport { networkRequestor } from './network-requestor';import { schema } from './schema';
// React component that will talk to the TripPin serviceimport { PeopleContainer } from './people-container';
export default function App() {    // define an Environment object to configure overreact    const store = new Store();    const tripPinEnvironment = new Environment(networkRequestor, schema, store, []);
    return (        <div className="app-container">            <DataFetcher environment={tripPinEnvironment}>                <PeopleContainer userName="russellwhyte" />            </DataFetcher>        </div>    );}

Now that overreact has now been initialized, we need to tell overreact how to construct actual network requests for different entities, and how to store them locally.

Create data specs#

In our app, we'll look for a specific People entity, whose name is "russellwhyte", from the TripPin service. To do that, let's create a data spec for People. This spec allows overreact to issue a HTTP GET call, like this:

GET https://services.odata.org/v4/TripPinServiceRW/People('russellwhyte') HTTP/1.1

people-spec.js

import {    createRequestContract,    createResponseContract,    createSpec,
    requestVerbs,    responseTypes,    specTypes,} from '@microsoft/overreact';
import { schema } from './schema';
function odataUriFactory(params) {    const { variables } = params;    const { locator } = variables;    const { descriptor, order } = locator;    const { people } = descriptor;
    return `/People('${people}')`;}
const odataHeaderFactory = () => {};
const requestContract = createRequestContract({    schema,    dataPath: 'people',    verb: requestVerbs.GET,    uriFactoryFn: odataUriFactory,    headerFactoryFn: odataHeaderFactory,    keySelector: p => p.UserName,});
const responseContract = createResponseContract({    requestContract: requestContract,    responseType: responseTypes.ENTITY,    keySelector: p => p.UserName,});
export const peopleSpec =     createSpec(requestContract, responseContract, specTypes.FETCH, null);

Finally, let's construct a React component that consumes the data.

Create your first overreact UI component#

By now, we have all the required pieces ready to make the actual network call. Let's assume our app contains two text field, showing a user's name and address from the TripPin service.

We begin by issuing the call using the useFetch hook from overreact.

people-container.js

import React, { useMemo } from 'react';import {     useFetch,    useDataRefId,} from '@microsoft/overreact';
import { peopleSpec } from './people-spec';import { PeopleView } from './people-view';
export function PeopleContainer(props) {    const { userName } = props;    const dataRefId = useDataRefId();
    const variables = useMemo(() => ({        locator: {            descriptor: { people: userName },            order: ['people'],        },    }), [userName]);
    const [data] = useFetch(dataRefId, peopleSpec, variables);
    return (data ? <PeopleView         firstName={data.FirstName}        lastName={data.LastName}        address={data.AddressInfo[0]}    /> ? null);}

people-view.js

import React from 'react';
export function PeopleView(props) {    const { firstName, lastName, address } = props;    const { Address } = address;
    return (        <div className="people-view">            <span>{`${firstName} ${lastName}`}</span>            <span>{Address}</span>        </div>    );}

That's it! Run your app and you should see a network request going out to https://services.odata.org/v4/(S(wzb13shf21muw3is3clriogh))/TripPinServiceRW/People('russellwhyte') (the actual URL listening to the requests), and the response should be rendered on the page.

What's Next?#

overreact does more than just fetching data from network. It also provides rich support for the following scenarios:

You can click on each topic to learn more details. Additionally, please go to Data Structure section to learn about how overreact stores data internally.