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.
npm i @kode-frontend/pathfinder-web
# or using yarn
yarn add @kode-frontend/pathfinder-web
Pathfinder is intended to be paired with a storage adapter and an OpenAPI resolver, which can be fully customized or installed as npm packages.
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.
- 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.
Create a new provider component with Pathfinder. Import storage
and openApiResolver
from this 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,
openApiResolver,
storage,
} from '@kode-frontend/pathfinder-web';
// Optional initial specifications
import spec1 from 'path/to/json';
import spec2 from 'path/to/json';
type Props = {
children: ReactNode,
};
export const PathfinderProvider = ({ children }: Props) => {
return (
<Pathfinder
dataKey={`some string`}
storage={storage}
resolver={openApiResolver}
active={process.env.NODE_ENV !== 'production'}
// Optional initial specifications
defaultSpecs={[spec1, spec2]}
>
{children}
</Pathfinder>
);
};
// 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>
);
};
- 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.
- Upload your OpenAPI 3.0 Specification file from Stoplight.
- Configure the base paths for all requests or only for the required ones.
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:
- Create a new folder for your ui-component;
- Click on the
New File from Template
in the context menu.
Use it for quick component creation without mistakes.
Clone repository and install dependencies:
git clone https://github.com/appKODE/pathfinder-web
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.
- replace css modules with styled components
- add storybook
- refactor components
- add usage examples
- add multy specification files support
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:
- Create new folder for ui-component;
- Click on
New File from Template
in context menu.
Use it for quick component creating without mistakes.