:construction: :construction: :construction: THIS PROJECT HAS AN EXPERIMENTAL STATUS, DON'T USE IT :construction: :construction: :construction:

@kode-frontend/pathfinder-web-react

Pathfinder is a tool that allows to substitute the base URL for requests, helping with global error handling, testing, mocking, and more. This package provides a useful UI panel for easy HTTP requests manipulations on the client side.

Installation

npm i @kode-frontend/pathfinder-web-react

# or using yarn
yarn add @kode-frontend/pathfinder-web-react

Pathfinder is intended to be paired with a storage adapter and an OpenAPI resolver, which can be fully customized or installed as npm packages.

We recommend using special libraries for integrating Pathfinder into your application. They are easy to integrate into an existing project and do not require any further development.

Save as dependencies* :

npm i @kode-frontend/pathfinder-web-local-storage @kode-frontend/pathfinder-web-open-api

# or using yarn
yarn add @kode-frontend/pathfinder-web-local-storage @kode-frontend/pathfinder-web-open-api

*You can read more about pathfinder-web-local-storage and pathfinder-web-open-api on their pages.

Introduction

There are cases in which it is useful to monitor or manipulate HTTP requests, instead of letting it happen as is. Pathfinder is a tool that allows to configure the base path for an API on the client side, both for all requests and for each one separately. It provides a UI panel, which enables to interactively change the requests environment in accordance with an uploaded OpenAPI config.

Pathfinder works with the OpenAPI 3.0 Specification, which can be exported from Stoplight.

Features:

• Request interception:
  intercepts requests according to the specified environment and changes base URL.
• Feature toggle for production:
  allows to enable or disable a feature through the developer tools.
• Uploading and updating data from an OpenAPI config:
  updates environment lists and paths on the spot by uploading an OpenAPI config.

Quickstart

Create a new provider component with Pathfinder. Import storage and openApiResolver from the corresponding packages or create custom ones.

Storage is an object that implements Pathfinder data storage
Resolver takes OpenAPI data and converts it to the PathFinder format

import { ReactNode } from 'react';
import { Pathfinder } from '@kode-frontend/pathfinder-web-react';
import { storage } from '@kode-frontend/pathfinder-web-local-storage';
import { openApiResolver } from '@kode-frontend/pathfinder-web-open-api';

type Props = {
  children: ReactNode,
};

export const PathfinderProvider = ({ children }: Props) => {
  return (
    <Pathfinder
      storage={storage}
      resolver={openApiResolver}
      active={process.env.NODE_ENV !== 'production'}
    >
      {children}
    </Pathfinder>
  );
};

Create PathfinderProvider, for example

import * as React from 'react';
import { Pathfinder } from '@kode-frontend/pathfinder-web-react';

import storage from '@kode-frontend/pathfinder-web-local-storage';
import { openApiResolver } from '@kode-frontend/pathfinder-web-open-api';

type Props = {
  children: React.ReactNode,
};

export const PathfinderProvider = ({ children }: Props) => {
  return (
    <Pathfinder
      children={<>{children}</>}
      resolver={openApiResolver}
      storage={storage}
      active={process.env.NODE_ENV !== 'production'}
      dataKey={'pathfinder-storage-key'}
    />
  );
};

// dataKey - The key witch will use for storing pathfinder data. It can use for versioning storage by with app version.

Import PathfinderProvider and render it around your whole app:

import { PathfinderProvider } from './pathfinder';

const App = () => {
  return (
    <PathfinderProvider>
      <div>your app</div>
    </PathfinderProvider>
  );
};

Usage

1. Run your project.

During local development (process.env.NODE_ENV !== 'production') you will see a button with gears in the bottom right of the screen. When clicking it the Pathfinder UI panel appears.

2. Upload your OpenAPI 3.0 Specification file from Stoplight.
3. Configure the base paths for all requests or only for the required ones.

Development

Plop.js

There is a plop.js tool to create ui-component using a template. You need to set up extension to create components quickly. After the extension installation you should follow these 2 steps:

1. Create a new folder for your ui-component;
2. Click on the New File from Template in the context menu.

Use it for quick component creation without mistakes.

Example

Clone repository and install dependencies:

git clone https://github.com/appKODE/pathfinder-web-open-api.git

npm i

# or using yarn
yarn

TSDX scaffolds Pathfinder inside /src, and also sets up a Parcel-based playground for it inside /example.

The recommended workflow is to run TSDX in one tab of your terminal:

npm start

# or using yarn
yarn start

This builds to /dist and runs the project in watch mode so any edits you save inside /src causes a rebuild to /dist.

Then run the example playground in another tab of your terminal:

# go to /example
cd example

# install dependencies and run create-react-app dev server
npm i && npm start

# or using yarn
yarn && yarn start

Now, anytime you make changes to your library in /src or to the example app's /src, create-react-app will live-reload your local dev server so you can iterate on your component in real-time.

TODO

• [x] replace css modules with styled components
• [ ] add storybook
• [ ] refactor components
• [ ] add usage examples

License

MIT ©

There is plop.js tool to create ui-component using a template. You need to set up to create components quickly. After an extension installing you should follow next 2 steps:

1. Create new folder for ui-component;
2. Click on New File from Template in context menu.

Use it for quick component creating without mistakes.